{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://shopify.dev/ucp/schemas/2026-08-25/shopify_catalog_global.json",
  "name": "dev.shopify.catalog.global",
  "version": "2026-08-25",
  "title": "Shopify Global Catalog Extension",
  "description": "Extends UCP Catalog with Shopify Global Catalog capabilities: cross-merchant search and discovery, seller identity, ML-inferred metadata, and similarity-based search.",

  "$defs": {

    "view": {
      "type": "string",
      "description": "Predefined output shape. When absent, returns the operation's default representation. Well-known values are operation-specific."
    },

    "attribute": {
      "type": "object",
      "description": "ML-inferred product attribute (e.g., material, style).",
      "required": ["name", "value"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Attribute name (e.g., 'Material', 'Style')."
        },
        "value": {
          "type": "string",
          "description": "Attribute value (e.g., 'Cotton', 'Casual')."
        }
      }
    },

    "shopify_variant": {
      "title": "Shopify Variant",
      "description": "UCP Variant with shared Shopify enrichments: checkout URL, checkout prerequisites, and selling plans.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/variant.json" },
        {
          "type": "object",
          "properties": {
            "checkout_url": {
              "type": "string",
              "format": "uri",
              "description": "Direct checkout URL for this variant."
            },
            "requires": {
              "type": "object",
              "description": "Checkout prerequisites for this variant.",
              "properties": {
                "shipping": {
                  "type": "boolean",
                  "description": "Whether a shipping address is needed to purchase this variant."
                },
                "selling_plan": {
                  "type": "boolean",
                  "description": "Whether a selling plan must be selected to purchase this variant."
                },
                "components": {
                  "type": "boolean",
                  "description": "Whether the variant requires components. If true, the variant can only be purchased as a parent bundle with components."
                }
              }
            },
            "selling_plans": {
              "type": "array",
              "items": { "$ref": "#/$defs/selling_plan" },
              "description": "Available purchase options with pricing.",
              "ucp_response": {
                "transition": {
                  "from": "omit",
                  "to": "optional",
                  "description": "Planned: subscription and recurring purchase options per variant."
                }
              }
            },
            "components": {
              "type": "array",
              "description": "Bundle components included in the variant, considering only fixed bundles.",
              "ucp_response": {
                "transition": {
                  "from": "omit",
                  "to": "optional",
                  "description": "Planned: fixed bundle component references per variant."
                }
              },
              "items": {
                "type": "object",
                "required": ["id", "quantity"],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The product variant identifier of the component."
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "The quantity of the component present in the bundle."
                  }
                }
              }
            }
          }
        }
      ]
    },

    "shopify_product": {
      "title": "Shopify Product",
      "description": "UCP Product with shared Shopify enrichments.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/product.json" },
        {
          "type": "object",
          "properties": {
            "variants": {
              "type": "array",
              "items": { "$ref": "#/$defs/shopify_variant" },
              "minItems": 1,
              "description": "Shopify-enriched variants."
            }
          }
        }
      ]
    },

    "global_eligible": {
      "type": "object",
      "description": "Checkout and fulfillment eligibility signals.",
      "properties": {
        "native_checkout": {
          "type": "boolean",
          "default": true,
          "description": "Whether this product/variant supports native (non-redirect) checkout."
        }
      }
    },

    "global_availability": {
      "description": "Extends UCP availability with inventory urgency signal.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/variant.json#/properties/availability" },
        {
          "type": "object",
          "properties": {
            "running_low": {
              "type": "boolean",
              "description": "True when inventory is limited. Only meaningful when available is true."
            }
          }
        }
      ]
    },

    "global_variant": {
      "title": "Global Variant",
      "description": "Shopify Variant extended with cross-shop discovery fields: seller identity, eligibility, and inventory signals.",
      "allOf": [
        { "$ref": "#/$defs/shopify_variant" },
        {
          "type": "object",
          "properties": {
            "condition": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Product condition labels. Known values: 'new', 'secondhand'. Values are not mutually exclusive."
            },
            "eligible": {
              "$ref": "#/$defs/global_eligible",
              "description": "Checkout and fulfillment eligibility signals."
            },
            "availability": {
              "$ref": "#/$defs/global_availability",
              "description": "Extended availability with running_low signal."
            },
            "seller": {
              "description": "Extends base UCP seller with Shopify shop identifiers.",
              "allOf": [
                { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/variant.json#/properties/seller" },
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Shop GID."
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Storefront URL."
                    },
                    "domain": {
                      "type": "string",
                      "description": "Shop primary domain."
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    },

    "global_product": {
      "title": "Global Product",
      "description": "Shopify Product extended with ML-inferred metadata, platform classification signals, and Global-enriched variants.",
      "allOf": [
        { "$ref": "#/$defs/shopify_product" },
        {
          "type": "object",
          "properties": {
            "metadata": {
              "type": "object",
              "description": "Shopify-specific product metadata. ML-inferred fields are typed here; base UCP agents see this as opaque business data.",
              "properties": {
                "attributes": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/attribute" },
                  "description": "ML-inferred product attributes (material, style, occasion, etc.)."
                },
                "tech_specs": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "ML-inferred technical specifications."
                },
                "top_features": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "ML-inferred top product features."
                },
                "unique_selling_points": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "ML-inferred unique selling propositions."
                }
              }
            },
            "variants": {
              "type": "array",
              "items": { "$ref": "#/$defs/global_variant" },
              "minItems": 1,
              "description": "Global-enriched variants with checkout URLs, shop context, and extended availability."
            }
          }
        }
      ]
    },

    "shopify_filters": {
      "type": "object",
      "title": "Shopify Filters",
      "description": "Common Shopify filter criteria. All filters combine with AND logic.",
      "properties": {
        "available": {
          "type": "boolean",
          "default": true,
          "description": "Filter by availability. Default true (only sale-ready items)."
        }
      }
    },

    "global_filters": {
      "title": "Global Filters",
      "description": "Global catalog filter criteria. Superset of shared Shopify filters with cross-shop discovery fields. All filters combine with AND logic.",
      "allOf": [
        { "$ref": "#/$defs/shopify_filters" },
        {
          "type": "object",
          "properties": {
            "shops": {
              "type": "array",
              "items": { "type": "string" },
              "maxItems": 1000,
              "description": "Restrict results to specific shops by GID. Maximum 1000 entries per request."
            },
            "condition": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Filter by product condition. Known values: 'new', 'secondhand'. Absent means no condition filter (all conditions returned). Multiple values use OR logic."
            },
            "ships_to": {
              "type": "object",
              "description": "Shipping destination filter. When absent, implementation falls back to context address fields. When country matches context, implementation MAY enrich with context region/postal_code for delivery estimates.",
              "required": ["country"],
              "properties": {
                "country": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$",
                  "description": "ISO 3166-1 alpha-2 country code."
                },
                "region": {
                  "type": "string",
                  "description": "State, province, or region. Improves delivery estimate fidelity."
                },
                "postal_code": {
                  "type": "string",
                  "description": "Postal or ZIP code. Improves delivery estimate fidelity."
                }
              }
            },
            "ships_from": {
              "type": "array",
              "description": "Shipping origin filter. Matches variants offered from any listed origin. Absent means no origin filter. Multiple entries use OR logic.",
              "items": {
                "type": "object",
                "required": ["country"],
                "properties": {
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "ISO 3166-1 alpha-2 country code."
                  }
                }
              }
            }
          }
        }
      ]
    },

    "global_search_filters": {
      "title": "Global Search Filters",
      "description": "UCP search filters extended with Shopify availability and Global catalog criteria. All filters combine with AND logic.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/types/search_filters.json" },
        { "$ref": "#/$defs/global_filters" },
        {
          "type": "object",
          "properties": {
            "categories": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Filter by product category. Each item is a taxonomy category GID. Multiple values use OR logic."
            },
            "attributes": {
              "type": "array",
              "maxItems": 25,
              "description": "Filter by Shopify taxonomy attributes on products and variants. Entries combine with AND; values within an entry combine with OR. Unrecognized attribute names are ignored and surfaced via result.messages[]. Maximum 25 entries per request.",
              "items": {
                "type": "object",
                "required": ["name", "values"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Taxonomy attribute. Currently supported attributes are 'Color', 'Size', 'Target gender'."
                  },
                  "values": {
                    "type": "array",
                    "items": { "type": "string" },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Taxonomy values (e.g. 'Red'). Values within an entry combine with OR. Maximum 50 values per attribute."
                  }
                }
              }
            },
            "rating": {
              "type": "object",
              "description": "Filter by variant rating.",
              "properties": {
                "variant": {
                  "type": "object",
                  "description": "Matches products with at least one variant whose rating field meets these thresholds.",
                  "properties": {
                    "min": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 5,
                      "description": "Minimum rating value. Ratings are on a 0–5 scale."
                    },
                    "min_count": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 2147483647,
                      "description": "Minimum number of reviews."
                    }
                  }
                }
              }
            },
            "price_tier": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Filter by relative price tier within each product's category. Multiple values use OR logic. Well-known values: `low`, `medium`, `high`. Unrecognized values are ignored and surfaced via result.messages[]."
            },
            "media": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Media type to require. Well-known values: `image`, `video`, `external_video`, `model_3d`."
                  }
                }
              },
              "description": "Filter by product media. Each entry asserts the product has at least one media item of the given type. Entries combine with AND. Entries with an unrecognized type are ignored and surfaced via result.messages[]."
            }
          }
        }
      ]
    },

    "like_item": {
      "title": "Like Item",
      "description": "An item specified by product ID or by inline image data.",
      "type": "object",
      "oneOf": [
        {
          "title": "Item Reference",
          "description": "Reference to a catalog item by GID.",
          "required": ["id"],
          "properties": {
            "id": {
              "type": "string",
              "description": "Product or variant GID."
            }
          },
          "additionalProperties": false
        },
        {
          "title": "Image Content",
          "description": "Inline image for visual similarity search.",
          "required": ["image"],
          "properties": {
            "image": {
              "type": "object",
              "description": "Base64-encoded image with MIME type.",
              "required": ["content_type", "data"],
              "properties": {
                "content_type": {
                  "type": "string",
                  "description": "MIME type of the encoded image (e.g., image/jpeg, image/webp)."
                },
                "data": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "description": "Base64-encoded image bytes."
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      ]
    },

    "global_search_request": {
      "title": "Global Search Request",
      "description": "UCP search request extended with Global catalog filters and similarity signals. The `like` parameter enables similarity-based search by item reference or image content.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json#/$defs/search_request" },
        {
          "type": "object",
          "anyOf": [
            { "required": ["query"] },
            { "required": ["like"] }
          ],
          "properties": {
            "view": { "$ref": "#/$defs/view" },
            "like": {
              "type": "array",
              "description": "Similar items to search by — results should resemble these inputs.",
              "minItems": 1,
              "maxItems": 1,
              "items": {
                "$ref": "#/$defs/like_item"
              },
              "ucp_request": {
                "search": {
                  "transition": {
                    "from": "omit",
                    "to": "optional",
                    "description": "Planned: similarity-based search via product reference or inline image."
                  }
                }
              }
            },
            "filters": { "$ref": "#/$defs/global_search_filters" }
          }
        }
      ]
    },

    "global_search_response": {
      "title": "Global Search Response",
      "description": "UCP search response with Global-enriched products.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json#/$defs/search_response" },
        {
          "type": "object",
          "properties": {
            "products": {
              "type": "array",
              "items": { "$ref": "#/$defs/global_product" }
            }
          }
        }
      ]
    },

    "global_lookup_request": {
      "title": "Global Lookup Request",
      "description": "UCP lookup request extended with Global catalog filters and expanded identifier support. Accepts GTIN, UPC, and product URL in addition to product/variant IDs.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/lookup_request" },
        {
          "type": "object",
          "properties": {
            "view": { "$ref": "#/$defs/view" },
            "filters": { "$ref": "#/$defs/global_filters" }
          }
        }
      ]
    },

    "global_lookup_response": {
      "title": "Global Lookup Response",
      "description": "UCP lookup response with Global-enriched products.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/lookup_response" },
        {
          "type": "object",
          "properties": {
            "products": {
              "type": "array",
              "items": { "$ref": "#/$defs/global_product" }
            }
          }
        }
      ]
    },

    "global_get_product_request": {
      "title": "Global Get Product Request",
      "description": "UCP get_product request extended with predefined output shapes and offer filters.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/get_product_request" },
        {
          "type": "object",
          "properties": {
            "view": { "$ref": "#/$defs/view" },
            "filters": { "$ref": "#/$defs/global_filters" }
          }
        }
      ]
    },

    "global_get_product_response": {
      "title": "Global Get Product Response",
      "description": "UCP get_product response with Global-enriched product.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/get_product_response" },
        {
          "type": "object",
          "properties": {
            "product": { "$ref": "#/$defs/global_product" }
          }
        }
      ]
    },

    "dev.ucp.shopping.catalog.search": {
      "description": "Global catalog search composition.",
      "$defs": {
        "search_request": { "$ref": "#/$defs/global_search_request" },
        "search_response": { "$ref": "#/$defs/global_search_response" }
      }
    },

    "dev.ucp.shopping.catalog.lookup": {
      "description": "Global catalog lookup composition.",
      "$defs": {
        "lookup_request": { "$ref": "#/$defs/global_lookup_request" },
        "lookup_response": { "$ref": "#/$defs/global_lookup_response" },
        "get_product_request": { "$ref": "#/$defs/global_get_product_request" },
        "get_product_response": { "$ref": "#/$defs/global_get_product_response" }
      }
    },

    "selling_plan_price": {
      "type": "object",
      "description": "Price adjustments for a selling plan allocation.",
      "required": [
        "total"
      ],
      "properties": {
        "total": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The price of the variant when it's purchased with this selling plan."
        },
        "compare_at": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The price of the variant when it's purchased without a selling plan for the same number of deliveries."
        },
        "per_delivery": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The effective price for a single delivery."
        },
        "unit": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The resulting price per unit for the variant associated with this selling plan. Measure and reference inherited from variant.unit_price."
        }
      }
    },

    "selling_plan_charge": {
      "type": "object",
      "description": "Charge amounts due for the purchase.",
      "required": [
        "checkout"
      ],
      "properties": {
        "checkout": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The checkout charge amount due for the purchase."
        },
        "remaining_balance": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/price.json",
          "description": "The remaining balance charge amount due for the purchase."
        }
      }
    },

    "selling_plan": {
      "type": "object",
      "description": "A representation of how products and variants can be sold and purchased.",
      "required": [
        "id",
        "name",
        "price",
        "charge"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "A globally unique identifier for the selling plan."
        },
        "name": {
          "type": "string",
          "description": "The name of the selling plan. For example, '6 weeks of prepaid granola, delivered weekly'."
        },
        "description": {
          "type": "string",
          "description": "The description of the selling plan."
        },
        "group": {
          "type": "string",
          "description": "The name of the selling plan group this plan belongs to (e.g., 'Subscribe & Save')."
        },
        "recurring": {
          "type": "boolean",
          "description": "Whether purchasing this selling plan will result in multiple deliveries."
        },
        "options": {
          "type": "array",
          "description": "The selling plan options available in the drop-down list in the storefront.",
          "items": {
            "type": "object",
            "required": [
              "name",
              "value"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "The name of the option (e.g., 'Delivery every')."
              },
              "value": {
                "type": "string",
                "description": "The value of the option (e.g., 'Month')."
              }
            }
          }
        },
        "price": {
          "$ref": "#/$defs/selling_plan_price",
          "description": "Price adjustments for this selling plan allocation."
        },
        "charge": {
          "$ref": "#/$defs/selling_plan_charge",
          "description": "Charge amounts due for the purchase."
        }
      }
    }
  }
}