spec: bring description/version to displayName's authoritative-source parity (ADR-0017)#60
Draft
tadasant wants to merge 2 commits into
Draft
spec: bring description/version to displayName's authoritative-source parity (ADR-0017)#60tadasant wants to merge 2 commits into
tadasant wants to merge 2 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>
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
1 participant
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 the spec documents them as plain optional fields 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 own requireddescriptionandversion. This PR closes that gap.Field overlap this PR is built on:
server.jsondisplayNamename(required)titletitledescriptiondescription(required)description(required)descriptionversionversion(required)versionversionChanges
adr/0017-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 description — parallel authoritative-source guidance + pointer to a new resolution section.versionfield description — 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.description/versionaligned with the existingtitle/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 + field-description edits + one resolution section + mapping-row alignment. No refactoring of unrelated spec parts.
Verification
uv run --python 3.12 --lockedper.github/workflows/publish-spec.yml) and succeeds with the edits; the newresolving-an-artifacts-descriptionanchor id is present in the rendered HTML.versioncontinuation paragraph renders as prose (<p>inside the<dd>), not a code block, in the built HTML.#resolving-an-artifacts-display-name(the spec's accepted convention; works on GitHub, consistent with PR docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53).name/description/version), MCP Server Card / SEP-2127 (title, requireddescription,version), and MCP Registryserver.json(title/description/version).Drafted as a follow-up to ADR-0016 / PR #53, ahead of an AI Catalog bi-weekly working-group discussion.
descriptionis OPTIONAL in SEP-2127 (onlyname+versionrequired), so the ADR's "REQUIRED description" claim was corrected; the multi-versionversionwording was also sharpened. Remaining review notes were non-blocking and left as defensible (see commit13dd39a).