Skip to content

fix(schema): transition cart_id to omit on complete_checkout requests in release/2026-08-25 - #871

Merged
damaz91 merged 1 commit into
Universal-Commerce-Protocol:release/2026-08-25from
isparsh510:fix/cart-checkout-annotations
Oct 15, 2026
Merged

damaz91 merged 1 commit into
Universal-Commerce-Protocol:release/2026-08-25from
isparsh510:fix/cart-checkout-annotations

Conversation

@isparsh510

@isparsh510 isparsh510 commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Description

Retargeted to release/2026-08-25. This PR originally targeted main. On 2026-10-09, #911 (@gsmith85) landed the end state directly on main — cart_id.ucp_request.complete: "omit" — so main no longer needs a transition. The shipped 2026-08-25 schema still declares only create/update for cart_id, which leaves cart_id optional on complete_checkout for current implementers. This PR now carries only the non-breaking transition note for that released version, so implementers of 2026-08-25 are told the field is going away before the next version cut makes it omit.

In source/schemas/shopping/cart.json#/$defs/checkout, cart_id defines ucp_request visibility for create ("optional") and update ("omit"), but omits "complete". ucp-schema defaults unannotated operations to Include, so cart_id appears in the resolved complete_checkout request schema:

ucp-schema resolve source/schemas/shopping/cart.json --request --op complete --bundle
# $defs.checkout … properties.cart_id present

cart_id is only meaningful on create_checkout (cart-to-checkout conversion); the cart's contents are bound when the checkout is created. Because the released schema currently accepts it on complete, switching straight to omit on this branch would be a breaking change for 2026-08-25 implementers. This PR therefore uses the transition annotation (the same approach as #633 for cart.id), moving complete from optional to omit with the wording agreed in review.

Changes

  • Add a transition annotation ("from": "optional", "to": "omit") for complete to cart_id.ucp_request in source/schemas/shopping/cart.json#/$defs/checkout, on release/2026-08-25.

The hunk is byte-identical to the version reviewed and approved on main; only the base branch changed.

Backward compatibility

Non-breaking. During the transition the resolved complete_checkout request schema still admits cart_id; the published 2026-08-25 JSON schema and ucp-schema resolve output mark it "deprecated": true and carry the x-ucp-schema-transition guidance that Platforms SHOULD NOT send it and Businesses MUST ignore it. Note that the transition notice does not surface in a rendered HTML schema table: cart.json is a capability schema ("title": "Cart"), so auto_generate_schema_reference in main.py only renders its root properties and skips $defs/checkout. main already carries the final omit via #911, so no further step is needed at the next cut.

Category (Required)

  • Core Protocol
  • Capability
  • Extension
  • TransportBinding
  • Security & Privacy
  • Documentation
  • Conformance & Testing
  • UCP Schema
  • Infrastructure
  • Maintenance

Related Issues

Related to #911 (same fix applied directly on main). N/A otherwise — routine schema alignment fix.

Checklist

  • Code Changes:
    • Schema files (source/schemas/) — Specify capability: dev.ucp.shopping.cart (source/schemas/shopping/cart.json#/$defs/checkout; spec/ is generated via CI / build script)
    • Documentation (docs/)
    • Scripts or tooling (scripts/)
  • Quality & Testing:
    • Schema linting passes (ucp-schema lint source/)
    • Markdown examples validate (uv run python scripts/validate_examples.py --schema-base source/schemas/)
    • Site builds cleanly (./scripts/build_local.sh --draft-only)
    • Internal links are valid (uv run python scripts/check_links.py local_preview)
    • Spec text and schemas match (if modifying existing capabilities)
  • Governance:
    • This is a bug fix or minor update
    • This is a new capability or breaking change (Link to Discuss RFC or Issue: #___)

@isparsh510

Copy link
Copy Markdown
Contributor Author

Hey @jingyli @damaz91 could you please take a look at this small cart schema fix when you get a chance?

@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage bug Something isn't working status:under-review gov:needs-tc-review Requires review and approval from the Technical Council area:shopping Issues and pull requests related to the Shopping vertical and removed status:needs-triage Signal that the PR is ready for human triage labels Sep 27, 2026

@jingyli jingyli left a comment

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.

Thanks @isparsh510 for catching this miss! One callout here:

This PR should either be marked as a breaking change given it removes an (erroneously marked) optional field or you can leverage the transition annotation to specify that complete operation is moving from optional to omit.

@isparsh510 isparsh510 changed the title fix(schema): omit cart_id on complete_checkout requests in cart extension fix(schema): transition cart_id to omit on complete_checkout requests in cart extension Sep 29, 2026
@isparsh510

Copy link
Copy Markdown
Contributor Author

Thanks @jingyli for the review, I moved to using transition annotation as it doesn't require full enhancement proposal.

@isparsh510
isparsh510 requested a review from jingyli September 29, 2026 17:55
Comment thread source/schemas/shopping/cart.json Resolved
@isparsh510 isparsh510 changed the title fix(schema): transition cart_id to omit on complete_checkout requests in cart extension fix(schema): transition cart_id to omit on complete_checkout requests in release/2026-08-25 Oct 10, 2026
@isparsh510
isparsh510 force-pushed the fix/cart-checkout-annotations branch from 4b2f234 to 7658a34 Compare October 10, 2026 22:01
@isparsh510
isparsh510 changed the base branch from main to release/2026-08-25 October 10, 2026 22:01
@isparsh510

isparsh510 commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Retargeted this PR from main to release/2026-08-25. #911 landed the end state (complete: "omit") directly on main on 2026-10-09, so main no longer needs a transition. The shipped 2026-08-25 schema still admits cart_id on complete_checkout, so this PR now only carries the non-breaking transition annotation (same hunk as reviewed, with the agreed wording) for that release. Description updated accordingly.

btw @jingyli @damaz91 lemme know should I just close this one since #911 already landed the same fix in main 😅

@damaz91

damaz91 commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

@gsmith85 PTAL at this as follow-up of #911

@damaz91
damaz91 requested a review from gsmith85 October 13, 2026 10:00

@gsmith85 gsmith85 left a comment

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.

LGTM, thanks @isparsh510 (and sorry for the overlap with #911 on main). Pairing the non-breaking optional -> omit transition on release/2026-08-25 with the final "complete": "omit" already on main leaves both branches in the right state and avoids needing a separate cleanup PR at the next version cut.

One small note on the PR description: because cart.json is a capability schema ("title": "Cart") rather than an extension schema, auto_generate_schema_reference in main.py only renders its root properties and skips $defs/checkout, so the transition notice won't show up in an HTML table unless we separately wire extension_schema_fields('cart.json#/$defs/checkout', ...) into the docs. The published 2026-08-25 JSON schema and ucp-schema resolve output still get "deprecated": true and x-ucp-schema-transition, so this is good to land as-is.

@isparsh510

Copy link
Copy Markdown
Contributor Author

Thnx @gsmith85 I updated the description accordingly will submit the PR :)

@isparsh510

Copy link
Copy Markdown
Contributor Author

@damaz91 its also asking for GC approval I think 😅

@amithanda
amithanda requested review from gil-- and igrigorik October 14, 2026 17:35
@amithanda

Copy link
Copy Markdown
Contributor

Approving! Please wait for Gil's approval as well.
@gil-- , Since you approved #911, can you please approve this as well before we merge.

… in release/2026-08-25

In cart.json#/$defs/checkout, cart_id annotated only create and update, so
ucp-schema included it in complete_checkout request schemas. cart_id is
only meaningful on create_checkout; cart contents are bound at checkout
creation.

main already carries the end state (complete: omit) via Universal-Commerce-Protocol#911. The shipped
2026-08-25 schema still admits cart_id on complete, so this change adds the
non-breaking transition annotation (optional -> omit) for that release:
Platforms SHOULD NOT send it, Businesses MUST ignore it, and it becomes
omit at the next version cut.
@damaz91
damaz91 force-pushed the fix/cart-checkout-annotations branch from 7658a34 to 5c912b8 Compare October 15, 2026 08:16
@damaz91
damaz91 merged commit cb60c88 into Universal-Commerce-Protocol:release/2026-08-25 Oct 15, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:shopping Issues and pull requests related to the Shopping vertical bug Something isn't working gov:needs-tc-review Requires review and approval from the Technical Council status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants