feat: structured constraints for instruments and beyond

docs/specification/playground.md

@@ -990,7 +990,7 @@ class UcpApp {
   }
 
   prepareUpdatePayload(checkoutResponse) {
-    const patch = { id: checkoutResponse.id }; // deprecated: id is provided in URL path
+    const patch = {}; // id is provided in URL path
     const errors = checkoutResponse.messages || [];
 
     if (errors.some(e => e.path === "$.buyer.email")) {

source/schemas/shopping/types/address_constraint.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/types/address_constraint.json",
+  "title": "Address Constraint",
+  "description": "Constraint on a postal address. Reusable across UCP — payments uses this for billing addresses, fulfillment can reuse it for shipping addresses. The requirement of the address field itself is owned by the parent's `required_fields` (e.g., an instrument constraint listing `\"billing_address\"` in its own `required_fields`); this object only describes what fields of the address must be populated when the address is present.",
+  "allOf": [
+    { "$ref": "constraint.json" },
+    {
+      "type": "object",
+      "properties": {
+        "required_fields": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "street_address",
+              "extended_address",
+              "address_locality",
+              "address_region",
+              "address_country",
+              "postal_code",
+              "first_name",
+              "last_name",
+              "phone_number"
+            ]
+          },
+          "uniqueItems": true
+        }
+      }
+    }
+  ],
+  "examples": [
+    { "required_fields": ["postal_code", "address_country"] },
+    {
+      "required_fields": [
+        "street_address",
+        "address_locality",
+        "address_region",
+        "postal_code",
+        "address_country"
+      ]
+    }
+  ]
+}

source/schemas/shopping/types/card_credential.json

@@ -2,76 +2,64 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/card_credential.json",
   "title": "Card Credential",
-  "description": "A card credential containing sensitive payment card details including raw Primary Account Numbers (PANs). This credential type MUST NOT be used for checkout, only with payment handlers that tokenize or encrypt credentials. CRITICAL: Both parties handling CardCredential (sender and receiver) MUST be PCI DSS compliant. Transmission MUST use HTTPS/TLS with strong cipher suites.",
+  "description": "A card credential whose verification scheme is the card verification code (CVC). The `number` field MAY carry an FPAN, a network token, or a wallet-issued token — the credential type is defined by its verification fields, not by the underlying PAN form. CRITICAL: Both parties handling card credentials with raw FPANs MUST be PCI DSS compliant. Transmission MUST use HTTPS/TLS with strong cipher suites.",
   "allOf": [
-    {
-      "$ref": "payment_credential.json"
-    },
+    { "$ref": "payment_funding_source.json" },
     {
       "type": "object",
-      "required": [
-        "type",
-        "card_number_type"
-      ],
+      "required": ["type", "number"],
       "properties": {
         "type": {
           "const": "card",
-          "description": "The credential type identifier for card credentials."
-        },
-        "card_number_type": {
-          "type": "string",
-          "enum": [
-            "fpan",
-            "network_token",
-            "dpan"
-          ],
-          "description": "The type of card number. Network tokens are preferred with fallback to FPAN. See PCI Scope for more details."
+          "description": "The credential type identifier."
         },
         "number": {
           "type": "string",
-          "description": "Card number.",
-          "examples": [
-            "4242424242424242"
-          ]
+          "description": "Card number. May be an FPAN, network token, or wallet token; the discriminator is the credential type, not the number form.",
+          "examples": ["4242424242424242"]
         },
         "expiry_month": {
           "type": "integer",
-          "description": "The month of the card's expiration date (1-12)."
+          "description": "Card expiration month (1-12)."
         },
         "expiry_year": {
           "type": "integer",
-          "description": "The year of the card's expiration date."
+          "description": "Card expiration year."
         },
         "name": {
           "type": "string",
           "description": "Cardholder name.",
-          "examples": [
-            "Jane Doe"
-          ]
+          "examples": ["Jane Doe"]
         },
         "cvc": {
           "type": "string",
           "maxLength": 4,
-          "description": "Card CVC number.",
-          "examples": [
-            "223"
-          ]
-        },
-        "cryptogram": {
-          "type": "string",
-          "description": "Cryptogram provided with network tokens.",
-          "examples": [
-            "gXc5UCLnM6ckD7pjM1TdPA=="
-          ]
-        },
-        "eci_value": {
-          "type": "string",
-          "description": "Electronic Commerce Indicator / Security Level Indicator provided with network tokens.",
-          "examples": [
-            "07"
-          ]
+          "description": "Card verification code. Optional at the protocol level; merchants can require it via `required_fields` on the funding-source constraint.",
+          "examples": ["223"]
         }
       }
     }
-  ]
+  ],
+  "$defs": {
+    "constraint": {
+      "title": "Card Credential Constraint",
+      "description": "Constraint shape for the `card` credential type.",
+      "allOf": [
+        { "$ref": "constraint.json" },
+        {
+          "type": "object",
+          "properties": {
+            "required_fields": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["number", "expiry_month", "expiry_year", "name", "cvc"]
+              },
+              "uniqueItems": true
+            }
+          }
+        }
+      ]
+    }
+  }
 }

source/schemas/shopping/types/card_payment_instrument.json

@@ -6,36 +6,61 @@
   "$defs": {
     "available_card_payment_instrument": {
       "title": "Available Card Payment Instrument",
-      "description": "Declares card instrument availability with card-specific constraints.",
+      "description": "Declares card instrument availability with constraints. The `constraints` object follows the universal constraint shape (`constraint.json`): a `required_fields` list naming top-level instrument properties that MUST be present (e.g., `billing_address`), plus card-specific custom keys (`brands`, `billing_address`, `credentials`, `funding_sources`). The credentials and funding-source axes share `credential_constraint.json` as their item primitive; funding-source entries MUST name credential types whose schema inherits from `payment_funding_source.json`.",
       "allOf": [
         { "$ref": "available_payment_instrument.json" },
         {
           "type": "object",
           "properties": {
-            "type": {
-              "const": "card"
-            },
+            "type": { "const": "card" },
             "constraints": {
-              "type": "object",
-              "properties": {
-                "brands": {
-                  "type": "array",
-                  "items": { "type": "string" },
-                  "minItems": 1,
-                  "uniqueItems": true,
-                  "description": "Limit to specific card brands (e.g., ['visa', 'mastercard', 'amex'])."
+              "allOf": [
+                { "$ref": "constraint.json" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "required_fields": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": ["billing_address", "credential"]
+                      },
+                      "uniqueItems": true
+                    },
+                    "brands": {
+                      "type": "array",
+                      "items": { "type": "string" },
+                      "minItems": 1,
+                      "uniqueItems": true,
+                      "description": "Accepted card brands (e.g., ['visa', 'mastercard']). Card brand is a property of the underlying card surfaced via `display.brand`, not a credential field, so it sits at the instrument-constraint level."
+                    },
+                    "billing_address": {
+                      "$ref": "address_constraint.json",
+                      "description": "Constraint on the instrument's `billing_address` field. The address itself is required only when `billing_address` appears in this object's `required_fields`."
+                    },
+                    "credentials": {
+                      "type": "array",
+                      "items": { "$ref": "credential_constraint.json" },
+                      "minItems": 1,
+                      "description": "Credential wire shapes the handler accepts. Constraints here describe the wire credential as transmitted."
+                    },
+                    "funding_sources": {
+                      "type": "array",
+                      "items": { "$ref": "credential_constraint.json" },
+                      "minItems": 1,
+                      "description": "Underlying funding sources the handler accepts. Entries MUST reference credential types inheriting from `payment_funding_source.json`. Constraints here describe the underlying instrument regardless of which wire credential conveys it; they are NOT duplicated under `credentials`."
+                    }
+                  }
                 }
-              }
+              ]
             }
           }
         }
       ]
     }
   },
   "allOf": [
-    {
-      "$ref": "payment_instrument.json"
-    },
+    { "$ref": "payment_instrument.json" },
     {
       "type": "object",
       "required": ["type"],
@@ -49,31 +74,12 @@
           "type": "object",
           "description": "Display information for this card payment instrument.",
           "properties": {
-            "brand": {
-              "type": "string",
-              "description": "The card brand/network (e.g., visa, mastercard, amex)."
-            },
-            "last_digits": {
-              "type": "string",
-              "description": "Last 4 digits of the card number."
-            },
-            "expiry_month": {
-              "type": "integer",
-              "description": "The month of the card's expiration date (1-12)."
-            },
-            "expiry_year": {
-              "type": "integer",
-              "description": "The year of the card's expiration date."
-            },
-            "description": {
-              "type": "string",
-              "description": "An optional rich text description of the card to display to the user (e.g., 'Visa ending in 1234, expires 12/2025')."
-            },
-            "card_art": {
-              "type": "string",
-              "format": "uri",
-              "description": "An optional URI to a rich image representing the card (e.g., card art provided by the issuer)."
-            }
+            "brand": { "type": "string", "description": "The card brand/network (e.g., visa, mastercard, amex)." },
+            "last_digits": { "type": "string", "description": "Last 4 digits of the card number." },
+            "expiry_month": { "type": "integer", "description": "The month of the card's expiration date (1-12)." },
+            "expiry_year": { "type": "integer", "description": "The year of the card's expiration date." },
+            "description": { "type": "string", "description": "An optional rich text description of the card to display to the user." },
+            "card_art": { "type": "string", "format": "uri", "description": "An optional URI to a rich image representing the card." }
           }
         }
       }

source/schemas/shopping/types/constraint.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/types/constraint.json",
+  "title": "Constraint",
+  "description": "The universal shape of a constraint object in UCP. Any constraint, on any field, on any object, is structured this way: a `required_fields` list naming properties of the constrained object that MUST be present, plus optional domain-specific custom constraint keys. Concrete constraint schemas (e.g., `address_constraint.json`, `credential_constraint.json`) extend this base and scope `required_fields` to the property names of the object they constrain.",
+  "type": "object",
+  "properties": {
+    "required_fields": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Names of properties on the constrained object that MUST be present. Concrete constraints should contain the actual property names of the constrained schema."
+    }
+  },
+  "additionalProperties": true
+}

source/schemas/shopping/types/credential_constraint.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/types/credential_constraint.json",
+  "title": "Credential Constraint",
+  "description": "An entry in an instrument's `credentials` or `funding_sources` list. Identifies a credential `type` and carries a `constraints` object specific to that credential schema. The same primitive is used on both axes; merchants put each constraint on the semantically correct axis (wire shape vs. underlying funding source) and do not repeat. Entries in `funding_sources` MUST reference credential types whose schema inherits from `payment_funding_source.json`.",
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The credential type discriminator (matches `payment_credential.json#/properties/type` on a concrete credential schema). Examples: `card`, `network_token`, `token`."
+    },
+    "constraints": {
+      "$ref": "constraint.json",
+      "description": "Constraint object scoped to the named credential type. Concrete credential schemas define their own constraint `$def` narrowing `required_fields` to that schema's properties."
+    }
+  },
+  "examples": [
+    { "type": "card",           "constraints": { "required_fields": ["cvc"] } },
+    { "type": "network_token",  "constraints": {} },
+    { "type": "token",          "constraints": { "token_provider": ["dev.shopify.spt"] } }
+  ]
+}

source/schemas/shopping/types/fulfillment_available_method.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/fulfillment_available_method.json",
   "title": "Fulfillment Available Method",
-  "description": "Inventory availability hint for a fulfillment method type.",
+  "description": "Inventory availability hint for a fulfillment method type, with optional constraints describing what the handler needs to quote or fulfill.",
   "type": "object",
   "ucp_shared_request": true,
   "required": ["type", "line_item_ids"],
@@ -29,6 +29,30 @@
       "type": "string",
       "description": "Human-readable availability info (e.g., 'Available for pickup at Downtown Store today').",
       "ucp_request": "omit"
+    },
+    "constraints": {
+      "allOf": [
+        { "$ref": "constraint.json" },
+        {
+          "type": "object",
+          "properties": {
+            "required_fields": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["destination"]
+              },
+              "uniqueItems": true,
+              "description": "Top-level fulfillment-method properties that MUST be present (e.g., `destination` to require an address before this method can be quoted)."
+            },
+            "destination": {
+              "$ref": "address_constraint.json",
+              "description": "For `shipping`: constraint on the destination postal address — what fields must be populated before the handler can return a meaningful quote (e.g., postal-code-only for fast quoting vs. full address for compliance/routing). Reuses the same `address_constraint` primitive as `card_payment_instrument` billing addresses."
+            }
+          }
+        }
+      ],
+      "description": "Constraints the handler places on this fulfillment method. Follows the universal constraint shape (`constraint.json`)."
     }
   }
 }