Skip to content

feat(schema): add SHOULD for capability_id on every format_options[] entry#4863

Closed
bokelley wants to merge 1 commit into
mainfrom
claude/issue-4856-should-publish-capability-id
Closed

feat(schema): add SHOULD for capability_id on every format_options[] entry#4863
bokelley wants to merge 1 commit into
mainfrom
claude/issue-4856-should-publish-capability-id

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Closes #4856

Summary

product-format-declaration.json capability_id description update: sellers SHOULD publish a stable capability_id on every format_options[] entry — not just when structurally required to disambiguate. Pairs the seller-side obligation with the v2 buyer capability (PackageRequest.capability_ids[]) added in #4845, so sellers reading 3.1 release notes see the obligation alongside the capability in the same minor.

The change also:

  • Fixes "should be stable once published" (informal) → Sellers SHOULD NOT change a published capability_id (normative, consistent with display_name's pattern)
  • Fixes "V2" → "v2" to match file convention
  • Softens "will receive UNSUPPORTED_FEATURE" → "may receive" to accurately reflect the SHOULD on the reason field in package-request.json

Non-breaking justification: Description-only change. The capability_id field remains type: string and optional in JSON Schema (required array unchanged). Existing conformant implementations remain conformant — sellers who omit capability_id on single-format_kind entries stay valid; the SHOULD creates a normative recommendation, not a mandatory requirement.

Not patch-eligible for 3.0.x. The prior description was "Recommended for any declaration that may be referenced by capability_id over time" (informal). Adding explicit RFC 2119 SHOULD language fails the patch-eligibility test (a conformant 3.0.0 implementation that omits capability_id entirely is valid but does not satisfy the new SHOULD). Ships on main as 3.1.0-beta.N under pre-mode — correct and intentional.

Pre-PR review:

  • code-reviewer: approved — no blockers; two wording nits addressed (lowercase "should" → normative, "will receive" → "may receive")
  • ad-tech-protocol-expert: approved — non-breaking per spec; minor changeset correct; REQUIRED + SHOULD combination is coherent and consistent with existing patterns in this schema

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_017v9EZzS9ZFzexe58cmFc4k


Generated by Claude Code

…try (#4856)

Pairs the seller-side obligation with the V2 buyer capability added in #4845.
Sellers SHOULD publish a stable capability_id on every format_options[] entry
so v2 buyers using PackageRequest.capability_ids[] can target declarations directly.

https://claude.ai/code/session_017v9EZzS9ZFzexe58cmFc4k
@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 20, 2026
@bokelley

Copy link
Copy Markdown
Contributor Author

Closing as superseded by current main. The capability_id SHOULD guidance and changeset are already present in static/schemas/source/core/product-format-declaration.json and .changeset/should-publish-capability-id-on-every-format-option.md; main also has newer adjacent format_schema mirror-domain text, so resolving this branch would only reintroduce stale wording.

@bokelley bokelley closed this May 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

spec(3.1): SHOULD-publish capability_id on every format_options[] entry

2 participants