spec: adopt `urn:air:` naming standard for AI artifacts (ADR 0015) by mindpower · Pull Request #36 · Agent-Card/ai-catalog

mindpower · 2026-05-13T18:01:18Z

This pull request introduces ADR 0015, proposaling a standardized, domain-anchored URN naming convention (urn:air:) for all AI actors and artifacts within the AI Catalog ecosystem. Evolving from the recommendations in PR #19, this proposal ensures global federation, consistent indexing, and industry-wide interoperability across registries and orchestrators.

📝 Summary of Changes

1. Architectural Decision Record: `adr/0015-agent-identifier-naming.md`

Formalized Naming Contract: Defines the universal URN structure: urn:air:{publisher}:{namespace}:{name}.
- publisher: The anchoring domain where the artifact is hosted (e.g., example.com).
- namespace: Optional, hierarchical segments separated by : (e.g., hr, finance, finance:agent, mcp, skill, catalog).
- name: The specific, distinguishing name of the artifact.
Separation of Concerns: Establishes a clear boundary between logical discovery names (the stable identifier URN) and cryptographic trust identities (the identity field in trustManifest, which may use DIDs, SPIFFE, x509, etc.).

2. Core Specification: `specification/ai-catalog.md`

Specification Text Update: Updated the identifier member definition to mandate the urn:air: format. (air->ai resource)
Example Alignment: Updated 38 example JSON blocks and narrative references across the specification to reflect the new standard, including:
- A2A Agent Cards (urn:air:acme.com:agent:finance)
- MCP Server Cards (urn:air:io.modelcontextprotocol.anonymous:mcp:brave-search)
- Nested & Hierarchical Catalogs (urn:air:acme.com:catalog:finance)
- Dual-Protocol (MCP + A2A) Wrappers (urn:air:acme.com:agent:finance:mcp)
- Security Typosquatting Scenarios (urn:air:acme.com:agent:financ vs urn:ai:acme.com:agent:finance)

Architectural Rationale:

Nomenclature Stability: The URN acts as an abstract, stable contract. Relocating workloads or changing underlying cloud infrastructure does not break client discovery or routing logic.
Global Uniqueness: Anchoring URNs to fully qualified domain names (FQDNs) guarantees cross-network uniqueness without central registration overhead.
Interoperability: Standardizing on urn:ai: allows centralized registries and decentralized crawlers to index, filter, and search AI artifacts uniformly.

⚠️ Reviewer Guidance & Stacked PR Note

Note to Reviewers: This pull request is stacked on top of #37

github-actions · 2026-05-13T18:02:10Z

Preview unavailable.

The pull request preview was removed because this pull request is closed.

muscariello · 2026-05-14T09:14:50Z

+
+## Proposal
+We will align the agent identifier naming in `ai-catalog.md` with the standards defined in [PR #19](https://github.com/Agent-Card/ai-catalog/pull/19).
+The `identifier` field MUST follow the URN format: `urn:{nid}:{publisher}:{namespace}:{name}`.


Is this a URN or a URI ?

Hi Luca, it is specifically a URN (which is a specific type of URI). While the previous draft allowed a mix of URNs and URIs, the latest update narrows this down to mandate a strictly formatted URN (starting with urn:).

This ensures that agent identifiers remain stable, location-independent handles, separating the logical name of the agent from its physical network location (which would be a URL) and the trust identity (SPIFFE/DID/DNS/etc).

So in summary:

Logical Discovery Identifier (CatalogEntry.identifier): Retains an abstract, domain-anchored URN namespace (e.g., urn:example:agent:name) to ensure permanent nomenclature stability and efficient indexing and discovery.

Pluggable Trust Identity (TrustManifest.identity): Supports various identity including SPIFFE IDs, DIDs, etc as a fully supported, first-class identity token for zero-trust enforcement and cryptographic verification.

Understood. So if my agent is running locally and I am using stdio or a file descriptor it's still a URN that I should use?

This is a good question. We can use "local" or "unknown" to indicate this is an unverifiable local agent (so publisher is not verifiable)

darrelmiller · 2026-05-14T16:33:29Z

+## Proposal
+We will align the agent identifier naming in `ai-catalog.md` with the standards defined in [PR #19](https://github.com/Agent-Card/ai-catalog/pull/19).
+The `identifier` field MUST follow the URN format: `urn:{nid}:{publisher}:{namespace}:{name}`.
+- `nid`: The Namespace Identifier (e.g., `agent`, `mcp`).


Making each ai artifact have its own nid is somewhat duplicative of having a type for each artifact. To adhere to the guidance of URNs and media types would require registering in two different IANA registries.

And if agent and mcp have two different nids, then there is no guarantee that the mcp nid will have publisher/namespace/name as the elements because the NID determines how the NSS is interpreted.

Would you be open to having aicatalog as the nid ?

These are valid concerns. Let's discuss about this in the meeting today.

darrelmiller · 2026-05-14T16:38:01Z

-    `application/agentskill+zip` for skill definitions)
+  - `application/mcp-server+json` — an MCP Server
+  - `application/ai-catalog+json` — a nested AI Catalog
+  - `application/agent-registry` — an Agent Registry search endpoint


I'm not sure how a type defines an endpoint? Is there other documentation for what this is?

This is the agent registry which is a rest based registry API (as proposed in #21). So by allowing to point to registries allow to further discover as well. But since we haven't discussed too much on registry here yet, I can remove that type from this PR.

It's just a url pointer

…ates

… marked as type under TrustManifest) during auto-merge

Documents the decision already implemented by this PR: displayName moves from a REQUIRED to an OPTIONAL member of a Catalog Entry and is dropped from the Minimal Catalog (Level 1) required-at-minimum set. Pairs each substantive spec PR with an ADR, matching ADR-0014 (Agent-Card#37) / ADR-0015 (Agent-Card#36). Status is Proposed pending the 2026-06-18 working-group call. Signed-off-by: Tadas Antanavicius <tadasant@users.noreply.github.com> Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jdamick · 2026-06-18T15:09:23Z

+To ensure global federation and industry-wide interoperability, we need a standardized, secure naming protocol for AI actors. However, we also need to preserve flexibility for organizations running local, private, or closed catalog instances that do not participate in public federation.
+
+## Decision
+We will define the `identifier` field as an open text format, while strongly recommending and standardizing the domain-anchored `urn:ai` scheme for open or federated ecosystems.


should this be urn:air here?

jdamick · 2026-06-18T15:09:42Z

-  [[RFC8141]] or URI [[RFC3986]] (e.g., `urn:example:agent:name`).
-  See [Multi-Version Entries](#multi-version-entries) for uniqueness
-  rules when multiple versions are present.
+: 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:ai` naming structure is **HIGHLY RECOMMENDED** and **MUST** be used for open or federated systems.


should this be urn:air here?

Thanks @jdamick . Updated.

…DR 0015) Align the MCP Catalog Entry `identifier` with the domain-anchored `urn:air:{publisher}:{namespace}:{name}` naming convention standardized in Agent-Card/ai-catalog#36 (ADR 0015), replacing the repo-local `urn:mcp:server:<name>` format. The MCP Catalog is documented as "a minimal, MCP-scoped subset of the AI Catalog specification" whose entries "can be used as-is within a full AI Catalog document" — a claim the old `urn:mcp:server:` format contradicted. Maps the Server Card reverse-DNS `name` (`{publisher}/{name}`) to `urn:air:{publisher}:mcp:{name}`, and clarifies that the discovery `identifier` is decoupled from cryptographic trust identity per ADR 0015. Doc-only change to docs/discovery.md; the Server Card schema has no identifier field and is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tadasant · 2026-06-19T01:25:42Z

  "entries": [
    {
-      "identifier": "urn:mcp:io.modelcontextprotocol.anonymous/brave-search",
+      "identifier": "urn:air:io.modelcontextprotocol.anonymous:mcp:brave-search",


Suggested change

"identifier": "urn:air:io.modelcontextprotocol.anonymous:mcp:brave-search",

"identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search",

If we are going to say the {publisher} is "The domain name of the organization publishing the artifact", I think we should use forward DNS here

MCP equivalent PR: modelcontextprotocol/experimental-ext-server-card#31

…DR 0015) (#31) ## What & why Adopts the AI Catalog **`urn:air:`** identifier-naming convention standardized in [Agent-Card/ai-catalog#36](Agent-Card/ai-catalog#36) (ADR 0015) for this extension's discovery docs. This repo's only identifier-naming surface is the **MCP Catalog Entry** in [`docs/discovery.md`](docs/discovery.md). It previously used a repo-local `urn:mcp:server:<name>` URN. `docs/discovery.md` describes the MCP Catalog as *"a minimal, MCP-scoped subset of the AI Catalog specification"* whose entries *"can be used as-is within a full AI Catalog document"* — a claim the old format contradicted, since the AI Catalog now standardizes the domain-anchored `urn:air:{publisher}:{namespace}:{name}` form. ### Changes (doc-only, `docs/discovery.md`) - Replace the `urn:mcp:server:<name>` convention with the AI Catalog `urn:air:` form. - Document the segments for an MCP server: - **`publisher`** — the publisher's domain (forward DNS), e.g. `example.com`, matching ADR 0015's framing that the publisher is a domain. - **`namespace`** — optional, populated per the AI Catalog specification (the examples omit it). - **`name`** — the server-name suffix (the segment after the `/` in the referenced Server Card's reverse-DNS `name`), e.g. `weather`. - So a Server Card named `com.example/weather` can be referenced as `urn:air:example.com:weather`. - Update all 4 catalog examples accordingly. ### Design notes for reviewers - **Forward-DNS publisher**, anchored on the publisher's domain per ADR 0015. - **Server Card schema deliberately untouched.** `schema.ts`/`schema.json` have **no `identifier`/`identity` field** — the card carries `name` (reverse-DNS) only — so this is a discovery-doc change, not a schema change. Keeps the PR minimal and avoids pre-empting unresolved SEP-2127 discussion. - **Related open question:** issue #26 ("Remove the MCP Catalog") — this aligns the identifier format while the MCP Catalog exists and does not pre-empt that discussion. ## Verification - [x] **Self-review (fresh-eyes) done.** Ran independent in-process reviews of the diff across iterations; findings (an incorrectly-attributed `urn:air:local:` form; reverse- vs forward-DNS publisher) were addressed. - [x] **ADR 0015 cross-checked against source** — verified the `urn:air:{publisher}:{namespace}:{name}` form, the forward-domain example `urn:air:example.com:...`, and the optional namespace against the raw `adr/0015-agent-identifier-naming.md` in PR #36. - [x] **All 4 examples internally consistent** with the documented mapping; example `url` hosts match the publisher domains. - [x] **No stale references** — `grep` confirms zero remaining `urn:mcp:server:` occurrences. - [x] **Schema untouched & in sync** — `npm run check` → `✓ schema.json is up to date`; `tsc --noEmit` passes. - [x] **Examples validate** — `npm run validate` → `All 7 example(s) passed.` - [x] **Formatting** — `npm run format:check` (prettier) passes on all tracked files. - [x] **CI green** — confirmed on the pushed branch (`build`, `CodeQL`, `Analyze` all pass). Local proof: ``` $ npm run check ✓ schema.json is up to date (+ tsc --noEmit, no errors) $ npm run validate All 7 example(s) passed. $ npm run format:check All matched files use Prettier code style! ``` Documentation-only change; no UI and no runtime/logic behavior to exercise beyond the schema toolchain above. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: tadasant <bob@tadasant.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

tadasant

This looks good 👍 Just pending the batch of changes flipping the MCP examples to forward DNS.

…ID length requirements (>2 characters). Note: this also aligns with the AI-catalog PR: Agent-Card/ai-catalog#36

…ention (forward dns domain format)

mindpower · 2026-06-22T17:52:57Z

This looks good 👍 Just pending the batch of changes flipping the MCP examples to forward DNS.

Just updated all examples in the spec.

mindpower added 2 commits May 13, 2026 10:54

Apply mediaType to type changes and add ADR 001

56fb993

Apply mediaType to type changes to ai-catalog.md and rename ADR

7c62ecb

github-actions Bot added a commit that referenced this pull request May 13, 2026

Publish specification preview for PR #36

3665997

mindpower requested review from darrelmiller and muscariello May 13, 2026 18:10

mindpower added 4 commits May 13, 2026 11:22

Add ADR 0015 for agent identifier naming

3958047

Update rationale in ADR 0015 regarding separation of concerns

24baf5d

Update URNs in ai-catalog.md and remove Orcas from ADR

582db47

feat: update to adr-0015 wording

b7c1866

github-actions Bot added a commit that referenced this pull request May 13, 2026

Publish specification preview for PR #36

52bec1f

mindpower changed the title ~~Update mediaType to type based on last meeting~~ Update mediaType to type based on last meeting + updated agent identifier May 13, 2026

fix: update typo and also entry type string for agents

a52df9f

github-actions Bot added a commit that referenced this pull request May 13, 2026

Publish specification preview for PR #36

a1d86a3

Update type field to open format in specifications

89dbff9

github-actions Bot added a commit that referenced this pull request May 13, 2026

Publish specification preview for PR #36

3872346

muscariello reviewed May 14, 2026

View reviewed changes

darrelmiller reviewed May 14, 2026

View reviewed changes

Comment thread specification/ai-catalog.md

darrelmiller reviewed May 14, 2026

View reviewed changes

fix: known catalog types

5ba2a67

github-actions Bot added a commit that referenced this pull request May 14, 2026

Publish specification preview for PR #36

d2856d5

jdamick reviewed May 14, 2026

View reviewed changes

Comment thread adr/0015-agent-identifier-naming.md Outdated

spec: refine catalog artifact type definitions based on 05/14 meeting

ac6f844

github-actions Bot added a commit that referenced this pull request May 15, 2026

Publish specification preview for PR #36

26715c0

Merge branch 'jbu/adr-0014-mediatype-to-type' into jbu/ai-catalog-upd…

1a81255

…ates

github-actions Bot added a commit that referenced this pull request May 15, 2026

Publish specification preview for PR #36

cbf798d

mindpower changed the base branch from main to jbu/adr-0014-mediatype-to-type May 15, 2026 23:20

fix: fix some of the incorrect field name in some examples (mediaType…

d55f141

… marked as type under TrustManifest) during auto-merge

github-actions Bot added a commit that referenced this pull request May 15, 2026

Publish specification preview for PR #36

bc8574f

mindpower changed the title ~~spec: adopt urn:ai: naming standard for AI artifacts (ADR 0015)~~ spec: adopt urn:air: naming standard for AI artifacts (ADR 0015) Jun 11, 2026

mindpower mentioned this pull request Jun 12, 2026

Spec: Update mediaType to type for catalogEntry and add known types #37

Merged

Tehsmash approved these changes Jun 12, 2026

View reviewed changes

jdamick reviewed Jun 18, 2026

View reviewed changes

darrelmiller approved these changes Jun 18, 2026

View reviewed changes

Fix some remaining 'urn:ai' to 'urn:air'

0708cdc

github-actions Bot added a commit that referenced this pull request Jun 18, 2026

Publish specification preview for PR #36

3714daa

tadasant mentioned this pull request Jun 18, 2026

docs(discovery): adopt AI Catalog urn:air: identifier convention (ADR 0015) modelcontextprotocol/experimental-ext-server-card#31

Merged

8 tasks

tadasant reviewed Jun 19, 2026

View reviewed changes

tadasant approved these changes Jun 19, 2026

View reviewed changes

This was referenced Jun 19, 2026

spec: Add "AI Actor Naming Standard" specification #19

Closed

spec: rename URN namespace identifier from <ai> to <air> to satisfy urn <nid> length requirements ards-project/ard-spec#29

Merged

mindpower added a commit to zeroasterisk/ard-spec that referenced this pull request Jun 20, 2026

spec: rename URN namespace identifier from <ai> to <air> to satisfy N…

8fff974

…ID length requirements (>2 characters). Note: this also aligns with the AI-catalog PR: Agent-Card/ai-catalog#36

chore: update URN identifiers to reflect canonical domain naming conv…

0281072

…ention (forward dns domain format)

github-actions Bot added a commit that referenced this pull request Jun 22, 2026

Publish specification preview for PR #36

785b9d4

mindpower mentioned this pull request Jun 23, 2026

Change identifier prefix from 'urn:air' to 'urn:ai' ards-project/ard-spec#39

Closed

Tehsmash mentioned this pull request Jun 23, 2026

[Feat]: Unique identifier for an agent in Agent Card a2aproject/A2A#1014

Open

1 task

ramizpolic approved these changes Jun 25, 2026

View reviewed changes

docs: update ADR 0015 participants and last updated date

f0b56b4

github-actions Bot added a commit that referenced this pull request Jun 25, 2026

Publish specification preview for PR #36

f6be2cb

mindpower changed the base branch from jbu/adr-0014-mediatype-to-type to main June 25, 2026 18:28

Fix some examples fields in ai-catalog.md

bed15ec

github-actions Bot added a commit that referenced this pull request Jun 25, 2026

Publish specification preview for PR #36

4dcf396

mindpower merged commit c443ffb into main Jun 25, 2026
4 checks passed

github-project-automation Bot moved this from In Progress to Done in AI Catalog Jun 25, 2026

github-actions Bot added a commit that referenced this pull request Jun 25, 2026

Remove specification preview for PR #36

af86d86

	"identifier": "urn:air:io.modelcontextprotocol.anonymous:mcp:brave-search",
	"identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search",

Uh oh!

Conversation

mindpower commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Summary of Changes

1. Architectural Decision Record: adr/0015-agent-identifier-naming.md

2. Core Specification: specification/ai-catalog.md

Architectural Rationale:

⚠️ Reviewer Guidance & Stacked PR Note

Uh oh!

github-actions Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tadasant left a comment

Choose a reason for hiding this comment

Uh oh!

mindpower commented Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mindpower commented May 13, 2026 •

edited

Loading

1. Architectural Decision Record: `adr/0015-agent-identifier-naming.md`

2. Core Specification: `specification/ai-catalog.md`

github-actions Bot commented May 13, 2026 •

edited

Loading