diff --git a/README.md b/README.md index e429d7b..13e9568 100644 --- a/README.md +++ b/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: diff --git a/doc/tea-uuid-scope.md b/doc/tea-uuid-scope.md new file mode 100644 index 0000000..ce1ff6a --- /dev/null +++ b/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:::`); 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.