{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/2026-08-25/schemas/ucp.json",
  "title": "UCP Metadata",
  "description": "Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.",
  "$defs": {
    "version": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Version identifier in YYYY-MM-DD format."
    },
    "version_constraint": {
      "type": "object",
      "description": "Version range requirement with minimum and optional maximum.",
      "properties": {
        "min": {
          "$ref": "#/$defs/version",
          "description": "Minimum required version (inclusive)."
        },
        "max": {
          "$ref": "#/$defs/version",
          "description": "Maximum compatible version (inclusive). When absent, no upper bound."
        }
      },
      "required": [
        "min"
      ],
      "additionalProperties": true
    },
    "requires": {
      "type": "object",
      "description": "Version requirements for extension schemas. Declares minimum (and optionally maximum) protocol and capability versions needed for correct operation.",
      "properties": {
        "protocol": {
          "$ref": "#/$defs/version_constraint",
          "description": "Required range for the selected `ucp.version`."
        },
        "capabilities": {
          "type": "object",
          "description": "Required capability versions, keyed by capability name. Keys must be a subset of the extension's $defs keys.",
          "propertyNames": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
          },
          "additionalProperties": {
            "$ref": "#/$defs/version_constraint"
          }
        }
      },
      "additionalProperties": true
    },
    "map_order": {
      "type": "object",
      "description": "Preferred key order for map-valued fields in the scope annotated by the containing `ucp` member. Each property names a target map, and its array lists target keys in preferred order. Lists may be partial and are not allowlists.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "members": {
      "type": "object",
      "description": "Members defined inside the reserved `ucp` protocol object. The object is open for forward compatibility: consumers MUST ignore unrecognized members. Only UCP core defines members, and every defined member MUST be safe to ignore.",
      "properties": {
        "map_order": {
          "$ref": "#/$defs/map_order",
          "ucp_request": "omit"
        },
        "request_constraints": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/request_constraints.json",
          "ucp_request": "omit"
        }
      },
      "additionalProperties": true
    },
    "entity": {
      "type": "object",
      "description": "Shared foundation for all UCP entities.",
      "required": [
        "version"
      ],
      "properties": {
        "version": {
          "$ref": "#/$defs/version",
          "description": "Entity version in YYYY-MM-DD format."
        },
        "spec": {
          "type": "string",
          "format": "uri",
          "description": "URL to human-readable specification document."
        },
        "schema": {
          "type": "string",
          "format": "uri",
          "description": "URL to JSON Schema defining this entity's structure and payloads."
        },
        "id": {
          "type": "string",
          "description": "Unique identifier for this entity instance. Used to disambiguate when multiple instances exist."
        },
        "config": {
          "type": "object",
          "description": "Entity-specific configuration. Structure defined by each entity's schema.",
          "additionalProperties": true
        }
      }
    },
    "base": {
      "description": "Base UCP metadata with shared properties for all schema types.",
      "type": "object",
      "required": [
        "version"
      ],
      "properties": {
        "version": {
          "$ref": "#/$defs/version"
        },
        "map_order": {
          "$ref": "#/$defs/map_order",
          "description": "Preferred key-traversal order for sibling registry fields inside the root `ucp` envelope (`services`, `capabilities`, and `payment_handlers`).",
          "ucp_request": "omit"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "error"
          ],
          "default": "success",
          "description": "Application-level status of the UCP operation."
        },
        "services": {
          "type": "object",
          "description": "Service registry keyed by reverse-domain name.",
          "propertyNames": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "https://ucp.dev/2026-08-25/schemas/service.json#/$defs/base"
            }
          }
        },
        "capabilities": {
          "type": "object",
          "description": "Capability registry keyed by reverse-domain name.",
          "propertyNames": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/base"
            }
          }
        },
        "payment_handlers": {
          "type": "object",
          "description": "Payment handler registry keyed by reverse-domain name.",
          "propertyNames": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "https://ucp.dev/2026-08-25/schemas/payment_handler.json#/$defs/base"
            }
          }
        }
      }
    },
    "success": {
      "description": "UCP metadata with status 'success'. Use for response branches that carry the expected payload.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "status": {
              "const": "success"
            }
          },
          "required": [
            "status"
          ]
        }
      ]
    },
    "error": {
      "description": "UCP metadata with status 'error'. Use for response branches that carry error information.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "status": {
              "const": "error"
            }
          },
          "required": [
            "status"
          ]
        }
      ]
    },
    "platform_schema": {
      "title": "UCP Platform Schema",
      "description": "Full UCP metadata for platform-level configuration. Hosted at a URI advertised by the platform in request headers.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "required": [
            "services",
            "payment_handlers"
          ],
          "properties": {
            "services": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/service.json#/$defs/platform_schema"
                }
              }
            },
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/platform_schema"
                }
              }
            },
            "payment_handlers": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/payment_handler.json#/$defs/platform_schema"
                }
              }
            }
          }
        }
      ]
    },
    "business_schema": {
      "title": "UCP Business Schema",
      "description": "UCP metadata for business/merchant-level configuration. Subset of platform schema with business-specific settings.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "required": [
            "services",
            "payment_handlers"
          ],
          "properties": {
            "supported_versions": {
              "type": "object",
              "description": "Previous protocol versions this business supports, mapped to profile URIs. Businesses that support older protocol versions SHOULD advertise each version and link to its profile. Each URI points to a complete, self-contained profile for that version. When omitted, only `version` is supported.",
              "propertyNames": {
                "$ref": "#/$defs/version"
              },
              "additionalProperties": {
                "type": "string",
                "format": "uri"
              }
            },
            "services": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/service.json#/$defs/business_schema"
                }
              }
            },
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/business_schema"
                }
              }
            },
            "payment_handlers": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/payment_handler.json#/$defs/business_schema"
                }
              }
            }
          }
        }
      ]
    },
    "response_checkout_schema": {
      "title": "UCP Checkout Response Schema",
      "description": "UCP metadata for checkout responses.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "required": [
            "payment_handlers"
          ],
          "properties": {
            "services": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/service.json#/$defs/response_schema"
                }
              }
            },
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/response_schema"
                }
              }
            },
            "payment_handlers": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/payment_handler.json#/$defs/response_schema"
                }
              }
            }
          }
        }
      ]
    },
    "response_order_schema": {
      "title": "UCP Order Response Schema",
      "description": "UCP metadata for order responses. No payment handlers needed post-purchase.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/response_schema"
                }
              }
            }
          }
        }
      ]
    },
    "response_cart_schema": {
      "title": "UCP Cart Response Schema",
      "description": "UCP metadata for cart responses. No payment handlers needed pre-checkout.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/response_schema"
                }
              }
            }
          }
        }
      ]
    },
    "response_catalog_schema": {
      "title": "UCP Catalog Response Schema",
      "description": "UCP metadata for catalog responses.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/response_schema"
                }
              }
            }
          }
        }
      ]
    },
    "response_location_schema": {
      "title": "UCP Location Response Schema",
      "description": "UCP metadata for location responses.",
      "allOf": [
        {
          "$ref": "#/$defs/base"
        },
        {
          "properties": {
            "capabilities": {
              "additionalProperties": {
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/response_schema"
                }
              }
            }
          }
        }
      ]
    }
  }
}