Repository navigation
Conversation
44667ef to
7168971
Compare
f6ad270 to
5250831
Compare
|
Re-anchored on released v2026-08-25: the branch already targets the new docs/specification/shopping paths and applies cleanly. The release sharpens the case rather than absorbing it, since buyer-consent.md L372-373 now asserts that the business retains its prior position while checkout/rest.md L242-245 states a MUST over the same buyer object that replaces everything not resent. The discount extension already carries per-field replacement semantics in its own doc (discount.md L134), which is the shape proposed here for consent. |
sbeashwar
left a comment
There was a problem hiding this comment.
Agree - under literal full-replacement, an update that omits buyer.consent could silently revert an opted-out buyer to the advertised default. I verified the three cross-references (buyer-consent.md#normative-requirements, cart/index.md#update-cart, checkout/index.md#update-checkout) all resolve, and the carve-out wording is consistent across the four prose locations.
One completeness gap, and it goes to the PR's own goal of stating the exception every place the full-replacement rule appears: the rule is also stated in the source API contracts, which this PR does not touch. Both source/services/shopping/rest.openapi.json and source/services/shopping/mcp.openrpc.json carry an update_checkout description that reads "Update Checkout is a full replacement operation ..." with only the complete_in_progress exception and no consent carve-out. These are authoritative and machine-consumed (SDKs, validators, generated reference), so an implementer reading the OpenAPI/OpenRPC directly still sees the unqualified rule - the same divergence this PR is closing. It also means the note that the MCP binding "does not restate the rule" is not quite accurate; the MCP source (mcp.openrpc.json) does restate it.
I would add the same carve-out (or a cross-reference to it) to those two update_checkout descriptions so the source contracts agree with the prose. The source/schemas/shopping/cart.json "Full replacement on update" note is scoped to line items rather than consent, so I do not think it needs changing.
Minor: no category box is checked in the PR template. Since the change adds a MUST-level carve-out to core Update Cart / Update Checkout behavior, it may be worth confirming whether it should be treated as a documentation clarification or flagged for Technical Council awareness under the significant-change definition. I read it as resolving a contradiction rather than introducing new behavior, so I lean clarification, but the categorization should be explicit.
…eplacement rules Buyer consent says that omitting `consent` on a request retains the prior position, but core Update Cart and Update Checkout are full replacements that require the platform to send the entire resource and replace the stored session state. A business implementing the literal full-replacement contract drops captured consent on the next update that omits `buyer.consent` (for example a fulfillment change), re-exposing advertised defaults, so a buyer who opted out can be reset toward an opted-in default. Consent rides both `cart.buyer.consent` and `checkout.buyer.consent`, so the exception is added to every prose location that states the full-replacement rule: - buyer-consent.md: state that consent persistence is an explicit exception to the cart and checkout full-replacement rules, cross-referencing both. - checkout/index.md and cart/index.md: add the exception note to each full-replacement rule (checkout/index.md already carries the complete_in_progress exception). - checkout/rest.md: the rule is restated twice here (the general Update Checkout rule and the buyer-specific Update Buyer Info paragraph, which draws the drop-if-omitted consequence as a MUST over the buyer object); both now carry the carve-out. The binding documents under docs/ do not restate the rule: cart/rest.md and cart/mcp.md carry no replacement statement, and checkout/mcp.md restates only the complete_in_progress clause. The machine-consumed service contracts under source/services/ do restate it; a following commit adds the carve-out there.
…racts The full replacement rule for Update Checkout is also stated in the machine-consumed service contracts, where it carried only the `complete_in_progress` exception. An implementer reading `source/services/shopping/rest.openapi.json` or `source/services/shopping/mcp.openrpc.json` directly, including the copy published at the URL the discovery profile advertises, still saw the unqualified rule: the same divergence this branch closes in the prose. Add the carve-out sentence already used in the four prose locations to the `update_checkout` description in both contracts. The `complete_in_progress` exception is left intact.
b7973b9 to
5db2dbe
Compare
|
Thanks for the review. You are right on both counts, and the second one is a The body claim was wrong. The body says "The MCP and cart-rest bindings link One mechanical detail worth recording: Changed now. The
The capability id is spelled out because a contract read on its own has no A second inaccuracy in the body, which you did not flag. It also says the Class accounting. Nine sites match
Four further sites state the same rule in other words and are listed for
Why lodging is out of scope. Three independent checks:
So the carve-out has nothing to attach to under lodging. If a lodging consent One gap I am leaving alone. Neither contract states the full-replacement rule Category. Recommending Documentation; the corrected body checks that Where I think you could reasonably disagree: the carve-out is a MUST over core Verification re-run 2026-09-30 on a rebase onto |
sbeashwar
left a comment
There was a problem hiding this comment.
Approving. Re-reviewed 5db2dbe9 and confirmed both OpenAPI and OpenRPC descriptions now include the consent-persistence exception, with the existing completion-state restrictions preserved. I agree with the Documentation classification: this makes the existing omit-and-retain rule explicit across the affected contracts and prose.
karangoel16
left a comment
There was a problem hiding this comment.
This is a real bug fix, and the failure mode is the scary one — an explicit opt-out silently reverting to opted-in defaults on an unrelated update. Good catch.
I checked the coverage claim: every place the full-replacement rule is stated now carries the exception — cart/index.md, checkout/index.md, both spots in checkout/rest.md, the extension doc itself, and both service descriptors. The cart-side descriptors don't restate the rule, so there's nothing missing there. All three anchor links resolve too.
Wording is consistent across all six sites. Approving.
|
@jingyli given this PR touched normative clauses of the documentation, can you take a look? |
Description
Problem
The buyer-consent extension says omitting
consenton a request "retains the prior position," but core Update Cart and Update Checkout are full replacements: the platform sends the entire resource and it replaces the stored session state. A business implementing the literal full-replacement contract drops captured consent on the next update that omitsbuyer.consent(for example a fulfillment change), re-exposing advertised defaults. A buyer who explicitly opted out can be reset toward an opted-in default, which is the failure mode a consent record most needs to prevent. Two conformant implementations diverge on the outcome.Fix
Consent rides both
cart.buyer.consentandcheckout.buyer.consent, so the exception is added to every place the full-replacement rule is stated:buyer-consent.md: state that consent persistence is an explicit exception to the cart and checkout full-replacement rules, cross-referencing both.shopping/checkout/index.mdandshopping/cart/index.md: add the exception note to each full-replacement rule (the checkout document already carries thecomplete_in_progressexception).shopping/checkout/rest.md: the rule is restated twice here, and both now carry the carve-out: the general Update Checkout rule, and the buyer-specific Update Buyer Info paragraph, which draws the drop-if-omitted consequence as aMUSTover thebuyerobject (and so is the most on-point site, since consent isbuyer.consent).source/services/shopping/rest.openapi.jsonandsource/services/shopping/mcp.openrpc.json: theupdate_checkoutdescription in each states the rule with only thecomplete_in_progressexception. Both now carry the same carve-out sentence, so the machine-consumed contracts agree with the prose. Added after review by @sbeashwar, who found this gap.The binding documents under
docs/do not restate the full-replacement rule:cart/rest.mdandcart/mcp.mdcarry no replacement statement, andcheckout/mcp.mdrestates only thecomplete_in_progressclause.checkout/embedded.mdstates a separate PUT-style replacement rule in prose at lines 1029, 1136 and 1328, each scoped to the fields a host supplies in one response (payment.instruments,fulfillment.methods, and the provided fields of a payment instruments response) and never ranging overbuyer, so consent persistence does not bear on it.source/schemas/shopping/cart.jsoncarries a "Full replacement on update" note inside theline_itemsproperty description, which governs line items only. Nothing underlodging/is affected: the buyer-consent extension declaresextends: ["dev.ucp.shopping.cart", "dev.ucp.shopping.checkout"], a booking session has nobuyerobject, andconsentdoes not appear anywhere underdocs/specification/lodging,source/services/lodgingorsource/schemas/lodging.Alternative
The other option is to require platforms to re-send the full consent map on every update once submitted. The exemption approach is proposed here as the smaller change; happy to switch if maintainers prefer the re-send contract.
Category (Required)
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Documentation rather than Core Protocol or Capability: no field is added, removed or retyped, no endpoint is introduced, and no file under
source/schemas/is touched. The two contract files changed here live undersource/services/, and what changes in each is an operationdescription, not a field description, so the Core Schema Modifications bullet ("Any change to JSON schemas, including adding/updating fields or field descriptions") does not reach them.buyer-consent.mdalready asserted that a business retains its prior position whenconsentis omitted, so this PR states which of two already published rules governs rather than introducing a third. If maintainers read the MUST-level carve-out over core Update Cart and Update Checkout as a Protocol Change under the significant-change definition, say so and this will move to an Enhancement Proposal.Related Issues
None.
Checklist
!for breaking changes).source/schemas/change.)