How are custom Mandate Constraints expected to compose with the canonical JSON Schemas?

[arjun2075]

I'm looking at the Mandate Constraints extension point in AP2 v0.2 and wanted to clarify the intended schema model for third-party constraints.

The specification says that new Mandate Constraints can be defined by specifying a unique type, a schema including selective-disclosure behavior, and an evaluation algorithm.

However, the current canonical open_checkout_mandate.json schema appears to constrain constraints[] with an anyOf containing the currently defined checkout.allowed_merchants and checkout.line_items types.

For example, suppose an integration defines a constraint conceptually like:

{
  "type": "com.example.checkout.some_constraint",
  "value": "..."
}

with its own schema and deterministic evaluation algorithm.

What is the intended way for that constraint to compose with mandate.checkout.open.1 while still validating against the canonical AP2 schemas?

A few possible models occurred to me:

1. the base mandate schema permits externally defined constraint objects and validation dispatches based on type;
2. AP2 defines a schema composition / registry mechanism for constraint extensions;
3. a constraint needs to be incorporated into AP2's canonical mandate schema before it can be interoperably used;
4. custom constraints are expected to use a separately profiled/versioned mandate schema.

I don't want to assume a particular model if there is already an intended extension mechanism.

Clarifying this would also seem useful for implementers building independent constraint extensions, since otherwise a constraint can satisfy the specification's extension requirements while still failing validation against the reference schema.

Is there an existing convention or planned mechanism for this that I've missed?

[chopmob-cloud]

You have identified the real friction precisely: "a constraint can satisfy the specification's extension requirements while still failing validation against the reference schema". It is worth separating two things the schema is doing at once. Structural validation asks whether the constraint object is well formed and permitted to appear in constraints[]. Evaluation asks whether a verifier can actually enforce the constraint's meaning. A closed anyOf, as you observe, couples them: an object whose type sits outside the two named branches cannot even be admitted, so an extension is rejected before its evaluation algorithm is ever consulted.

Reading the four models you list along a coordination axis is clarifying. Only your first, in which the base mandate schema would admit externally typed constraint objects and dispatch on type, would let a previously unseen constraint pass structural validation without the verifier holding prior knowledge of it. Your registry, canonical incorporation, and profiled schema models would each require a coordination step first: registration, a specification change, or agreement on a profile identifier. That is not a criticism of them, it just means only the first supports open extension by strangers. One minimal shape that would enable it, purely as a proposal, is an anyOf wildcard arm that would accept any object whose type falls outside the current named branches and carries the common required fields, leaving enforcement to dispatch on type.

Underneath the schema question is a governance one: whether AP2 intends unknown typed constraints to interoperate at all, or only those it has blessed. If the aim is open extension, the base schema has to admit objects it was not written against. If the aim is a closed set that grows by adoption, then the registry or incorporation models fit and the current closed anyOf is working as intended. Which of those two is AP2 aiming for, and if it is the open one, would a wildcard arm keyed on a reserved namespace be an acceptable shape, or do the selective disclosure requirements need something a generic arm could not express?

[arjun2075]

Apologies for missing this earlier. This is a useful framing, and I think the distinction between structural admission and evaluation is exactly the right one.

One clarification on the first model: allowing a previously unseen type through the base mandate schema would not, by itself, make that constraint interoperable. The verifier — and, where applicable, the Trusted Surface producing the selectively disclosed representation — still needs to understand the extension's schema, selective-disclosure rules, and deterministic evaluation algorithm. If it does not support that constraint type, it should fail closed rather than ignore it.

That said, the mismatch you identified is real. The specification describes Mandate Constraints as an extension point defined by a unique type, a schema, and an evaluation algorithm, while the current open_checkout_mandate.json schema admits only the built-in checkout.allowed_merchants and checkout.line_items branches. So today the reference schema is more restrictive than the extension model described by the specification.

The direction that seems cleanest is to separate the layers: the base mandate schema should be able to structurally carry an externally defined constraint without requiring a revision to mandate.checkout.open.1; the constraint-specific schema should then be selected based on type and used for field/selective-disclosure validation; and evaluation should dispatch to the deterministic evaluator for that type. A verifier that does not support the type rejects it.

A wildcard arm could solve the first part, but a namespace alone would not solve the whole problem. We would still need a convention for identifying/versioning the extension schema and its evaluation semantics. So I would frame the goal as “external constraints can be carried without changing the base mandate schema,” rather than “unknown constraints are accepted.”

That makes the governance question slightly narrower: should third parties be able to define constraint types without requiring a change to the canonical mandate schema, while actual interoperability still requires the relevant parties to explicitly support that extension? If that is the intended model, then the specification and reference schema should be aligned to express it.