Separate artifact identity from registry coordinates

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

@@ -0,0 +1,104 @@
+# 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, a registry 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.
+
+A registry uses a stateful preserve-or-mint policy:
+
+1. If the registry previously published an identifier for the artifact,
+   reuse it, even if another identifier becomes available later.
+2. Otherwise, if the source entry contains a publisher-authorized
+   `urn:air` identifier, preserve it exactly.
+3. Otherwise, the registry may preserve or replace a non-`urn:air` source
+   identifier. Non-`urn:air` identifiers have no guaranteed portability
+   across catalogs.
+4. When assigning a new identifier, a registry that becomes the artifact
+   publisher should use `urn:air` with its own domain in the `{publisher}`
+   segment. A registry acting as an authorized delegate should use
+   `urn:air` with the delegating publisher's domain in that segment. An
+   independent registry must use a non-`urn:air` identifier under its own
+   control.
+
+Merely hosting or aggregating an entry does not make a registry the
+artifact publisher.
+
+Changing a previously published primary identifier requires an explicit
+migration mechanism, which this decision does not define.
+
+The registry assigning an identifier, the catalog `host`, and the
+artifact `publisher` are independent roles. A registry-issued identifier
+does not imply that the registry published the artifact.
+
+A registry may retain replaced source identifiers or registry-native
+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
+  registries and mirrors.
+- Non-`urn:air` identifiers remain valid, but registries may replace them
+  when they are unsuitable for the destination catalog.
+- Legacy records can be projected without publisher enrollment by using
+  a registry-issued identifier.
+- Two registries 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; native 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 registry 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 incorporating an entry for the first time with a publisher-authorized `urn:air` identifier MUST preserve that identifier exactly.
 
-    **Standard Naming Format:**
+    **AI Catalog Publisher Naming 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 [Registry Projection](#registry-projection) for identifiers assigned while projecting an existing registry.
 
 `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 [Registry Projection](#registry-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,72 @@ 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.
 
+## Registry 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.
+
+A registry creating an entry from an existing record or catalog entry
+MUST select its primary identifier by applying these rules in order:
+
+1. If the registry previously published an identifier for the artifact,
+   it MUST reuse that identifier, even if another identifier becomes
+   available later.
+2. Otherwise, if the source entry contains a publisher-authorized
+   `urn:air` identifier, it MUST preserve the identifier exactly.
+3. Otherwise, the registry MAY preserve a non-`urn:air` source identifier
+   or replace it. Non-`urn:air` identifiers have no guaranteed portability
+   across catalogs.
+4. When assigning a new identifier, a registry that becomes the artifact
+   publisher SHOULD use `urn:air` with its own domain in the `{publisher}`
+   segment. A registry acting as an authorized delegate SHOULD use
+   `urn:air` with the delegating publisher's domain in that segment. An
+   independent registry MUST use a non-`urn:air` identifier under its own
+   control.
+
+Merely hosting or aggregating an entry does not make a registry the
+artifact publisher.
+A registry 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.
+
+A registry-assigned identifier identifies the artifact, not a particular
+version or registry record. It MUST remain stable across
+versions, registry-coordinate changes, and retrieval-URL changes, and
+MUST NOT be reassigned to another artifact. The registry assigning the
+identifier, the catalog `host`, and the artifact `publisher` are
+independent roles.
+
+A registry MAY retain replaced source identifiers or registry-native
+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.