{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://shopify.dev/ucp/schemas/2026-08-25/shopify_shopping_declared_fields.json",
  "name": "dev.shopify.shopping.declared_fields",
  "version": "2026-08-25",
  "title": "Shopify Declared Fields Extension",
  "description": "Extends Cart and Checkout with business-declared data collection fields and Order with read-only captured field definitions and values. Fields declare a purpose and a JSON Schema describing their value. Cart and Checkout fields may also provide optional presentation hints.",
  "requires": {
    "protocol": {
      "min": "2026-08-25"
    }
  },
  "$defs": {
    "declared_field_value_schema": {
      "title": "Declared Field Value Schema",
      "type": "object",
      "description": "JSON Schema Draft 2020-12 object describing the non-null value carried by a declared field. A $ref MUST be a local fragment resolving to a value schema in this document's $defs.",
      "additionalProperties": true,
      "properties": {
        "$ref": {
          "type": "string",
          "pattern": "^#/\\$defs/[A-Za-z0-9._-]+$",
          "description": "Local reference to a reusable value schema defined by this extension."
        }
      }
    },
    "json_value": {
      "title": "JSON Value",
      "description": "Any JSON value. Within declared fields, null means no value has been submitted or the value has been cleared."
    },
    "presentation": {
      "title": "Presentation Hints",
      "type": "object",
      "description": "Optional non-normative rendering hints. Properties MUST NOT affect whether a submitted value is valid. Platforms MUST tolerate unknown properties and values.",
      "additionalProperties": true,
      "properties": {
        "preferred_control": {
          "type": "string",
          "description": "Preferred input control hint. Well-known values are text, textarea, date_picker, checkbox, select, and radio. Platforms MAY ignore this hint and use a control appropriate for value_schema.",
          "examples": [
            "text",
            "textarea",
            "date_picker",
            "checkbox",
            "select",
            "radio"
          ]
        }
      }
    },
    "base_declared_field": {
      "title": "Base Declared Field",
      "type": "object",
      "description": "Shared definition and current value for a business-defined Cart, Checkout, or Order field.",
      "additionalProperties": true,
      "ucp_request": {
        "complete": "omit"
      },
      "required": [
        "key",
        "purpose",
        "value_schema",
        "value"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "Unique identifier for the field. Must be unique within the declared_fields array.",
          "ucp_request": {
            "create": "required",
            "update": "required"
          }
        },
        "purpose": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json",
          "description": "Governed reverse-domain identifier defining why this data is collected and how it may affect the commerce outcome. Well-known purposes convey exact portable field semantics independently of the field key. Unknown purposes remain opaque and do not relax field safety restrictions.",
          "examples": [
            "dev.shopify.shopping.declared_fields.generic"
          ],
          "ucp_request": "omit"
        },
        "title": {
          "type": "string",
          "description": "Human-readable display name for the field.",
          "ucp_request": "omit"
        },
        "title_content_type": {
          "type": "string",
          "default": "plain",
          "description": "Format for the title. Well-known values are plain and markdown. Defaults to plain.",
          "ucp_request": "omit"
        },
        "description": {
          "type": "string",
          "description": "Help text or instructions for the field.",
          "ucp_request": "omit"
        },
        "value_schema": {
          "$ref": "#/$defs/declared_field_value_schema",
          "description": "JSON Schema Draft 2020-12 object describing the non-null value accepted for this field.",
          "ucp_request": "omit"
        },
        "value": {
          "$ref": "#/$defs/json_value",
          "description": "Current value for the field. A non-null value MUST match value_schema. Null means no value has been submitted or the value has been cleared.",
          "ucp_request": {
            "create": "required",
            "update": "required"
          }
        }
      }
    },
    "cart_declared_field": {
      "title": "Cart Declared Field",
      "description": "Definition and current value for a business-defined cart field. Cart fields do not express checkout requiredness.",
      "allOf": [
        {
          "$ref": "#/$defs/base_declared_field"
        },
        {
          "type": "object",
          "properties": {
            "presentation": {
              "$ref": "#/$defs/presentation",
              "description": "Optional non-normative hints for rendering the field.",
              "ucp_request": "omit"
            }
          }
        }
      ]
    },
    "checkout_declared_field": {
      "title": "Checkout Declared Field",
      "description": "Definition and current value for a business-defined checkout field.",
      "allOf": [
        {
          "$ref": "#/$defs/base_declared_field"
        },
        {
          "type": "object",
          "required": [
            "required"
          ],
          "properties": {
            "required": {
              "type": "boolean",
              "description": "Whether the field must be filled before checkout can complete.",
              "ucp_request": "omit"
            },
            "presentation": {
              "$ref": "#/$defs/presentation",
              "description": "Optional non-normative hints for rendering the field.",
              "ucp_request": "omit"
            }
          }
        }
      ]
    },
    "cart_declared_fields": {
      "title": "Cart Declared Fields",
      "type": "array",
      "description": "Business-declared cart fields with current values. A request with entries replaces the submitted value set: configured fields that the request omits have no submitted value. Omit the array, or send it empty, to keep the current values. A null value clears the field.",
      "items": {
        "$ref": "#/$defs/cart_declared_field"
      }
    },
    "checkout_declared_fields": {
      "title": "Checkout Declared Fields",
      "type": "array",
      "description": "Business-declared checkout fields with current values and checkout completion requiredness. A request with entries replaces the submitted value set: configured fields that the request omits have no submitted value. Omit the array, or send it empty, to keep the current values. A null value clears the field.",
      "items": {
        "$ref": "#/$defs/checkout_declared_field"
      }
    },
    "order_declared_field": {
      "title": "Order Declared Field",
      "description": "Read-only declared field definition and value captured for an order.",
      "allOf": [
        {
          "$ref": "#/$defs/base_declared_field"
        }
      ]
    },
    "order_declared_fields": {
      "title": "Order Declared Fields",
      "type": "array",
      "description": "Read-only declared field definitions and values captured by checkout completion, including values carried forward from cart.",
      "items": {
        "$ref": "#/$defs/order_declared_field"
      }
    },
    "dev.ucp.shopping.cart": {
      "title": "Cart with Declared Fields",
      "description": "Cart extended with business-defined declared fields.",
      "allOf": [
        {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
        },
        {
          "type": "object",
          "properties": {
            "declared_fields": {
              "$ref": "#/$defs/cart_declared_fields",
              "ucp_request": {
                "create": "optional",
                "update": "optional"
              }
            }
          }
        }
      ]
    },
    "dev.ucp.shopping.checkout": {
      "title": "Checkout with Declared Fields",
      "description": "Checkout extended with business-defined declared fields.",
      "allOf": [
        {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
        },
        {
          "type": "object",
          "properties": {
            "declared_fields": {
              "$ref": "#/$defs/checkout_declared_fields",
              "ucp_request": {
                "create": "optional",
                "update": "optional",
                "complete": "omit"
              }
            }
          }
        }
      ]
    },
    "dev.ucp.shopping.order": {
      "title": "Order with Declared Fields",
      "description": "Order extended with read-only declared field values captured by checkout completion, including values carried forward from cart.",
      "allOf": [
        {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/order.json"
        },
        {
          "type": "object",
          "properties": {
            "declared_fields": {
              "$ref": "#/$defs/order_declared_fields",
              "ucp_request": "omit"
            }
          }
        }
      ]
    },
    "dev.shopify.shopping.declared_fields": {
      "platform_schema": {
        "title": "Declared Fields Capability (Platform)",
        "description": "Platform-level declared fields capability declaration.",
        "allOf": [
          {
            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/platform_schema"
          }
        ]
      },
      "business_schema": {
        "title": "Declared Fields Capability (Business)",
        "description": "Business-level declared fields capability declaration.",
        "allOf": [
          {
            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/business_schema"
          }
        ]
      }
    }
  }
}