spec: adopt urn:ai: naming standard for AI artifacts (ADR 0015)#36
spec: adopt urn:ai: naming standard for AI artifacts (ADR 0015)#36mindpower wants to merge 16 commits into
urn:ai: naming standard for AI artifacts (ADR 0015)#36Conversation
|
Preview: https://agent-card.github.io/ai-catalog/pr/36/ This comment is updated automatically while the pull request preview is available. |
mindpower
changed the title
|
|
||
| ## 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}`. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
This is a good question. We can use "local" or "unknown" to indicate this is an unverifiable local agent (so publisher is not verifiable)
| ## 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`). |
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
These are valid concerns. Let's discuss about this in the meeting today.
|
|
||
| - `application/ai-catalog+json` — a nested AI Catalog | ||
| - `application/a2a-agent-card+json` — an A2A Agent Card | ||
| - `application/mcp-server-card+json` — an MCP Server Card |
There was a problem hiding this comment.
What was the reason for removing the agent card type?
There was a problem hiding this comment.
I think we are just missing application/agent-card+json that was mentioned in the ADR
There was a problem hiding this comment.
Updated the PR so now we have application/agent-card+json as mentioned in the ADR.
| `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 |
There was a problem hiding this comment.
I'm not sure how a type defines an endpoint? Is there other documentation for what this is?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
It's just a url pointer
| We will align the agent identifier naming in `ai-catalog.md` with the naming standards proposed in [PR #19](https://github.com/Agent-Card/ai-catalog/pull/19). | ||
| The `identifier` field will follow the URN format: `urn:{nid}:{publisher}:{namespace}:{name}`. | ||
| - `nid`: The Namespace Identifier (e.g., `agent`, `mcp`). | ||
| - `publisher`: The domain where the agent is hosted (e.g., `example.com`). |
There was a problem hiding this comment.
If you embed the domain anyway, how is this more stable than say a did:web identifier?
… marked as type under TrustManifest) during auto-merge
mindpower
changed the title
urn:ai: naming standard for AI artifacts (ADR 0015)
mindpower
changed the title
urn:ai: naming standard for AI artifacts (ADR 0015)urn:ai: naming standard for AI artifacts (ADR 0015)
Redefines the `identifier` field in catalog entries as an open format for local and closed systems, while highly recommending and standardizing the domain-anchored `urn:ai` URN scheme for open/federated systems. - Updates the `identifier` schema description in `ai-catalog.md`. - Promotes and updates ADR 0015 to document this balanced decision.
4 participants
This pull request introduces ADR 0015, proposaling a standardized, domain-anchored URN naming convention (
urn:ai:) 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.mdurn:ai:{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.identifierURN) and cryptographic trust identities (theidentityfield intrustManifest, which may use DIDs, SPIFFE, x509, etc.).2. Core Specification:
specification/ai-catalog.mdidentifiermember definition to mandate theurn:ai:format.urn:ai:acme.com:agent:finance)urn:ai:io.modelcontextprotocol.anonymous:mcp:brave-search)urn:ai:acme.com:catalog:finance)urn:ai:acme.com:agent:finance:mcp)urn:ai:acme.com:agent:financvsurn:ai:acme.com:agent:finance)Architectural Rationale:
urn:ai:allows centralized registries and decentralized crawlers to index, filter, and search AI artifacts uniformly.