Skip to content

docs(split-payments): validate the allowed_combinations profile example - #658

Merged
damaz91 merged 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/split-payments-profile-example
Nov 16, 2026
Merged

damaz91 merged 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/split-payments-profile-example

Conversation

@vishkaty

@vishkaty vishkaty commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor

Problem

The only business-profile example for the split payments extension is annotated <!-- ucp:example skip -->, so CI never validates it, and it does not match the profile schema in three ways:

  1. capabilities is an array, but ucp.json defines it as an object map keyed by reverse-domain name.
  2. The capability entry omits the required schema URL (capability.json business_schema requires schema).
  3. It pinned "version": "2026-01-23", a release that does not contain this extension. Main has since changed that line to {{ ucp_version }} independently, so this branch no longer touches it and problem 3 is already resolved.

Validating the fragment against the profile schema fails on the capabilities type and then on the missing schema property; it passes once rewritten as a map with a schema URL.

Fix

Rewrite the example in the ucp.capabilities map form with spec, schema, extends, and {{ ucp_version }}, mirroring the buyer-consent profile example, and replace the skip annotation with a validated schema=profile def=business_schema annotation so CI covers it going forward.

extends: ["dev.ucp.shopping.checkout"] names the parent capability this business profile entry extends. common/payment_split_payments.json extends both dev.ucp.shopping.checkout and dev.ucp.lodging.booking, with one extended data schema per parent under $defs, and declares its single business_schema under $defs["dev.ucp.common.payment.split_payments"]. The example declares the checkout parent it uses.

Verification

scripts/validate_examples.py full corpus goes from 398 to 399 passing (53 to 52 skipped): the example flips from skipped to validated. ucp-schema lint source/ unaffected. Counts re-measured on 2026-10-08 after rebasing onto main.

Two corrections to an earlier version of this body. It cited a requires key on checkout in split_payments.json: that file is common/payment_split_payments.json since #741,
and it has no requires key at any depth, so both the name and the key were wrong.
And on scope, worth being precise about what the annotation buys: the profile schema
validates the capability envelope, the version, spec and schema URLs, extends, and that
config is an object. It does not reach inside config, so allowed_combinations
content is still unvalidated by CI. I checked the example by hand against
types/business_split_payments_config.json and it is valid. Reaching it automatically
needs def= to accept a nested path, which is a separate change.

A third correction, to the Fix section above. It said this file declares a business_schema
under $defs for both dev.ucp.shopping.checkout and dev.ucp.lodging.booking. It does
not. Those two $defs entries are the extended data schemas, one per parent, and neither
contains a business_schema. The only business_schema in the file sits under
$defs["dev.ucp.common.payment.split_payments"]. The point the sentence was making stands,
that the extension targets both parents so extends has to name the one in use, but the
structure is as now described.

@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage 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 Jul 31, 2026
@vishkaty

vishkaty commented Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

A gentle note on this and its sibling docs and schema PRs (#659, #660, #661, #662, #669, #670, plus #625): all eight are rebased onto current main, conflict free, and validate_examples passes on each. They are independent of one another, so they can be reviewed in any order or batched, whatever is easiest. Happy to adjust any of them.

@dkoch74 dkoch74 added the area:payments Issues and pull requests related to the Payments vertical label Aug 5, 2026
@vishkaty

Copy link
Copy Markdown
Contributor Author

Following up on this docs and schema batch (#658, #659, #660, #661, #662, #669, #670, #625): all eight are still green on current main, conflict free, and independent, so any subset can be merged in any order. If the batch size is the awkward part, I am glad to fold the docs-only ones into a single PR to cut the review overhead, whatever is easiest on your side. No urgency at all, just flagging they are ready whenever the queue allows. Thanks @damaz91.

@vishkaty

Copy link
Copy Markdown
Contributor Author

@jingyli you are a requested reviewer here, so flagging this quiet one. Small fix so the split payments profile example actually validates against the profile schema. Glad to adjust anything.

@dkoch74

dkoch74 commented Aug 17, 2026

Copy link
Copy Markdown
Member

@knightlin-shopify I am supportive of fixing this example - could you please review?

@vishkaty
vishkaty force-pushed the fix/split-payments-profile-example branch 2 times, most recently from 82d20c2 to bd08cce Compare August 27, 2026 00:35
@vishkaty

Copy link
Copy Markdown
Contributor Author

Updated the spec URL in the example to the post-reorganization path, specification/payment/extensions/split-payments, matching what the other extension profiles carry on current main. The rest of the example is unchanged.

@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 21, 2026
@damaz91
damaz91 requested review from kmcduffie and yanheChen and removed request for knightlin-shopify September 21, 2026 10:42
@vishkaty
vishkaty force-pushed the fix/split-payments-profile-example branch from 7571d2a to 9f836a5 Compare October 8, 2026 03:42

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

Verified against the profile schema: the capabilities map form, the required schema URL, and extends are all correct, and the annotation matches the existing precedent.

The only business-profile example for the split payments extension was
annotated `ucp:example skip`, so CI never checked it, and it did not match
the profile schema three ways: `capabilities` was an array where the schema
defines an object map keyed by reverse-domain name, the entry omitted the
required `schema` URL, and it pinned `version: 2026-01-23`, a release that
does not contain this extension.

Rewrite the example in the `ucp.capabilities` map form with `spec`, `schema`,
`extends`, and `{{ ucp_version }}`, mirroring the buyer-consent profile
example, and replace the skip with a validated
`schema=profile def=business_schema` annotation so CI covers it going forward.

Full corpus: 283 passed (was 282), 47 skipped (was 48).
The example wrote the pre reorganization flat path. Every extension
profile on current main carries the full reorganized path, so the
example now matches, specification/payment/extensions/split-payments.
@vishkaty
vishkaty force-pushed the fix/split-payments-profile-example branch from 9f836a5 to 1bcec24 Compare October 11, 2026 23:21
@damaz91 damaz91 removed the status:stale-review Applied if a PR is waiting on a reviewer for too long label Oct 12, 2026
@damaz91
damaz91 requested a review from archrao October 12, 2026 08:44
@damaz91

damaz91 commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

@archrao @kmcduffie can either of you take a quick look here? Thanks

@damaz91
damaz91 requested review from xiaoxuanz-hub and removed request for kmcduffie October 14, 2026 14:50
@damaz91
damaz91 requested review from karangoel16 and removed request for yanheChen October 23, 2026 12:25
@damaz91
damaz91 merged commit 8c56188 into Universal-Commerce-Protocol:main Nov 16, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:payments Issues and pull requests related to the Payments vertical bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants