spec: bring description/version to displayName's authoritative-source parity (ADR-0018) - #60
Open
tadasant wants to merge 6 commits into
Open
spec: bring description/version to displayName's authoritative-source parity (ADR-0018)#60tadasant wants to merge 6 commits into
tadasant wants to merge 6 commits into
Conversation
… parity Adds ADR-0017 and the matching spec edits so the entry-level fields that duplicate a referenced artifact's own canonical value (description, version) follow the same SHOULD-omit-when-authoritative / present-takes-precedence / avoid-drift rule already established for displayName in ADR-0016. - description: parallel authoritative-source guidance + new "Resolving an Artifact's Description" consumer resolution order - version: authoritative-source guidance adapted for its structural role (uniqueness key + sorting; required for multi-version listings) - MCP + Claude Plugins mapping-appendix rows aligned with the title row
Contributor
|
Preview: https://ai-catalog.io/pr/60/ This comment is updated automatically while the pull request preview is available. |
…sion wording Review feedback: - MCP Server Card `description` is OPTIONAL in SEP-2127 (only name+version required), not REQUIRED as originally stated. - Frame the multi-version `version` requirement as emergent from the identifier+version uniqueness key rather than as already-stated normative text in the Multi-Version Entries section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Resolves the specification/ai-catalog.md conflict with the base branch's Server-Card-centric MCP mapping rewrite (PR #53) and mkdocs reconciliation (PR #62). Base main already added the authoritative-source guidance to the MCP mapping-appendix description/version rows, so those now-redundant edits are dropped. This branch's genuinely-additive contribution is preserved and re-applied onto the base structure: - authoritative-source guidance on the description and version *field definitions* (base still had bare one-liners there) - a new "Resolving an Artifact's Description" consumer-resolution section - the Claude Plugins appendix description row aligned to match Spec-internal anchor links use the build-tool slugify form (#resolving-an-artifact-s-description) to match base's convention; ADR cross-links keep the GitHub form, consistent with ADR-0016. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tadasant
changed the title
…field-authoritative-source-parity.md
tadasant
marked this pull request as ready for review
July 23, 2026 03:27
…0016 Review follow-ups on ADR-0018: - Align the Claude Plugins example with the new mapping-table row: the three marketplace catalog entries drop the now-redundant `description` (they already omit `displayName`), so the worked example no longer contradicts the "entry `description` is omitted" mapping. The nested-catalog entry keeps its `description`, since a catalog artifact carries no canonical description of its own. - Add a "Resolving an Artifact's Version" section mirroring the display-name and description resolution sections, and point the `version` field definition at it. Covers the omitted-single-version case (resolve from the artifact), the entry-vs-artifact mismatch rule (entry value authoritative for sorting/selection), and the `updatedAt` fallback for unversioned entries. - Mark ADR-0016 (displayName optional) Accepted — ratified at the 2026-06-18 AI Catalog working-group call. ADR-0018 Consequences updated to reflect the new version resolution section and the plugin-example alignment. All 16 intra-doc anchors resolve. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
Took me a couple of times to read this but now I grok it, I like this change a lot. Thank you. |
darrelmiller
approved these changes
Jul 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
ADR-0016 made the Catalog Entry
displayNameOPTIONAL and gave it a precise authoritative-source rule: omit it when the referenced artifact already carries its own canonical name (A2A Agent Cardname, MCP Server Cardtitle) 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.displayNameis not the only entry member that restates a value the referenced artifact already carries.descriptionandversionhave the same duplication-and-drift problem against the same artifact, but thedescription/versionfield definitions were still bare one-liners with no equivalent guidance. That's incoherent — a publisher reading the field list is told to omitdisplayNameagainst the Server Card'stitlebut given no steer ondescription/version, which map onto the Server Card's owndescriptionandversion. This PR closes that gap at the field-definition level.Field overlap this PR is built on:
server.jsondisplayNamename(required)title(optional)titledescriptiondescription(required)description(optional)descriptionversionversion(required)version(required)version(required)Changes
adr/0018-entry-field-authoritative-source-parity.md(Status: Proposed) — extends ADR-0016's rule todescriptionandversion, with an explicit in/out Scope section (out:tags,updatedAt,publisher/trustManifest,metadata,identifier/type/url/data, each with reasoning).specification/ai-catalog.md:descriptionfield definition — parallel authoritative-source guidance + pointer to a new resolution section.versionfield definition — authoritative-source guidance adapted for its structural role: it's part of theidentifier+versionuniqueness 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.descriptionrow aligned with the existing plugin-name/displayNamerow.No schema change —
descriptionandversionare already OPTIONAL in the CDDL. This is guidance only and is not a breaking change (existing catalogs that populate these fields remain conformant).Scope
Deliberately tight: one ADR + two field-definition edits + one resolution section + one mapping-row alignment. No refactoring of unrelated spec parts.