Skip to content

Clarify AIR portability and registry identifier selection - #3

Merged
jonathanhefner merged 1 commit into
agent/issue-102-registry-identifier-guidancefrom
agent/issue-102-portability-clarifications
Aug 27, 2026
Merged

Clarify AIR portability and registry identifier selection#3
jonathanhefner merged 1 commit into
agent/issue-102-registry-identifier-guidancefrom
agent/issue-102-portability-clarifications

Conversation

@jonathanhefner

@jonathanhefner jonathanhefner commented Aug 27, 2026

Copy link
Copy Markdown
Owner

Summary

  • define publisher-authorized urn:air identifiers by who assigned them and whose domain appears in the {publisher} segment
  • require a catalog incorporating an entry for the first time to preserve a publisher-authorized urn:air identifier exactly
  • allow registries to preserve or replace non-urn:air source identifiers, which have no portability guarantee
  • distinguish a registry becoming the artifact publisher, acting as an authorized delegate, and acting as an independent host
  • make retention of replaced source identifiers optional and keep namespaced extensions as their proper location when retained

Motivation

This follows the maintainer discussion of upstream PR Agent-Card/ai-catalog#105.

The original policy did not clearly distinguish a portable publisher identifier from an identifier that is valid only within its source catalog. For example, a publisher may use local identifiers such as foo and bar; a registry combining entries from several publishers must be able to assign globally scoped identifiers to avoid conflicts.

This revision keeps urn:air optional but gives publisher-authorized urn:air identifiers a specific interoperability benefit: a catalog must preserve one when it first incorporates the entry. A registry may preserve or replace other identifiers at its discretion, but they receive no cross-catalog portability guarantee.

The assignment rules also identify the domain used in the AIR {publisher} segment: a registry that becomes the artifact publisher uses its own domain, while an authorized delegate uses the delegating publisher domain. Merely hosting or aggregating an entry does not make a registry its publisher, so an independent host must use a non-urn:air identifier under its own control when it assigns a replacement.

Review focus

  • the publisher-directed recommendation and host-side preservation rule in the Catalog Entry identifier definition
  • the ordered decision rules in ADR-0021 and Registry Projection
  • the definition of a publisher-authorized urn:air identifier
  • the separation between publisher, authorized-delegate, and independent-host roles
  • optional retention of replaced source identifiers in namespaced extensions

Validation

  • .venv/bin/mkdocs build --strict --site-dir /tmp/ai-catalog-issue-102-portability-site
  • .venv/bin/python tools/build_spec.py specification/ai-catalog.md /tmp/ai-catalog-issue-102-portability-spec.html
  • git diff --check

Comment thread adr/0021-separate-artifact-identity-from-registry-coordinates.md Outdated
Comment thread adr/0021-separate-artifact-identity-from-registry-coordinates.md Outdated
Comment thread adr/0021-separate-artifact-identity-from-registry-coordinates.md Outdated
Comment thread adr/0021-separate-artifact-identity-from-registry-coordinates.md Outdated
Comment thread specification/ai-catalog.md Outdated
Comment thread specification/ai-catalog.md Outdated
Comment thread specification/ai-catalog.md
Comment thread specification/ai-catalog.md Outdated
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`.
@jonathanhefner
jonathanhefner force-pushed the agent/issue-102-portability-clarifications branch from 45720c3 to 0c8b58d Compare August 27, 2026 18:53
@jonathanhefner
jonathanhefner marked this pull request as ready for review August 27, 2026 18:54
@jonathanhefner
jonathanhefner merged commit b69d2b9 into agent/issue-102-registry-identifier-guidance Aug 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant