Skip to content

docs(consent): exempt buyer.consent from the cart and checkout full-replacement rules - #660

Open
vishkaty wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/consent-exempt-from-full-replace
Open

vishkaty wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/consent-exempt-from-full-replace

Conversation

@vishkaty

@vishkaty vishkaty commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor

Description

Problem

The buyer-consent extension says omitting consent on 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 omits buyer.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.consent and checkout.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.md and shopping/cart/index.md: add the exception note to each full-replacement rule (the checkout document already carries the complete_in_progress exception).
  • 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 a MUST over the buyer object (and so is the most on-point site, since consent is buyer.consent).
  • source/services/shopping/rest.openapi.json and source/services/shopping/mcp.openrpc.json: the update_checkout description in each states the rule with only the complete_in_progress exception. 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.md and cart/mcp.md carry no replacement statement, and checkout/mcp.md restates only the complete_in_progress clause. checkout/embedded.md states 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 over buyer, so consent persistence does not bear on it. source/schemas/shopping/cart.json carries a "Full replacement on update" note inside the line_items property description, which governs line items only. Nothing under lodging/ is affected: the buyer-consent extension declares extends: ["dev.ucp.shopping.cart", "dev.ucp.shopping.checkout"], a booking session has no buyer object, and consent does not appear anywhere under docs/specification/lodging, source/services/lodging or source/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)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps 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 under source/services/, and what changes in each is an operation description, 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.md already asserted that a business retains its prior position when consent is 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

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works. (Not applicable: prose and contract description only.)
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas. (Not applicable: no source/schemas/ change.)
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk. (Not applicable: no schema field change, so no model change.)

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 31, 2026
@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch from 44667ef to 7168971 Compare July 31, 2026 23:12
@damaz91 damaz91 added bug Something isn't working documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 3, 2026
@damaz91
damaz91 requested review from jingyli and westeezy August 3, 2026 07:52
@vishkaty

Copy link
Copy Markdown
Contributor Author

@jingyli companion to #658. This keeps captured buyer consent from being dropped by the full replacement update rules. Glad to rework if you see a better shape.

@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch 2 times, most recently from f6ad270 to 5250831 Compare August 27, 2026 00:35
@vishkaty

Copy link
Copy Markdown
Contributor Author

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.

@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Sep 20, 2026
@damaz91
damaz91 requested a review from sbeashwar September 21, 2026 10:42
@damaz91 damaz91 added the area:shopping Issues and pull requests related to the Shopping vertical label Sep 24, 2026

@sbeashwar sbeashwar 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.

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.
@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch from b7973b9 to 5db2dbe Compare October 1, 2026 00:08
@vishkaty

vishkaty commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. You are right on both counts, and the second one is a
mistake in the PR body, not a wording preference.

The body claim was wrong. The body says "The MCP and cart-rest bindings link
back to the capability docs and do not restate the rule."
source/services/shopping/mcp.openrpc.json:118 does restate it, and so does
source/services/shopping/rest.openapi.json:169. The claim was true of the
binding documents under docs/ and I wrote it as though it covered the MCP
surface as a whole. The sweep behind it grepped docs/ and not
source/services/, so the two contracts were never in view.

One mechanical detail worth recording: method_fields renders only the
parameter, request and response tables, never the operation description, so
the unqualified rule appears in no built page. It is visible only in the
published contract, which is the artifact a discovery profile schema URL
points at
(https://ucp.dev/<version>/services/shopping/mcp.openrpc.json).

Changed now. The update_checkout description in both
source/services/shopping/rest.openapi.json and
source/services/shopping/mcp.openrpc.json now carries the same carve-out
sentence as shopping/cart/index.md, with the complete_in_progress exception
left intact:

Captured buyer.consent is an exception when the buyer-consent capability is
active: an update that omits consent MUST NOT clear previously submitted
consent. See the Buyer Consent extension (dev.ucp.shopping.buyer_consent)
for the persistence rule.

The capability id is spelled out because a contract read on its own has no
relative link to follow.

A second inaccuracy in the body, which you did not flag. It also says the
embedded-* documents "mention it only in example code comments." That is
wrong too. shopping/checkout/embedded.md states a PUT-style replacement rule
in normative prose three times, at lines 1029, 1136 and 1328. It is still out of
scope, for a reason of substance rather than of form: each of the three is
scoped to the fields a host supplies in one response (payment.instruments,
fulfillment.methods, and the provided fields of a payment instruments
response), on the host to Embedded Checkout direction, and none of them ranges
over buyer. The corrected body says that instead.

Class accounting. Nine sites match full replacement on main at b0e81ad
before this branch:

Site Status Basis
docs/specification/shopping/cart/index.md:213 changed by this PR Update Cart full-replacement rule
docs/specification/shopping/checkout/index.md:1078 changed by this PR Update Checkout full-replacement rule
docs/specification/shopping/checkout/rest.md:231 changed by this PR REST Update Checkout rule
source/services/shopping/rest.openapi.json:169 changed now update_checkout description, machine consumed
source/services/shopping/mcp.openrpc.json:118 changed now update_checkout description, machine consumed
source/schemas/shopping/cart.json:55 out of scope the note sits inside the line_items property description and governs line items only; consent rides buyer.consent
docs/specification/lodging/booking/index.md:526 out of scope lodging, see below
docs/specification/lodging/booking/rest.md:520 out of scope lodging, see below
source/services/lodging/rest.openapi.json:173 out of scope lodging, see below

Four further sites state the same rule in other words and are listed for
completeness:

Site Status Basis
docs/specification/shopping/checkout/rest.md:244 Update Buyer Info changed by this PR draws the drop-if-omitted consequence as a MUST over buyer
docs/specification/shopping/extensions/buyer-consent.md:373 changed by this PR the persistence rule itself, now named as the exception
docs/specification/shopping/checkout/embedded.md:1029,1136,1328 out of scope per-field PUT-style replacement, scoped to payment.instruments, fulfillment.methods and the provided fields of one host response, never buyer
docs/specification/lodging/booking/rest.md:531 out of scope lodging, see below

Why lodging is out of scope. Three independent checks:

  1. The extension declares its own reach. The discovery profile in
    buyer-consent.md lists extends: ["dev.ucp.shopping.cart", "dev.ucp.shopping.checkout"], and
    source/schemas/shopping/buyer_consent.json composes exactly
    dev.ucp.shopping.cart and dev.ucp.shopping.checkout. Lodging appears in
    neither.
  2. A case-insensitive grep for consent over docs/specification/lodging,
    source/services/lodging and source/schemas/lodging returns zero matches,
    under that name or any other. The nearest hits are privacy_policy entries
    in links arrays, which are compliance links a platform displays, not a
    consent record.
  3. A booking session has no buyer object to hang consent on. Its party
    fields are guests, booker, travel_purpose and
    stays[].guest_assignments.

So the carve-out has nothing to attach to under lodging. If a lodging consent
concept lands later, docs/specification/lodging/booking/index.md:526,
rest.md:520 and rest.md:531, and
source/services/lodging/rest.openapi.json:173 are the four sites that will
need the same treatment.

One gap I am leaving alone. Neither contract states the full-replacement rule
for update_cart at all: rest.openapi.json has "Update a cart session." and
mcp.openrpc.json carries no description for update_cart at all. Stating the
rule there would be adding it rather than qualifying it, so it is outside what
this PR closes. Happy to open a separate PR if you want the contracts to carry
the Update Cart rule too.

Category. Recommending Documentation; the corrected body checks that
box. The grounds: no field is added, removed or retyped, no endpoint is introduced, and
no source/schemas/ file is touched. The two files changed now are service
contracts under source/services/, and the edit is to an operation
description. On behavior, buyer-consent.md already asserted that a business
"retains its prior position" when consent is omitted, so this PR states which
of two already published rules governs rather than introducing a third. Reading
the significant-change definition, that is not a Core Schema Modification and
not a Protocol Change.

Where I think you could reasonably disagree: the carve-out is a MUST over core
Update Cart and Update Checkout, and a maintainer who reads "Protocol Changes:
Alterations to communication flows or expected behaviors of operations" broadly
could put it under Protocol Changes. If that is the call, I will file an
Enhancement Proposal and relabel. Say which and I will follow it.

Verification re-run 2026-09-30 on a rebase onto main b0e81ad, all exit 0:
ucp-schema lint source/, validate_examples.py --schema-base source/schemas/
on the full corpus and on the changed files, the validator and link-checker unit
tests, the pinned pre-commit hooks on all six changed files, yamllint,
DOCS_MODE=spec mkdocs build --strict and check_links.py. Diffing the whole
built site before against after shows exactly two files changed, the two
published contracts, with specification/shopping/checkout/index.html byte
identical. Your three cross references still resolve after the rebase.

@sbeashwar sbeashwar 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.

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.

@damaz91
damaz91 requested review from karangoel16 and removed request for westeezy October 14, 2026 14:50

@karangoel16 karangoel16 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.

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.

@damaz91 damaz91 removed bug Something isn't working status:stale-review Applied if a PR is waiting on a reviewer for too long labels Oct 19, 2026
@damaz91 damaz91 added the gov:needs-tc-review Requires review and approval from the Technical Council label Oct 19, 2026
@damaz91

damaz91 commented Oct 19, 2026

Copy link
Copy Markdown
Contributor

@jingyli given this PR touched normative clauses of the documentation, can you take a look?

@damaz91 damaz91 moved this to Triage / Unscheduled in DTC Review Pipeline Oct 29, 2026

This branch has not been deployed

No deployments
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 documentation Improvements or additions to documentation gov:needs-tc-review Requires review and approval from the Technical Council

Projects

Status: Triage / Unscheduled

Development

Successfully merging this pull request may close these issues.

5 participants