Separate artifact identity from registry coordinates - #105
Separate artifact identity from registry coordinates#105jonathanhefner wants to merge 3 commits into
Conversation
Clarify how a registry creates AI Catalog entries for existing artifacts that lack publisher-assigned `urn:air` identifiers. Preserve authorized publisher identifiers when available; otherwise assign and persist a registry-controlled identifier without conflating the registry with the artifact publisher. Keep native registry coordinates in namespaced `extensions`, treat unrecognized schemes as opaque, and defer identifier migration rather than silently changing published identifiers.
|
|
||
| `identifier` | ||
| : A string uniquely identifying this artifact. This field is an open text format (e.g., any valid URI or URN is accepted). However, to ensure interoperability, identity uniqueness, and discoverability, the standard `urn:air` naming structure is **HIGHLY RECOMMENDED** and **MUST** be used for open or federated systems. | ||
| : A string uniquely identifying this artifact. This field is an open text format (e.g., any valid URI or URN is accepted). Consumers that do not recognize an identifier scheme MUST treat the value as opaque. Identifier syntax alone does not verify publisher identity or establish trust. For open or federated systems, a globally unique absolute URI is RECOMMENDED. The `urn:air` naming structure is RECOMMENDED when the publisher assigns an identifier in a namespace it controls. |
There was a problem hiding this comment.
This is the main change to call out. From:
the standard
urn:airnaming structure is HIGHLY RECOMMENDED and MUST be used for open or federated systems
to:
For open or federated systems, a globally unique absolute URI is RECOMMENDED. The
urn:airnaming structure is RECOMMENDED when the publisher assigns an identifier in a namespace it controls.
The rationale being: federated registries should not invent a urn:air identifier for a publisher when the publisher hasn't provided such an identifier for a legacy artifact. See #102 for more info.
Define publisher-authorized `urn:air` identifiers as the portable form
that catalogs preserve on first incorporation, while allowing registries
to preserve or replace non-AIR identifiers.
Distinguish registries acting as artifact publishers, authorized
delegates, and independent hosts; specify the corresponding
`{publisher}` segment rules; and make retention of replaced source
identifiers optional in namespaced `extensions`.
| artifact publisher or its authorized delegate, with the artifact | ||
| publisher's domain in the `{publisher}` segment. | ||
|
|
||
| A registry creating an entry from an existing record or catalog entry |
There was a problem hiding this comment.
existing record
Does this mean a record in a non-ai-catalog registry/market place?
| } | ||
| ``` | ||
|
|
||
| The extension key is illustrative. |
There was a problem hiding this comment.
As we're aware that AI catalog is designed for federation, do you think it makes sense to formalise a native/official extension for federation source / entry origin?
This could then be used to build chain of origin if someone wants to find the normative source of a entry, e.g. resolve the entry origin then check that entries origin until you find an entry with no origin.
There was a problem hiding this comment.
I pushed a commit to address the other comments, but I think this comment should be addressed in a separate PR if we want to pursue it.
Frame identifier selection as catalog projection performed by a catalog operator, rather than only as registry behavior, and distinguish source Catalog Entries from source-system records. Name the `urn:air` identifier format explicitly and scope the ordered selection rules to first incorporation so later source changes remain governed by identifier stability rather than implicit artifact-equivalence assumptions.
Tehsmash
left a comment
Tehsmash
left a comment
There was a problem hiding this comment.
Thanks for the update, after this the wording LGTM.
I agree we can discuss the origin extension as a separate issue to be added later and standardised.
| publisher SHOULD use `urn:air` with its own domain in the `{publisher}` | ||
| segment. An operator acting as an authorized delegate SHOULD use | ||
| `urn:air` with the delegating publisher's domain in that segment. An | ||
| operator that is neither the artifact publisher nor its authorized |
There was a problem hiding this comment.
It would be helpful to note how publisher delegate/operator-assigned identifiers interact with the trust domain validation requirements in section 5.1.
Specifically:
When a Trust Manifest appears within a Catalog Entry, the identity field's trust domain MUST align with the publisher domain in the containing entry's identifier field
When an operator assigns a urn:air, it must still satisfy this domain alignment w/ trustManifest.identity.
3 participants
Summary
This PR proposes a resolution to #102 for existing registries that need to create AI Catalog entries for artifacts without publisher-assigned
urn:airidentifiers.Publisher-controlled
urn:airidentifiers remain recommended when available, but are no longer required when a registry cannot construct one truthfully.Changes Included
Added ADR-0021 which documents a stateful preserve-or-mint policy for registries:
Updated the core specification:
extensionsvalueMotivation
Requiring every federated entry to use
urn:air:{publisher}:...leaves existing registries with two problematic choices: present the registry as the artifact publisher, or require publisher enrollment before exposing legacy records.The proposed preserve-or-mint policy avoids both outcomes. It preserves publisher-controlled identifiers when available while allowing existing records to be exposed without inventing publisher authority. Native registry coordinates remain available for lookup and round trips without being treated as portable artifact identities.
No new core JSON field is required or introduced.
Scope
This PR intentionally does not change Trust Manifest behavior or define generic aliases and primary-identifier migration. It also leaves distribution-mapping corrections and AIR namespace registration to separate work.
AI usage disclosure: This PR was drafted with the assistance of AI under my direct supervision and scrutiny.
Closes #102