Skip to content

fix: terminology alignment and ADR 0007/0010 follow-ups #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
liady wants to merge 1 commit into
base: main
Choose a base branch
from
+30 −8
Open

fix: terminology alignment and ADR 0007/0010 follow-ups #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions adr/0007-url-field-name.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,15 @@ Use `url` as the field name.
collection references, attestations).
- Values MAY be relative URI references, despite the field name, though
absolute URLs are RECOMMENDED.

## Update (2026-07)

The spec has since split naming by intent, and the split is deliberate:

- `url`-suffixed fields (`url`, `documentationUrl`, `logoUrl`,
`privacyPolicyUrl`, `termsOfServiceUrl`) hold fetchable HTTP(S)
resources.
- `uri`-suffixed fields (attestation `uri`, `governanceUri`,
`registryUri`, `statementUri`) allow non-HTTP schemes or values that
serve as identifiers rather than fetchable locations (e.g. `oci://`
references).
26 changes: 18 additions & 8 deletions specification/ai-catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ and reducing interoperability.

This document defines the **AI Catalog**: a typed, nestable JSON
container for discovering heterogeneous AI artifacts. Each entry
declares its artifact type via a media type and may reference or
declares its artifact type via a type identifier and may reference or

@darrelmiller darrelmiller Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The value of type is still an IANA media type. We are sticking with this value domain because then we don't need to define our own syntax and range of valid values. There is precedence for using type as an indicator of media type in the IETF Web Linking specification https://datatracker.ietf.org/doc/html/rfc8288#section-3.4.1

embed the native artifact metadata. A minimal catalog is simply a
list of entries — names, types, and URLs — requiring no additional
infrastructure.
Expand All @@ -25,7 +25,7 @@ that do not need trust metadata can ignore the Trust Manifest entirely.
The AI Catalog is intentionally agnostic about the artifacts it
indexes. It does not define or constrain the schema of MCP server
manifests, A2A agent cards, or any other artifact format. Instead, it
relies on media types to identify what each entry is, and delegates
relies on type identifiers to indicate what each entry is, and delegates
the definition of artifact-specific metadata to the respective protocol
specifications.

Expand All @@ -44,7 +44,7 @@ AI Catalog
media type that contains an ordered list of catalog entries.

Catalog Entry
: A single item in an AI Catalog, identified by a media type and
: A single item in an AI Catalog, identified by a type identifier and
referencing or embedding an AI artifact.

Trust Manifest
Expand All @@ -56,14 +56,21 @@ Artifact
manifest, an A2A agent card, a Claude Code plugin, a
dataset descriptor, or a nested AI Catalog.

AI Card

@darrelmiller darrelmiller Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we really want to keep the terminology of AI Card. The repo was renamed and the org hasn't been changed primarily because we didn't want to break links. We have been using "catalog entry" as the primary term.

: The umbrella concept for any AI artifact metadata document, such as
an A2A Agent Card, an MCP Server Card, or an Agent Skill. "AI Card"
is the name of the working group and the overall effort; the
normative term for such a document in this specification is
Catalog Entry.

# Design Goals

1. **Artifact Agnosticism**: The catalog MUST be capable of indexing
any type of AI artifact without requiring knowledge of the
artifact's internal schema.

2. **Media Type Identification**: Each catalog entry MUST declare its
artifact type using a media type, enabling clients to select,
2. **Type Identification**: Each catalog entry MUST declare its
artifact type using a type identifier, enabling clients to select,
filter, and route entries without parsing artifact content.

3. **Composability**: The catalog format supports nesting — a catalog
Expand Down Expand Up @@ -932,9 +939,12 @@ procedure is:
3. If neither is found, optionally fall back to the well-known URI
`/.well-known/ai-catalog.json` as described in
[Well-Known URI](#well-known-uri).
4. Retrieve the discovered URL. If the response has a media type of
`application/ai-catalog+json` and contains a valid `specVersion`
field, treat it as the site's AI Catalog.
4. Retrieve the discovered URL. If the response carries a JSON media
type (`application/ai-catalog+json` is preferred, but a generic
type such as `application/json` is acceptable, per
[Location Independence](#location-independence)) and the document
contains a valid `specVersion` field, treat it as the site's AI
Catalog.

This mechanism allows any website to surface its AI tools, agents,
and services to visiting agents through a standard, machine-readable
Expand Down
Loading