Separate artifact identity from registry coordinates

adr/0021-separate-artifact-identity-from-registry-coordinates.md

@@ -0,0 +1,106 @@
+# ADR-0021: Separate Artifact Identity from Registry Coordinates
+
+**Status:** Proposed
+
+**Date:** 2026-08-26
+
+**Related:** [Issue #102](https://github.com/Agent-Card/ai-catalog/issues/102)
+
+**Supersedes if accepted:** The federated AIR requirement in
+[ADR-0015](0015-agent-identifier-naming.md)
+
+## Context
+
+Existing registries commonly identify artifacts with native coordinates,
+such as a registry namespace and artifact name. When projecting those
+records as AI Catalog entries, the catalog operator may have no
+publisher-assigned `urn:air` identifier.
+
+Using the registry's domain in `urn:air` is easy, but the current format
+defines that domain as the artifact publisher. Requiring the publisher's
+domain is portable, but prevents automatic projection when the publisher
+has not supplied or authorized an identifier.
+
+The existing model already separates most roles: `publisher` identifies
+the artifact publisher, `host` identifies the catalog operator, `url`
+locates the artifact, and `extensions` can preserve registry-specific
+coordinates.
+
+## Decision
+
+`entry.identifier` identifies the artifact represented by the entry and
+remains stable across versions. A publisher-authorized `urn:air`
+identifier is also portable across catalog locations. Other
+identifier schemes remain valid but have no cross-catalog portability
+guarantee. Consumers that do not recognize an identifier scheme treat
+the value as opaque. Identifier syntax alone does not verify publisher
+identity or establish trust.
+
+The base format does not require a particular identifier scheme. A
+globally unique absolute URI is recommended for open or federated use.
+An artifact publisher that wants an identifier to be preserved when the
+artifact appears in other catalogs should use the AI Catalog-specific
+`urn:air` format in a namespace it controls.
+
+A publisher-authorized `urn:air` identifier is one assigned by the
+artifact publisher or its authorized delegate, with the artifact
+publisher's domain in the `{publisher}` segment.
+
+Catalog projection creates a Catalog Entry from either a source Catalog
+Entry in another AI Catalog or a source record in another system. When
+incorporating a projected entry for the first time, a catalog operator
+selects its identifier by applying these rules in order:
+
+1. If the source contains a publisher-authorized `urn:air` identifier,
+   preserve it exactly.
+2. Otherwise, the operator may preserve a non-`urn:air` source identifier
+   or replace it. Non-`urn:air` identifiers have no guaranteed portability
+   across catalogs.
+3. When assigning a new identifier, an operator that becomes the artifact
+   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
+   delegate must use a non-`urn:air` identifier under its own control.
+
+Operating a catalog or aggregating an entry does not make its operator the
+artifact publisher.
+
+Changing a previously published primary identifier requires an explicit
+migration mechanism, which this decision does not define.
+
+The catalog operator and artifact publisher are distinct roles. An
+operator-assigned identifier does not imply that the operator published
+the artifact.
+
+A catalog operator may retain replaced source identifiers or source-system
+coordinates. When retained, they should be stored in a namespaced entry
+extension. They do not affect catalog uniqueness or establish publisher
+identity, trust, or equivalence with another identifier.
+
+## Consequences
+
+- Publisher-authorized `urn:air` identifiers are preserved across
+  catalogs and mirrors.
+- Non-`urn:air` identifiers remain valid, but catalog operators may preserve
+  or replace them.
+- Legacy records can be projected without publisher enrollment by using
+  an operator-assigned identifier.
+- Two catalog operators may assign different identifiers to the same
+  artifact when no publisher-authorized `urn:air` identity is available.
+  The model does not claim equivalence it cannot establish.
+- No new core field is added; source-system coordinates use `extensions`.
+- Generic aliases and primary-identifier migration remain future work.
+
+## Alternatives Considered
+
+Always using a registry-domain `urn:air` was rejected because it makes the
+registry appear to be the artifact publisher under the current format.
+
+Requiring a publisher-domain `urn:air` was rejected as a universal rule
+because it makes automatic projection depend on publisher enrollment.
+
+Adding `aliases`, `nativeIdentifier`, or `identifiers[]` was deferred
+because source-system coordinates do not necessarily assert logical
+identity equivalence, and `extensions` is sufficient for the immediate
+use case.

specification/ai-catalog.md

@@ -203,9 +203,9 @@ A Catalog Entry object describes a single AI artifact in the catalog.
 It MUST contain the following members:
 
 `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. An artifact publisher that wants an entry identifier to be preserved when the artifact appears in other catalogs SHOULD use the AI Catalog-specific `urn:air` naming structure with its own domain in the `{publisher}` segment. A catalog operator incorporating an entry for the first time with a publisher-authorized `urn:air` identifier MUST preserve that identifier exactly.
 
-    **Standard Naming Format:**
+    **`urn:air` Identifier Format:**
     `urn:air:{publisher}:{namespace}:{name}`
 
     - `{publisher}`: The domain name of the organization publishing the artifact (e.g., `example.com`).
@@ -219,7 +219,7 @@ It MUST contain the following members:
 
     For closed or local systems where a different identifier format is used, client implementations are responsible for parsing and processing the custom format as appropriate.
 
-    See [Multi-Version Entries](#multi-version-entries) for uniqueness rules when multiple versions are present.
+    See [Multi-Version Entries](#multi-version-entries) for uniqueness rules when multiple versions are present, and [Catalog Projection](#catalog-projection) for identifiers assigned while projecting an existing Catalog Entry or source-system record.
 
 `type`
 : A string containing the identifier that specifies the type of the
@@ -433,9 +433,9 @@ single artifact — similar to a package registry.
 
 When `version` is present, the combination of `identifier` and `version`
 MUST be unique within the catalog. When `version` is absent, `identifier`
-alone MUST be unique. The `identifier` SHOULD be stable across versions
-and catalog locations so that the same logical artifact can be
-recognized wherever it appears.
+alone MUST be unique. The `identifier` SHOULD be stable across versions.
+Only publisher-authorized `urn:air` identifiers receive a cross-catalog
+preservation requirement, as defined in [Catalog Projection](#catalog-projection).
 
 Clients that need only the latest version SHOULD sort entries
 sharing the same `identifier` by `version` (when parseable as a semantic
@@ -469,6 +469,73 @@ For example, a catalog listing two versions of the same agent:
 Both entries share the same `identifier` but have distinct `version`
 values, so the combination is unique.
 
+## Catalog Projection
+
+A publisher-authorized `urn:air` identifier is one assigned by the
+artifact publisher or its authorized delegate, with the artifact
+publisher's domain in the `{publisher}` segment.
+
+Catalog projection creates a Catalog Entry from either a source Catalog
+Entry in another AI Catalog or a source record in another system. When
+incorporating a projected entry for the first time, a catalog operator
+MUST select its identifier by applying these rules in order:
+
+1. If the source contains a publisher-authorized `urn:air` identifier,
+   the operator MUST preserve it exactly.
+2. Otherwise, the operator MAY preserve a non-`urn:air` source identifier
+   or replace it. Non-`urn:air` identifiers have no guaranteed portability
+   across catalogs.
+3. When assigning a new identifier, an operator that becomes the artifact
+   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
+   delegate MUST use a non-`urn:air` identifier under its own control.
+
+A projected entry that uses `urn:air` and includes a Trust Manifest remains
+subject to the trust-domain alignment requirements in [Identity](#identity).
+
+Operating a catalog or aggregating an entry does not make its operator the
+artifact publisher. A catalog operator MUST NOT infer publisher
+authorization from the artifact's URL or an unsigned `publisher` field.
+
+Adopting a different primary identifier after publication requires an
+explicit migration mechanism, which this specification does not define.
+
+An identifier assigned by a catalog operator identifies the artifact, not
+a particular version or source record. It MUST remain stable across
+versions, source-coordinate changes, and retrieval-URL changes, and MUST
+NOT be reassigned to another artifact. The catalog operator and artifact
+publisher are distinct roles. The operator is the entity identified by the
+top-level `host` field when that field is present.
+
+A catalog operator MAY retain replaced source identifiers or source-system
+coordinates. If retained, they SHOULD be stored in a namespaced entry
+extension. They do not participate in catalog uniqueness or establish
+publisher identity, trust, or equivalence with another identifier.
+
+```json
+{
+  "identifier": "https://registry.example/ids/artifacts/7bf4a8c2",
+  "type": "application/a2a-agent-card+json",
+  "url": "https://registry.example/apis/registry/v3/groups/payments/artifacts/fraud-agent",
+  "publisher": {
+    "identifier": "did:web:acme.example",
+    "displayName": "Acme"
+  },
+  "extensions": {
+    "com.example.registry.coordinates": {
+      "registryUri": "https://registry.example",
+      "sourceIdentifier": "foo",
+      "namespace": "payments",
+      "name": "fraud-agent"
+    }
+  }
+}
+```
+
+The extension key is illustrative.
+
 ## Publisher Object
 
 The Publisher object identifies the entity responsible for an artifact.