{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json",
  "name": "dev.ucp.shopping.catalog.lookup",
  "title": "Catalog Lookup",
  "description": "Product/variant lookup by identifier. Supports batch retrieval (lookup_catalog) and single-product detail (get_product).",
  "type": "object",
  "$defs": {
    "lookup_variant": {
      "description": "Variant with required correlation metadata for lookup responses.",
      "allOf": [
        {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/variant.json"
        },
        {
          "required": [
            "inputs"
          ],
          "properties": {
            "inputs": {
              "type": "array",
              "items": {
                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/input_correlation.json"
              },
              "minItems": 1,
              "description": "Which request identifiers resolved to this variant, and how. Each entry maps a request ID to its match type."
            }
          }
        }
      ]
    },
    "lookup_request": {
      "type": "object",
      "description": "Request body for catalog lookup.",
      "required": [
        "ids"
      ],
      "properties": {
        "ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "description": "Identifiers to lookup. Implementations MUST support product ID and variant ID; MAY support secondary identifiers (SKU, handle, etc.)."
        },
        "filters": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/search_filters.json",
          "description": "Filter criteria to narrow returned products and variants. All specified filters combine with AND logic."
        },
        "context": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/context.json"
        },
        "signals": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/signals.json"
        },
        "attribution": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/attribution.json"
        }
      }
    },
    "lookup_response": {
      "type": "object",
      "required": [
        "ucp",
        "products"
      ],
      "properties": {
        "ucp": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/response_catalog_schema"
        },
        "products": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/product.json"
              },
              {
                "properties": {
                  "variants": {
                    "items": {
                      "$ref": "#/$defs/lookup_variant"
                    }
                  }
                }
              }
            ]
          },
          "description": "Products matching the requested identifiers. May contain fewer items if some identifiers not found, or more if identifiers match multiple products."
        },
        "actions": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/actions.json",
          "description": "Outstanding extension-defined Actions for this catalog lookup response.",
          "ucp_request": "omit"
        },
        "messages": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/message.json"
          },
          "description": "Errors, warnings, or informational messages about the requested items."
        },
        "policies": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/policy.json"
          },
          "description": "Policies (e.g., return/refund terms) that apply to the products in this response. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`."
        }
      }
    },
    "get_product_request": {
      "type": "object",
      "description": "Request body for single-product retrieval. Supports interactive variant narrowing via selected and preferences.",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Product or variant identifier. Implementations MUST support product ID and variant ID."
        },
        "selected": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/selected_option.json"
          },
          "description": "Partial or full option selections for interactive variant narrowing. When provided, response option values include availability signals (available, exists) relative to these selections."
        },
        "preferences": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Option names in relaxation priority order. When no exact variant matches all selections, the server drops options from the end of this list first. E.g., ['Color', 'Size'] keeps Color and relaxes Size."
        },
        "filters": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/search_filters.json",
          "description": "Filter criteria to narrow returned variants. All specified filters combine with AND logic."
        },
        "context": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/context.json"
        },
        "signals": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/signals.json"
        },
        "attribution": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/attribution.json"
        }
      }
    },
    "detail_product": {
      "description": "A product in a get_product response, extended with effective selections and availability signals on option values.",
      "type": "object",
      "allOf": [
        {
          "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/product.json"
        }
      ],
      "properties": {
        "selected": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/selected_option.json"
          },
          "description": "Effective option selections that anchor the featured variant and availability signals. Required when the product has configurable options; may be empty or omitted for products with no option axes."
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "values"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "values": {
                "type": "array",
                "items": {
                  "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/detail_option_value.json"
                },
                "minItems": 1
              }
            }
          },
          "description": "Product options with availability signals relative to the effective selections."
        }
      }
    },
    "get_product_response": {
      "type": "object",
      "required": [
        "ucp",
        "product"
      ],
      "properties": {
        "ucp": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/response_catalog_schema"
        },
        "product": {
          "$ref": "#/$defs/detail_product",
          "description": "The requested product with full detail. Singular — this is a single-resource operation."
        },
        "actions": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/actions.json",
          "description": "Outstanding extension-defined Actions for this product response.",
          "ucp_request": "omit"
        },
        "messages": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/message.json"
          },
          "description": "Warnings or informational messages about the product (e.g., price recently changed, limited availability)."
        },
        "policies": {
          "type": "array",
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/policy.json"
          },
          "description": "Policies (e.g., return/refund terms) that apply to this product. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`."
        }
      }
    }
  },
  "version": "2026-08-25"
}