spec: bring description/version to displayName's authoritative-source parity (ADR-0017)

[tadasant]

⚠️ AI-assisted draft. This PR's content (the ADR and spec prose) was drafted by an AI assistant working on Tadas's behalf. Tadas will review, vet, and rewrite as needed, and will remove this disclosure once he has done so. Until then, treat this as a steered placeholder, not Tadas's finished position.

---

What & why

ADR-0016 made the Catalog Entry displayName OPTIONAL and gave it a precise authoritative-source rule: omit it when the referenced artifact already carries its own canonical name (A2A Agent Card name, MCP Server Card title) to avoid drift; when present it takes precedence for display; and a companion "Resolving an Artifact's Display Name" section defines the consumer resolution order.

displayName is not the only entry member that restates a value the referenced artifact already carries. description and version have the same duplication-and-drift problem against the same artifact, but the description/version field definitions were still bare one-liners with no equivalent guidance. That's incoherent — a publisher reading the field list is told to omit displayName against the Server Card's title but given no steer on description/version, which map onto the Server Card's own description and version. This PR closes that gap at the field-definition level.

Field overlap this PR is built on:

Entry field	A2A Agent Card	MCP Server Card / SEP-2127	MCP Registry server.json
displayName	name (required)	title (optional)	title
description	description (required)	description (optional)	description
version	version (required)	version (required)	version (required)

Changes

• New adr/0017-entry-field-authoritative-source-parity.md (Status: Proposed) — extends ADR-0016's rule to description and version, with an explicit in/out Scope section (out: tags, updatedAt, publisher/trustManifest, metadata, identifier/type/url/data, each with reasoning).
• specification/ai-catalog.md:
  • description field definition — parallel authoritative-source guidance + pointer to a new resolution section.
  • version field definition — authoritative-source guidance adapted for its structural role: it's part of the identifier+version uniqueness key and consumers sort on it, so it stays REQUIRED for multi-version listings and a present value is sort-authoritative (SHOULD equal the artifact's version; a contradiction is a publishing error, not a free-form override) rather than a cosmetic override.
  • New "Resolving an Artifact's Description" section next to "Resolving an Artifact's Display Name".
  • Claude Plugins mapping-appendix description row aligned with the existing plugin-name/displayName row.

No schema change — description and version are already OPTIONAL in the CDDL. This is guidance only and is not a breaking change (existing catalogs that populate these fields remain conformant).

Relationship to base main

While this branch was open, base main merged a Server-Card-centric rewrite of the MCP mapping appendix (#53) that already added the authoritative-source guidance to the MCP description/version mapping rows, and a mkdocs reconciliation (#62) that switched spec-internal anchors to the build-tool slugify form. This branch has been merged with base; the now-redundant MCP mapping-row edits were dropped, and the remaining genuinely-additive contribution (the ADR, the two field-definition edits, the new resolution section, and the plugins-row alignment) was re-applied onto the base structure. Spec-internal links use the build-tool anchor form (#resolving-an-artifact-s-description); ADR→spec cross-links keep the GitHub form, consistent with ADR-0016.

Scope

Deliberately tight: one ADR + two field-definition edits + one resolution section + one mapping-row alignment. No refactoring of unrelated spec parts.

Verification

• Merged base main into the branch and resolved the specification/ai-catalog.md conflict; PR reports MERGEABLE (no conflicts remaining).
• Net diff vs origin/main confirmed to be exactly the four intended additive edits (description field def, version field def, "Resolving an Artifact's Description" section, plugins description row) — no stray or half-merged content.
• CI green — build and publish-pr-preview both pass; publish-root/cleanup-pr-preview correctly skipped (main-only / on-close).
• Local spec build reproduces CI (uv run --python 3.12 --locked python tools/build_spec.py … per .github/workflows/publish-spec.yml) and succeeds; the new resolving-an-artifact-s-description heading id is present in the rendered HTML and matches its sibling resolving-an-artifact-s-display-name.
• Verified the version continuation paragraph renders as prose (<p> inside the <dd>), not a code block, in the built HTML.
• Anchor conventions verified: spec-internal links use the build-tool -s- form (matches base); ADR cross-links use the GitHub form (matches ADR-0016).
• Independent fresh-eyes review performed twice via in-process subagent (initial diff, then the final post-merge diff). The first pass caught an overstated "REQUIRED" claim on MCP Server Card description (it is OPTIONAL in SEP-2127), which was fixed.
• Opened and kept as a draft; AI-authorship disclosure at the top of this description per the repo operating rule.

Drafted as a follow-up to ADR-0016 / PR #53, ahead of an AI Catalog bi-weekly working-group discussion.

[github-actions]

Preview: https://ai-catalog.io/pr/60/

This comment is updated automatically while the pull request preview is available.