feat: add response-carried request constraints

[igrigorik]

Depends on #657.

Static request schemas describe the inputs a Business generally accepts, but not narrower requirements for a particular transaction. Without response-time constraints, a Platform learns that a negotiated quantity is fixed or an otherwise optional field is required only after submission fails—or through domain-specific constraint formats.

PR #657 establishes the ambient ucp protocol namespace and central member registry. This PR adds request_constraints to that vocabulary instead of inventing a parallel structural namespace.

• Registers response-only ucp.request_constraints in ucp.json#/$defs/members.
• Defines a closed JSON Schema Draft 2020-12 value grammar using required, properties, enum, and const.
• Lets a Business communicate and authoritatively enforce transaction-specific input constraints.
• A Platform MAY use the member to form or validate a request, or safely ignore it and rely on Business validation.
• Applies the fragment alongside the resolved request schema; both validations must pass, equivalent for validity to allOf without schema merging.
• Uses the containing ucp scope to identify the constrained parent object; adopting contracts define correspondence and lifecycle when existing operation semantics do not.

Examples

A Cart Line Item fixed at quantity 100:

{
  "id": "line_123",
  "quantity": 100,
  "ucp": {
    "request_constraints": {
      "properties": {
        "quantity": {"const": 100}
      }
    }
  }
}

A submitted card instrument that requires a billing address for this transaction:

{
  "type": "card",
  "ucp": {
    "request_constraints": {
      "required": ["billing_address"]
    }
  }
}

Boundaries

This PR does not define payment availability, custom assertion keywords, schema merging, or new outcomes and error codes. Payment-specific correspondence and availability remain downstream.

[jamesandersen]

Consolidating the concerns raised across this constraints arc (#288 → #424 → #580 → #626) and where each lands under request_constraints, assuming this + #657 supersedes the #424/#626 availability-constraint refactor rather than coexisting with it.

Legend: ✅ resolved / moot · ⚠️ partial or deliberately out of scope · ❌ not addressed

#	Concern	Raised on	By	Status under #655
C1	Convey per-transaction constraints so a platform learns them before completing, not via submit-and-fail (incl. "is CVV required?")	#288	@jamesandersen (upfront framing revisited on #424 by @igrigorik)	✅ Core purpose. Response-carried → create-then-complete, no failure loop. Depends on a payment correspondence + lifecycle contract, still downstream.
C2	Field-name/typo validation (billing_addr vs billing_address)	#288 (reraised #626)	@alexpark20 (later @raginpirate)	⚠️ Out of scope by design — authoring-time concern, not wire-validation. Smaller blast radius since the business both authors and enforces.
C3	Brittle named booleans/enums; constraints should mirror the target schema	#288	@gsmith85, @kmcduffie	✅ Superseded by the structural JSON-Schema-subset grammar.
C4	Polymorphic credential discrimination — a cvc requirement must not apply to a token branch	#288 / #424	@raginpirate, @gsmith85	⚠️ Partial. No type dispatch, so "cvv only for the card credential, not the token credential" within one instrument isn't expressible in the grammar. Cleanest fix is structural, not conditional: reviving the distinct network-token credential from #424 (@raginpirate) makes discrimination positional and request_constraints needs no if/then.
C5	Enforcement gap — the type discriminator didn't drive validation; malformed configs passed	#424	@TateLyman, @jamesandersen, @igrigorik	✅ Moot by design — the business is the authoritative enforcer; correctness no longer rides the platform's schema validator.
C6	constraints not truly generic / extension-friendly (allOf only narrows)	#424	@igrigorik	✅ Sidestepped — grammar is closed + core-owned. Arbitrary target fields (incl. extension-defined) can still be constrained; only new predicate kinds can't be added.
C7	Credential inception — nested cvc on a raw card behind a provider token	#424	@raginpirate	⚠️ Structural nesting is expressible; type-conditional nesting isn't. Non-blocking IMO; @raginpirate WDYT?.
C8	Expressiveness / locality — assertions that aren't presence-or-value: accepted-value menus (brands), numeric ranges (B2B min/max qty), relational predicates	#580 / #626	@raginpirate (ack @igrigorik)	✅ Division of labor. request_constraints handles transaction-time presence/value narrowing; advertised/specialized/derived constraints keep living in the instrument schema's existing constraints member (e.g. card_payment_instrument.constraints.brands). Less uniform, but no regression.
C9	options over-strict typing (additionalProperties = string-arrays; credentials a hardcoded exception)	#626	@raginpirate	✅ Dissolved — there's no options axis.
C10	properties-keyword collision (the reason #424/#626 used direct keys)	#626	@igrigorik	✅ Resolved — applied as a standalone fragment, so literal properties carries no merge collision.

Net: this arc has genuinely come a long way. The debates that took the most back-and-forth — genericity (C6), where enforcement lives (C5), the properties collision (C10) — are effectively settled here, and the original #288 goal of surfacing constraints early enough to skip a doomed round-trip (C1) is finally within reach. What's left feels like a couple of deliberate, eyes-open choices rather than open problems: reviving the distinct network-token credential from #424 so discrimination is structural instead of conditional (C4), and being explicit that advertised/specialized constraints stay in the domain schema's constraints member while request_constraints owns transaction-time narrowing (C8). We're close.

[jamesandersen]

@igrigorik @raginpirate — overall this is feeling good to me. Two things I'd love to get thoughts on before stamping though:

1. C4. from the table comment above... request_constraints handles flat presence/value fine (required: ["billing_address"] etc.). Where it still falls short is anything conditioned on a value inside the target object e.g. the polymorphic card credential — e.g. "require cvc for a raw PAN but not a network token". This is where @raginpirate you wanted to go with Allow anyOf and an open expansion of schema overlays ontop of 655 #705 right?:

{
  "ucp": {
    "request_constraints": {
      "anyOf": [
        { "properties": { "card_number_type": { "enum": ["fpan", "dpan"] } }, "required": ["cvc"] },
        { "properties": { "card_number_type": { "const": "network_token" } }, "required": ["cryptogram"] }
      ]
    }
  }
}

The closed subset (required/properties/enum/const) can't branch, so today it's cvc always or never.

Honestly I'd rather land a solution that finally does address that case which was the impetus for this journey. But I'm OK taking this as-is for the incremental progress it brings. IIUC, either path to closing the gap layers on as a clean backwards-compatible change: structural separation of card credential types (#424) OR extending the request_constraints vocabulary (#705, e.g. anyOf).

Nit for if we do the vocabulary route: since the meta-schema is additionalProperties: false, we should spell out that an unrecognized construct means "ignore + defer to Business," not "reject."

2. "Options" e.g. domain specific constraints that don't layer onto the request schema e.g. card brands in the payment handler example. We started discussing whether there was a clean way to bundle them together OR whether to just leave them separate (putting a bit more burden on both schema authors and implementers to express constraints in different ways. We are here introducing a 2nd way of expressing "constraints" ... but I think the principle is straightforward in that this mechanism can and should be used for additional constraints on the subsequent request schema. I'm comfortable that - given the long PR arc - there's not a straightforward way we've missed to cleanly model both kinds of constraints together so I don't consider this a blocking concern personally.

WDYT on these two topics?

CC @gsmith85

[igrigorik]

@jamesandersen @raginpirate ptal at 30b0b3e. That refactor extracts the closed executable language from its first binding and enables additional target-specific bindings:

constraint_expression.json = reusable closed grammar
request_constraints.json = grammar bound to subsequent request data
future payment_acceptance_constraints.json  = same grammar bound to ~payment acceptance facts

In other words: different targets and carriers, but one executable constraint language. ucp.request_constraints is the ambient response-carried binding over data in a subsequent platform request, covering rules such as requiring billing_address, pinning a negotiated quantity, or constraining a submitted credential field.

A payment-owned binding could reuse the same grammar without requiring its target to appear on the wire. Payment might define a logical target derived from an instrument or credential:

PaymentAcceptanceFacts {
  brand,
  credential_type,
  is_po_box
}

It could then express accepted brands using the shared grammar:

{
  "properties": {
    "brand": {
      "enum": ["visa", "mastercard"]
    }
  }
}

The payment contract would own how those facts are derived, where the expression is carried, and its authority and lifecycle; Constraint Expression would own the executable operations and evaluation semantics. Request Constraints and payment acceptance constraints can therefore remain separate because they have different targets and lifecycles while sharing one evaluator contract. This preserves an N + M model—N domains define target bindings and M Platforms implement the grammar once—instead of every handler introducing executable keywords that every Platform must separately understand.

This PR does not define PaymentAcceptanceFacts, add a payment acceptance binding, or change the existing constraints.brands shape. It establishes the reusable language boundary that lets payment adopt the grammar in a focused follow-up.

Polymorphic branching and anyOf

C4 is a separate expressiveness question. The current grammar cannot express “require cvc for FPAN/DPAN and require cryptogram for a network token” while allowing both branches. I still see the same two additive paths you called out:

1. structurally separate the credential variants so constraints are attached after subtype selection; or
2. centrally admit standard Draft 2020-12 anyOf into Constraint Expression.

If admitted, anyOf would remain part of a closed UCP-owned grammar: each branch would recursively use Constraint Expression, while arbitrary handler-defined predicate keywords would remain invalid. Because the vocabulary now lives in constraint_expression.json, that decision would be made once and inherited by Request Constraints and any future domain binding.

The fallback is already explicit: a Platform validates the complete member against the shared grammar it supports, ignores a nonconforming member, and relies on authoritative Business enforcement. A successful best-effort preflight never claims that every Business constraint has passed.

My read is therefore that this PR establishes the common closed grammar and its binding to subsequent request data without closing either follow-up. A concrete payment target and binding remain payment work, while polymorphic branching remains a focused choice between structural separation and centrally admitting anyOf; neither needs to block the request constraints foundation.

[jamesandersen]

small nit: With 30b0b3e separating the constraints schema from request_constraints (for potential reuse) should it be bumped out to be described outside of the request_constraints section? ... IMO probably best left until there's a second use case for it (e.g. follow-up on payment facts)

[raginpirate]

As a follow up... do we actually need the intent of why we separated the layers described in this document? I just find this paragraph is telling me more about the history of this PR rather than what I need to know to author using the constraints concept.

[gsmith85]

LGTM! 🚀

The composition model (allOf intersection over the resolved request schema) is solid and keeps validation strictly within standard JSON Schema. The grammar/carrier separation sets up future domain bindings nicely.

[amithanda]

It will be useful for schema authors to have clear guidelines on whether a business requirement should be modeled proactively as a request_constraints rule or left to reactive messages validation. This prevents authors from misusing request_constraints for volatile or runtime-evaluated state (such as live inventory or fraud scoring).

Should we add something like below:

Suggested change

	### When to use `request_constraints` vs. `messages`
	Capability designers should use the following heuristic when deciding how to
	model business requirements:
	| Criterion | Use `request_constraints` | Use standard `messages` |
	| :-- | :-- | :-- |
	| **Temporal Role** | Proactive preflight for subsequent request *N+1*. | Reactive diagnostic for submitted request *N*. |
	| **Rule Stability** | Deterministic and known in current response. | Evaluated dynamically at execution time. |
	| **Primary Goal** | Machine preflight and round-trip elimination. | Explaining execution outcomes or failure reasons. |
	Use `request_constraints` for rules known in advance (e.g., fixed purchase lot
	quantities, locked discount codes, or required billing fields). Use `messages`
	when validation depends on real-time execution state (e.g., live inventory
	availability, fraud checks, payment authorization) or when reporting why a
	submission failed.

[raginpirate]

I don't think this concern lands on schema authors. request_constraints is registered once in ucp.json#/$defs/members and no capability schema declares it — there's no authoring-time decision to guide. messages, by contrast, is declared per-capability. The choice isn't for that party.

Aligning with you though, it might be worth a simple line or two in the overview to inform businesses that it is detrimental for them to enforce requirements on volatile, changing properties in schemas.

[vishkaty]

One wiring note on the registration: nothing in source/schemas references ucp.json#/$defs/members, so resolved schemas never apply the member grammar. At 14df500 with ucp-schema 1.4.1 a Cart response carrying request_constraints {"bogus": 1} validates in default mode, and strict mode rejects the documented Cart example since the member is unevaluated. Exposing the member through #/$defs/base the way map_order is, or shipping the materialization described in schema-authoring.md with the release, would close both.

[amithanda]

Added minor non-blocking documentation suggestions to make the distinction clearer between request constraints and existing messages based mechanism. PTAL.

[raginpirate]

I think we're missing some fundamental prose around how to handle the path to constrain against as a platform, lmk your thoughts

[raginpirate]

As a follow up... do we actually need the intent of why we separated the layers described in this document? I just find this paragraph is telling me more about the history of this PR rather than what I need to know to author using the constraints concept.

[raginpirate]

I don't think this concern lands on schema authors. request_constraints is registered once in ucp.json#/$defs/members and no capability schema declares it — there's no authoring-time decision to guide. messages, by contrast, is declared per-capability. The choice isn't for that party.

Aligning with you though, it might be worth a simple line or two in the overview to inform businesses that it is detrimental for them to enforce requirements on volatile, changing properties in schemas.

[raginpirate]

Also wanted to add; thank you so much for continuing to iterate here @igrigorik.
I spent the entire weekend obsessing over how we can best define constraints for payments and I'm still hitting frustrating edges with it, so my polish on that end is going to continue taking time.
Regardless of how I think I want the shape of the base constraint object to evolve, I realized that because we're making it closed here, its non-extensible, so we are free to change it across versions as long as the evaluation of the schemas over the wire remain consistent.
tldr; I'll continue iterating in the background while we try to wrap up this primitive.

[raginpirate]

🚀 🚀 🚀 🚀

[raginpirate]

@igrigorik one quick note before this merges, PTAL at #424.
I found I required turning request_constraints into an array in order to support navigating 2 separate id paths at this time, essentially solving a need to ever define anyOf. Let me know if this is the right path and if you want to unify that into this PR before merging.

[igrigorik]

@raginpirate you walked right into the design question I wrestled for hours while iterating on options for #744. Short answer: the array works, but I don't think it is the right primitive for #424, and I would not fold it into #655.

JSON Schema can express the contract you're after. The reason the array feels necessary is that our current grammar does not admit anyOf.

As a side note, yes, an array can also produce a more compact representation for some rule sets. The explicit trade-off is that we double down on UCP-specific constraint resolution: JSONPath filters become conditional control flow, and the member becomes a list of independently targeted rules with its own composition and partial-evaluation semantics. The invariant behind #744 was “one binding carries one schema”: prefer standard schema structure before introducing a rule sheet.

Crucially, the array does not replace vocabulary evolution; it only routes around anyOf for this one filter-addressable branching pattern. We would still need to decide whether to admit items, conditionals, numeric assertions, cardinality, and other standard operations. Saying yes here leaves us maintaining both the UCP-specific rule sheet and the evolving JSON Schema subset. My preference is to force the actual vocabulary conversation instead: should the shared grammar admit anyOf, and which standard structural operations should we explore next? As a broader reference / map...

JSON Schema vocabulary	What it unlocks	Status
required	Transaction-specific field presence, such as requiring billing_address.	In #655
properties	Structural descent into nested request objects.	In #655
enum / const	Accepted values, exact values, and pinned discriminators.	In #655
items	Applying one constraint structurally to every array element.	Candidate
anyOf	Alternative polymorphic request shapes, including PAN versus network-token requirements.	Concrete next candidate
if / then / else	Conditional requirements not naturally expressed as alternatives.	Later candidate
allOf	Multiple independent conditional rules over one instance; sibling assertions already cover simple conjunction.	Later candidate
Numeric and cardinality assertions	Dynamic ranges, increments, and collection limits when concrete cases justify them.	Later candidates

The benefit of this path is that we retain a simple evaluator contract: UCP owns the binding step through path, while the expression evaluated against every selected object remains ordinary 2020-12 JSON Schema with a deliberately closed subset. Businesses and Platforms get familiar validator semantics rather than a second UCP rule-sheet language.

In the #424 case, one path selects the submitted card instrument and a nested anyOf expresses the PAN and network-token branches. That is exactly the kind of concrete request-shaped use case we said should justify centrally adding a standard keyword. It is also narrower than #705 as written: admit standard anyOf into the closed grammar, without opening handler-defined predicate keys.

So my steer and preference is: keep request_constraints object-valued, keep the PAN/network-token structural split, and take anyOf as the focused core follow-up.

[raginpirate]

Re-approving; thanks for the feedback on array form. Happy to align in this direction 😄