add path targeting to Request Constraints

[igrigorik]

#655 defines a reusable closed Constraint Expression grammar, but the response location alone does not always identify the request data to validate. For example, a constraint attached to a response Line Item could mean the item at the same array position, the item with the same identity, or some other request object. The ambiguity becomes unavoidable when arrays reorder or when response and request shapes differ, such as an available payment instrument constraining a submitted instrument.

---

This PR adds an optional, outer-only path to Request Constraints. An explicit path is a complete RFC 9535 JSONPath query evaluated against the next logical UCP request to the same resource. When omitted, the effective path is derived from the RFC 9535 Normalized Path of the structured response object whose ucp member contains the constraint.

The omission behavior preserves concise ambient authoring. A constraint on the response root derives $; a constraint on a nested object derives that object's positional path. That positional correspondence is deterministic but does not imply stable identity. Authors use an explicit query when a rule must survive reordering, select multiple objects, or bridge different response and request shapes.

A path may select zero, one, or many objects. Zero matches have no effect, while every selected object must satisfy the complete Constraint Expression. Overlapping constraints compose conjunctively without precedence or override, and the Business must ensure potentially overlapping expressions are jointly satisfiable. These checks narrow the resolved request schema; they cannot make an otherwise invalid request valid.

Binding shape

The chosen wire shape keeps path beside the root members of the expression:

{
  "path": "$['line_items'][?@['id'] == 'line_123']",
  "properties": {
    "quantity": {"const": 100}
  }
}

One considered alternative was separating path from constraint expression:

{
  "path": "$['line_items'][?@['id'] == 'line_123']",
  "expression": {
    "properties": {
      "quantity": {"const": 100}
    }
  }
}

The benefit of the latter is that keeps expression strict subset of JSONSchema. The cost is permanent wire noise in the common case. Most constraints use ambient placement and omit path, so even a simple local requirement would need an otherwise meaningless wrapper:

{
  "expression": {
    "required": ["billing_address"]
  }
}

The selected shape optimizes for the authoring and wire surface rather than schema-factoring purity. constraint_expression.json remains direction-neutral and contains no path; request_constraints.json is the closed binding that admits path only at its root and re-exposes the root Object Constraint members. Recursive constraints continue through the pure expression schema, so nested path members remain invalid. The trade-off is that future changes to the root Object Constraint must also be reflected in request_constraints.json.

This preserves the core invariant that one binding carries one schema. It avoids introducing a list of independently targeted rules, repeated navigation, target precedence, or another orchestration model alongside JSON Schema.

[raginpirate]

Thanks for all the deep thinking here Ilya. Approving, with a note from our discussion in the deep dive earlier.

Another solution is to put checkout.ucp.request_constraints on the response root as a single property, which carries an array of constraints and their paths in one place. As you mentioned, an implementer could even choose to do this.

In a vacuum, I think thats the simple solution, as it avoids having to walk the tree to assemble all the fragments you'll evaluate to restrict your json schema. However, I'll concede that it is very nice to keep the constraints authored in a semantically-relevant place in the schema; something I care deeply about for our payment requests 😄

Lets land this thing!

[gsmith85]

Thanks for driving this through, @igrigorik! This looks great and aligns with what we discussed in the deep dive.

Adding RFC 9535 path targeting gives us the precision needed for array reordering and payment shape bridging while keeping the common ambient case clean and flat. LGTM! 🚀

[jamesandersen]

I was a bit late to the party here ... but agree this is a good catch and addition @igrigorik - thanks!