Skip to content

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

Open
liady wants to merge 1 commit into
Agent-Card:mainfrom
liady:fix/terminology-alignment
Open

fix: terminology alignment and ADR 0007/0010 follow-ups#79
liady wants to merge 1 commit into
Agent-Card:mainfrom
liady:fix/terminology-alignment

Conversation

@liady

@liady liady commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Fixes #72.

Four small alignment items, none of them changing behavior on their own:

  • The intro, the Catalog Entry terminology definition, and Design Goal 2 still described entries as identified by a "media type". ADR 0014 renamed the field to type precisely because it is an open type identifier, and the field definition already uses that framing, so the intro material now matches.
  • Link relation discovery step 4 only accepted application/ai-catalog+json responses, while Location Independence makes serving that media type a SHOULD. A catalog served as application/json would pass the well-known flow but fail the link-relation flow. Step 4 now accepts generic JSON media types as long as the document has a valid specVersion.
  • Added the "AI Card" terminology entry that ADR 0010 called for.
  • ADR 0007 said the field is named url across all objects, but the spec uses uri where non-fetchable identifiers are allowed (attestation uri, governanceUri, registryUri, statementUri). Added an update note to the ADR recording that the split is deliberate, so implementers don't read it as drift.

@liady
liady requested a review from a team as a code owner July 14, 2026 21:11
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

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

manifest, an A2A agent card, a Claude Code plugin, a
dataset descriptor, or a nested AI Catalog.

AI Card

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.

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.

Terminology and wording alignment: 'media type' leftovers, discovery strictness, ADR 0007/0010 follow-ups

2 participants