Merge pull request #245 from relizaio/2026-05-issue-217-uuid-documentation

docs: TEA UUID Scope and Stability (#217)

Author: oej

README.md

@@ -67,6 +67,8 @@ The working group has produced a list of use cases and requirements for the prot
 - [TEA Collection](tea-collection/tea-collection.md): A versioned list of artefacts for a specific Release (Component Release) or Product Release. Collections are versioned to indicate changes, e.g., an updated VEX or corrected SBOM.
 - [TEA Artifacts](tea-artifact/tea-artifact.md): Files associated with a Collection. A single TEA Artifact can appear in multiple Collections. Note that a TEA Artifact is a named term introduced by the TEA standard.
 
+See [TEA UUID Scope and Stability](doc/tea-uuid-scope.md) for uniqueness and stability rules that apply to all UUIDs in the data model above.
+
 ## Artefacts available of the API
 
 The Transparency Exchange API (TEA) supports publication and retrieval of a set of transparency exchange artefacts. The API itself is not restricting the types of the artefacts published. A few examples:

doc/tea-uuid-scope.md

@@ -0,0 +1,27 @@
+# TEA UUID Scope and Stability
+
+This document defines the scope of uniqueness and the stability guarantees of UUIDs used by TEA objects (TEA Product, TEA Product Release, TEA Component, TEA Release, TEA Collection, TEA Artifact).
+
+## Uniqueness scope
+
+A TEA UUID alone is **not** globally unique. Global uniqueness in TEA is achieved by the tuple:
+
+```text
+authoritative domain  +  object type  +  UUID
+```
+
+- The **authoritative domain** is supplied by the TEI (`urn:tei:<type>:<domain-name>:<unique-identifier>`); see [discovery](../discovery/readme.md). TEA itself has no centralized authority that can police UUIDs across servers, so cross-server uniqueness is not enforceable and is not claimed.
+- The **object type** scopes uniqueness to a single object class (Product, Product Release, Component, Release, Collection, Artifact). A TEA server MUST guarantee that UUIDs are unique within `(authoritative domain, object type)`. UUIDs are not required to be unique across object types.
+
+The per-object-type scoping reflects how TEA servers are typically implemented: each object type lives in its own database table, where uniqueness is trivially enforced by a primary key. Cross-table uniqueness offers no functional benefit - TEA has no operation that resolves a UUID without already knowing its object type.
+
+Implementations MAY use generators that produce globally unique UUIDs (e.g. RFC 4122). Doing so neither violates nor strengthens this specification.
+
+## Stability
+
+All TEA UUIDs MUST be stable for the lifetime of the resource they identify, within a given TEA server. Specifically:
+
+- A UUID MUST NOT be reassigned to a different resource.
+- A UUID MUST NOT change across backup/restore or re-hosting of the same TEA service instance.
+
+Stability is required for **all** TEA object types, not only TEA Product Release. While TEI resolution targets only Product Release UUIDs, clients routinely bookmark and cache sub-resource URLs (e.g. `/component/{uuid}`, `/release/{uuid}`, `/collection/{uuid}`); changing those UUIDs would silently break those clients.