Repository navigation
fix(schema): transition cart_id to omit on complete_checkout requests in release/2026-08-25 - #871
Conversation
jingyli
left a comment
There was a problem hiding this comment.
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.
|
Thanks @jingyli for the review, I moved to using |
4b2f234 to
7658a34
Compare
|
Retargeted this PR from btw @jingyli @damaz91 lemme know should I just close this one since #911 already landed the same fix in main 😅 |
gsmith85
left a comment
There was a problem hiding this comment.
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.
|
Thnx @gsmith85 I updated the description accordingly will submit the PR :) |
|
@damaz91 its also asking for GC approval I think 😅 |
… 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.
7658a34 to
5c912b8
Compare
cb60c88
into
Universal-Commerce-Protocol:release/2026-08-25
Description
In
source/schemas/shopping/cart.json#/$defs/checkout,cart_iddefinesucp_requestvisibility forcreate("optional") andupdate("omit"), but omits"complete".ucp-schemadefaults unannotated operations toInclude, socart_idappears in the resolvedcomplete_checkoutrequest schema:cart_idis only meaningful oncreate_checkout(cart-to-checkout conversion); the cart's contents are bound when the checkout is created. Because the released schema currently accepts it oncomplete, switching straight toomiton this branch would be a breaking change for2026-08-25implementers. This PR therefore uses thetransitionannotation (the same approach as #633 forcart.id), movingcompletefromoptionaltoomitwith the wording agreed in review.Changes
transitionannotation ("from": "optional","to": "omit") forcompletetocart_id.ucp_requestinsource/schemas/shopping/cart.json#/$defs/checkout, onrelease/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_checkoutrequest schema still admitscart_id; the published2026-08-25JSON schema anducp-schema resolveoutput mark it"deprecated": trueand carry thex-ucp-schema-transitionguidance 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.jsonis a capability schema ("title": "Cart"), soauto_generate_schema_referenceinmain.pyonly renders its root properties and skips$defs/checkout.mainalready carries the finalomitvia #911, so no further step is needed at the next cut.Category (Required)
Related Issues
Related to #911 (same fix applied directly on
main). N/A otherwise — routine schema alignment fix.Checklist
source/schemas/) — Specify capability:dev.ucp.shopping.cart(source/schemas/shopping/cart.json#/$defs/checkout;spec/is generated via CI / build script)docs/)scripts/)ucp-schema lint source/)uv run python scripts/validate_examples.py --schema-base source/schemas/)./scripts/build_local.sh --draft-only)uv run python scripts/check_links.py local_preview)