Clarify scope of all our UUIDs

[oej]

We need to clarify the scope of each UUID - are they globally Unique in a TEA server implementation? If I move my TEA service from one server to another - should I preserve UUIDs?

[mrutkows]

Hearing the UUIDs are not really "universal" on the TG` call today, which means it is not really a a UUID... But instead if iut is relative to a "domain" then... The definition of the "domain" for a UUID will need to be considered relative to CDX 2.0 schema which will have a "classification" object for use with external references, but would also apply to this.

IMO, a UUID is a UUID (universal)... period. This should be the position and clarified as to which version UUID(s) are supported.

[taleodor]

I may be paranoid, but my approach is to have UUID unique within a single TEA server and within specific object scope (i.e. namespacing by components, component releases, etc - such that each object within the namespace is guaranteed to have unique UUID within the namespace).

This approach allows to have strong uniqueness guarantees via implementation side. I don't think we should pursue universal uniqueness, i.e. see here - https://alexsci.com/blog/uuid-oops/

[Mehrn0ush]

@mrutkows I agree that the term “UUID” carries an expectation of RFC 4122 semantics unless we explicitly define otherwise.
@taleodor I agree the collision / generator-quality concern is real — but it seems better handled by tightening generation guidance, rather than weakening identifier semantics.

Uniqueness scope vs. stability

There are two independent questions here:

• Uniqueness scope: where is a UUID guaranteed unique — within a single TEA service instance (the logical authority/dataset), or across TEA instances?
• Stability: does the same logical resource keep the same UUID over time and across lifecycle events (backup/restore, re-hosting)?

An identifier can be “local to a TEA service instance” and still be stable. The key limitation of local scope is cross-instance portability, not instability per se.

One terminology note: “server-scoped” can be read as “unique per physical server”. In practice the boundary that matters is the TEA service instance / dataset authority (which may be a clustered deployment), not a single machine.

Practical impact on TEA clients

• UUIDs are embedded in resource URLs (e.g. /product/{uuid}, /release/{uuid}). People will bookmark and share these, and clients will cache them — which creates an expectation that identifiers remain valid for the lifetime of the resource.
• TEA is starting to use UUIDs as cross-object reference keys (e.g. distributionId in Use distributionId instead of distributionType to identifiy disributions #215 mapping artifacts → distributions). At that point UUID semantics become a referential-integrity issue, not just an internal implementation detail.

The discovery endpoint makes the portability tradeoff explicit

TEA already supports TEI → per-instance UUID resolution via /discovery. That’s useful, but it also makes the design choice very concrete:

• If UUIDs are only unique within a TEA service instance, the same TEI can legitimately resolve to different UUIDs on different TEA instances (even if they represent the same logical resource).
• In that model, clients that need portability must persist TEI and re-resolve UUID per instance/provider; persisting UUID alone is not sufficient across instances.

That can be a valid model — it just needs to be stated explicitly so clients know whether UUIDs are portable identities or instance-local handles.

Options and tradeoffs

A) RFC 4122 UUIDs as durable resource identifiers (global intent + stable)

Semantics: UUIDs identify the logical resource; intended to be globally unique in the RFC 4122 sense (probabilistic uniqueness) and stable across backup/restore and re-hosting.

Benefits

• Matches typical expectations of “UUID”.
• Clients can store UUIDs and safely reuse them across lifecycle events.
• Cross-object joins (artifact → distribution via distributionId, etc.) remain robust.
• Makes federation/merging across TEA instances far simpler (no composite keys/remapping layers).

Costs

• Implementations must treat UUIDs as durable identifiers (avoid regeneration on import/restore).
• Collision risk – with properly implemented RFC 4122 generators (e.g., CSPRNG‑based v4 or standards‑compliant v7), the probability of collision is negligible for all practical purposes. The only meaningful risk comes from weak or non‑compliant generation – exactly the kind of “UUID oops” pitfall we can mitigate by specifying clear generator requirements.

B) UUIDs unique only within a TEA service instance (instance-local; stability may exist, portability is limited)

Semantics: UUIDs are guaranteed unique within a single TEA service instance. They may be stable within that instance (including re-hosting of that same instance), but are not guaranteed unique across TEA instances.

Benefits

• Fine for single-provider / single-instance deployments.
• Works naturally with /discovery if clients store TEI and resolve per instance.

Costs

• Even if UUIDs are stable within an instance, cross-instance portability is still broken: two TEA instances can legitimately use the same UUID for different resources, or represent the same logical resource under different UUIDs.
• External systems interacting with multiple TEA instances can’t treat UUID alone as durable identity.
• Aggregation/merging needs namespacing (e.g. {issuer/serviceInstanceId, uuid}) or a strict “TEI + discovery” approach.

C) Hybrid (instance-local UUID + explicit global identifier)

Architecturally strong for multi-provider and provenance, but it expands the spec surface and pushes more complexity onto clients.

Generation quality (collision risk and privacy)

If UUIDs remain in the spec, it’s worth stating generator expectations:

• UUIDs SHOULD be generated using CSPRNG-based UUIDv4 or a standards-compliant UUIDv7 generator.
• Because UUIDs are used in URLs, predictable or low-entropy IDs can make resource enumeration easier in practice; strong randomness materially reduces that risk.
• UUIDv1 SHOULD NOT be used due to timestamp/MAC privacy leakage; UUIDv7 provides ordering without those exposures.

Can we make UUID scope/stability explicit in the spec?
If the community agrees we should resolve the ambiguity, could we make the spec wording explicit about the chosen model and update phrasing like “UUID … in the TEA server” so it doesn’t imply the wrong scope?

For example, if we lean toward Option A, we could add:

All UUID fields MUST be RFC 4122 UUIDs and MUST remain stable for the lifetime of the logical resource, including across backup/restore and re-hosting. UUIDs SHOULD be generated using a CSPRNG (v4) or a compliant UUIDv7 generator.

If Option B feels more appropriate, we could instead say:

UUIDs are unique within a TEA service instance only; clients MUST treat them as instance-local handles and use TEI + discovery for durable identity across instances.

(And then define the service-instance identity/namespace concept needed for cross-instance reference.)

[taleodor]

@Mehrn0ush I'd appreciate that if you bring AI into conversation, you

1. Give clear attribution to which parts are AI generated
2. Try to limit the size of the response

This is because we're perfectly capable to engage AI if something is not clear and we need to expand on points. Also the issue with AI here is that AI is trying to base concepts on its existing knowledgebase, while we're trying to build something new here.

Now, for your concerns, I'll expand:

TEA is a distributed system, there is no centralized authority that will or even can police UUIDs. If a malicious actor wants to create duplicate UUIDs, there is nothing to stop them.

Therefore, TEI contains "authoritative domain" part. Combination of authoritative domain + UUID is what creates global uniqueness, rather than UUID itself. For clarification, please read the discovery docs and watch any of my TEA talks on the TEI part, i.e. @OWASP Global AppSec USA 2025.

Now, why I want to further tighten scope to authoritative domain + object type + UUID - purely for practical implementation reasons. Usually, a single object type lives in its own table in the database. Enforcing UUID uniqueness is easy this way. If you try to enforce uniqueness across tables, this becomes much more difficult problem. And I believe there is no benefit in that, as we have no plans to resolve a UUID into object type + object. There is always expectation that you know object type alongside UUID. So practically, I believe this is the most reasonable approach. With that, if you want, you can still have globally unique UUIDs in your specific implementation - it won't break anything, but it also doesn't bring any real benefits.

[Mehrn0ush]

@taleodor Thanks for the note — understood on attribution/size.

I didn’t use AI to generate my comment. I tried to compress my own takeaways from reading the repo/spec and yesterday’s discussion into one message to help the decision converge faster. I’ll keep future replies shorter.

got it. UUID uniqueness being scoped to (authoritative domain + object type + UUID) sounds practical (per-table constraints), and TEI (domain + UUID) remains the portable/global identifier via /discovery.

One question: within a single TEA service instance, should UUIDs be stable across backup/restore or re-hosting of the same instance? If yes, it may be worth stating explicitly; otherwise bookmarks/cached references will break.

[ppkarwasz]

@Mehrn0ush,

Note that TEIs can only be created for a TEA Product Release object. Therefore for those objects UUIDs must be stable.

For other object types they also should be stable, so we can query the server for new product/component releases or new versions of the TEA collection associated to a product/component release.

[taleodor]

I agree with @Mehrn0ush 's point here - I think we should require all UUIDs within the TEA server to be stable. As even though resolution only happens via TEA Product Release, clients may bookmark underlying endpoints as well for future calls and this would break things if those UUIDs ever change.

[oej]

Need to document this