Skip to content

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

Open
liady wants to merge 3 commits into
Agent-Card:mainfrom
liady:fix/terminology-alignment
Open

liady wants to merge 3 commits 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
Comment thread specification/ai-catalog.md Outdated
Comment thread specification/ai-catalog.md Outdated
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Yes let's remove the AI card change part.

@darrelmiller darrelmiller added this to the RC release milestone Aug 20, 2026
@darrelmiller

Copy link
Copy Markdown
Contributor

From the Aug 20th meeting, there is consensus around this PR with the exception of the section about AI Card which we should remove.

@darrelmiller
darrelmiller force-pushed the fix/terminology-alignment branch from aa56755 to 4f3a468 Compare August 23, 2026 20:13
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: a8f253d0-d588-43dc-936a-9c6d7ccf2674
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

4 participants