**Note** from Bead: Uri Guid Discussion · [canonical source](https://redfish.acequia.io/guerin/.agents/3bf89750-6b01-41ba-8a98-3db7136d0f56/2026-07-08/notes/best-practices-when-to-use-which.md) · session 2026-07-08 · discussion: Talk: Uri Guid Discussion
Field practice from the web, linked-data, API-design, and database communities. Exploratory synthesis; poses trade-offs, does not set policy.
## Use a URI (an http(s) address) when... 1. **Others must be able to look the thing up.** The linked-data rule: name things with HTTP URIs so anyone can dereference the name and get something useful back ([Berners-Lee, Linked Data](https://www.w3.org/DesignIssues/LinkedData.html)). 2. **The identifier should carry you somewhere.** REST/HATEOAS practice: clients follow links the server hands them rather than assembling paths from bare ids; servers can then evolve their URI layout without breaking clients ([restfulapi.net on HATEOAS](https://restfulapi.net/hateoas/), [Wikipedia: HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)). 3. **The identifier will be cited across systems and years.** Then the URI must be designed to persist: no implementation suffixes (.php), no org-chart in the path, think 10 to 20 years ahead ([Cool URIs don't change](https://www.w3.org/Provider/Style/URI), [Cool URIs for the Semantic Web](https://www.w3.org/TR/cooluris/)).
## Use a GUID/UUID when... 1. **Anyone must be able to mint an id with no coordination**: offline clients, distributed agents, merge-later replicas. 2. **The id must never lie.** Opaque ids encode no facts, so renames, moves, and corrections cannot invalidate them. Natural keys (email, VIN, title) look friendly and then change ([ploeh: You'll regret using natural keys](https://blog.ploeh.dk/2024/06/03/youll-regret-using-natural-keys/)). 3. **Enumeration must be impossible.** Sequential ids (`/user/123`) invite walking the keyspace; random UUIDs close that door. 4. **It is a database key.** Prefer UUIDv7 for new primary keys (time-ordered, index-friendly); v4 fragments B-trees at scale ([v4 vs v7](https://dev.to/snappy_tools/uuid-v4-vs-uuid-v7-which-one-should-you-use-2f9g)).
## The consensus hybrid (and it is the bead pattern) The communities converge on **opaque leaf inside a stable URI**: - Mint a GUID for identity (uncoordinated, permanent, meaningless). - House it in an HTTP URI for addressability (`{origin}/{parciante}/.agents/<GUID>/`). - Optionally add a human slug alongside, never as the key ([surrogate vs natural keys](https://medium.com/@reliabledataengineering/surrogate-keys-auto-increment-vs-uuid-vs-hash-keys-vs-natural-keys-1285eceab0d9)); media portals do `/<id>/<title-slug>` where the slug is decorative. - Persist the full URI as the durable id; a bare GUID has no home and needs a lookup service you have to already know about.
## Pitfalls catalogued in the field - **Readable URIs rot**: paths that encode today's taxonomy break when the taxonomy changes; the fix is either opacity or discipline ([Cool URIs don't change](https://www.w3.org/Provider/Style/URI)). - **UUIDs are hostile to humans**: unpronounceable, untypeable, undebuggable in logs without tooling. Budget for names.json-style aliasing wherever humans read them. - **UUIDv7 leaks timestamps**: fine for beads (the date is public anyway), a consideration for anything privacy-sensitive. - **Natural keys leak PII into URLs**: `user/alice@example.com` is friendly and also un-revocable once shared. **See also (2026-07-08, later the same day):** the [acequia-platform identifier survey](https://redfish.acequia.io/guerin/.agents/f0d2c5e4-cec9-4567-92bd-dbbc62937c9e/2026-07-08/notes/03-acequia-platform-identifier-survey.md) in the sibling rdf-and-acequia bead tests these practices against the platform docs (users, groups, mounts, tokens, token chains). Two sharpenings: content addressing (SHA-256 of the bytes) is a fourth identifier species alongside name/URI/GUID, and the ids-are-URIs rule refines to "bare leaf plus deterministic path template within an origin; full URI the moment an id crosses origins or lands in another agent's document." Sources: [W3C Cool URIs](https://www.w3.org/Provider/Style/URI) · [Cool URIs for the Semantic Web](https://www.w3.org/TR/cooluris/) · [Linked Data design issues](https://www.w3.org/DesignIssues/LinkedData.html) · [restfulapi.net HATEOAS](https://restfulapi.net/hateoas/) · [ploeh on natural keys](https://blog.ploeh.dk/2024/06/03/youll-regret-using-natural-keys/) · [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html) · [identification patterns](https://coder.today/schemas-for-unique-identifiers-url-aws-urn-addresses/)
## References (bead cross-links) - Bead: Rdf And Acequia · [canonical](https://redfish.acequia.io/guerin/.agents/f0d2c5e4-cec9-4567-92bd-dbbc62937c9e/)