{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bolotstudio-com/json-schema/bolotstudio-com-ucpproduct-schema.json",
  "title": "UCPProduct",
  "description": "Product in UCP format",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bolotstudio-com-openapi.json#/components/schemas/UCPProduct",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Shopify product GID"
    },
    "handle": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "price": {
      "oneOf": [
        {
          "$ref": "#/$defs/Money"
        },
        {
          "type": "null"
        }
      ],
      "description": "Lowest market-visible resolver price, or null when no sellable offer is available in the requested market."
    },
    "images": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Image"
      }
    },
    "variants": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UCPVariant"
      }
    },
    "options": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "availability": {
      "type": "string",
      "enum": [
        "in_stock",
        "out_of_stock"
      ]
    },
    "vendor": {
      "type": "string"
    },
    "productType": {
      "type": "string"
    },
    "shipping": {
      "type": "object",
      "properties": {
        "freeAbove": {
          "$ref": "#/$defs/Money"
        },
        "estimatedDays": {
          "type": "object",
          "properties": {
            "min": {
              "type": "integer"
            },
            "max": {
              "type": "integer"
            }
          }
        },
        "zones": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "returns": {
      "type": "object",
      "properties": {
        "days": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Commercial return-window length, or null when no blanket change-of-mind window is offered."
        },
        "type": {
          "type": "string",
          "enum": [
            "statutory_remedies_personalized_goods"
          ]
        },
        "freeReturns": {
          "type": "boolean",
          "const": false,
          "description": "True only for a blanket merchant-paid commercial return policy. Mandatory statutory-remedy costs are described separately."
        },
        "changeOfMindReturns": {
          "type": "string",
          "description": "No blanket voluntary change-of-mind window is promised; mandatory destination-law rights remain.",
          "enum": [
            "not_offered_for_personalized_goods"
          ]
        },
        "qualityIssueReportingTiming": {
          "type": "string",
          "const": "promptly_after_discovery",
          "description": "Contact timing for voluntary Verified quality support. It does not create a separate claim deadline or limit mandatory rights."
        },
        "qualityIssueReportingHasSeparateDeadline": {
          "type": "boolean",
          "const": false,
          "description": "Verified quality support does not impose a separate voluntary claim deadline."
        },
        "merchantPaidVerifiedIssueReturns": {
          "type": "boolean",
          "const": true,
          "description": "If Bolot Studio accepts a physical return for a verified quality issue, Bolot Studio pays that return cost."
        },
        "personalizedGoodsExemption": {
          "type": "boolean",
          "const": true
        },
        "legalBasis": {
          "type": "string"
        },
        "process": {
          "type": "string"
        },
        "eligibleReasons": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "excludedReasons": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "coverage": {
          "type": "string"
        }
      }
    },
    "customization": {
      "type": "object",
      "description": "Customization requirements. IMPORTANT: Most products require a customer-uploaded photo; the Address Sign uses text/template input instead.",
      "properties": {
        "required": {
          "type": "boolean",
          "description": "Whether customization is mandatory to order"
        },
        "type": {
          "type": "string",
          "description": "Type of customization (e.g., photo_upload)"
        },
        "description": {
          "type": "string"
        },
        "image_upload": {
          "type": "object",
          "properties": {
            "required": {
              "type": "boolean"
            },
            "formats": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "max_file_size": {
              "type": "string"
            },
            "min_resolution": {
              "type": "object",
              "properties": {
                "width": {
                  "type": "integer"
                },
                "height": {
                  "type": "integer"
                }
              }
            },
            "recommended_resolution": {
              "type": "object",
              "properties": {
                "width": {
                  "type": "integer"
                },
                "height": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "configurator_url": {
          "type": "string",
          "format": "uri",
          "description": "URL where customer can upload photo and configure the product"
        },
        "ordering_flow": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Step-by-step ordering flow"
        },
        "checkout_attribute": {
          "type": "object",
          "description": "How to pass the customer's image URL when creating a checkout session",
          "properties": {
            "key": {
              "type": "string",
              "description": "Attribute key to use in line_items[].custom_attributes"
            },
            "description": {
              "type": "string"
            },
            "required": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "product_nature": {
      "type": "string",
      "description": "Whether product is made_to_order, ready_made, etc."
    },
    "material": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "thickness": {
          "type": "string"
        },
        "process": {
          "type": "string"
        },
        "mounting": {
          "type": "string"
        }
      }
    },
    "social_proof": {
      "type": "object",
      "description": "Social proof and review data for AI shopping agent recommendations",
      "properties": {
        "aggregate_rating": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number",
              "description": "Average rating (e.g. 4.9)"
            },
            "scale": {
              "type": "number",
              "description": "Rating scale maximum (5)"
            },
            "review_count": {
              "type": "integer",
              "description": "Total number of reviews"
            },
            "verified_purchase_count": {
              "type": "integer",
              "description": "Number of verified purchase reviews"
            },
            "reviews_with_photos_count": {
              "type": "integer",
              "description": "Number of reviews with photos"
            }
          }
        },
        "featured_reviews": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "author": {
                "type": "string"
              },
              "rating": {
                "type": "number"
              },
              "variant": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "verified_purchase": {
                "type": "boolean"
              },
              "has_photo": {
                "type": "boolean"
              },
              "date": {
                "type": "string",
                "format": "date"
              }
            }
          }
        },
        "review_source": {
          "type": "string",
          "description": "Review platform (judge.me)"
        },
        "review_page_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "use_cases": {
      "type": "array",
      "description": "Recommended use cases with variant/finish suggestions for AI recommendation engines",
      "items": {
        "type": "object",
        "properties": {
          "occasion": {
            "type": "string",
            "description": "Use case identifier (birthday_gift, home_decor, etc.)"
          },
          "recommended_variant": {
            "type": "string"
          },
          "recommended_finish": {
            "type": "string"
          },
          "price_from": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "why": {
            "type": "string",
            "description": "Explanation for the recommendation"
          },
          "recipient_profile": {
            "type": "string",
            "description": "Target recipient profile, e.g. man_who_has_everything, woman, couple"
          },
          "age_range": {
            "type": "string",
            "description": "Target age range, e.g. 30, 40-49, 50, 60+"
          },
          "seasonal": {
            "type": "boolean",
            "description": "Whether this use case is seasonal (Valentine's, Christmas, etc.)"
          }
        }
      }
    },
    "gifting": {
      "type": "object",
      "description": "Gift purchasing metadata with budget tiers",
      "properties": {
        "is_giftable": {
          "type": "boolean"
        },
        "gift_wrapping": {
          "type": "boolean"
        },
        "gift_message": {
          "type": "boolean"
        },
        "budget_tiers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "variant": {
                "type": "string"
              },
              "from": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    },
    "competitive_positioning": {
      "type": "object",
      "description": "Competitive comparison data for AI shopping comparison",
      "properties": {
        "category": {
          "type": "string"
        },
        "differentiators": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "feature": {
                "type": "string"
              },
              "value": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              },
              "competitor_typical": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              }
            }
          }
        },
        "vs_competitors": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "key_differences": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "sustainability": {
      "type": "object",
      "description": "Environmental and sustainability claims",
      "properties": {
        "material_recyclability": {
          "type": "string"
        },
        "process_claims": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "packaging": {
          "type": "string"
        },
        "certifications": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "gallery": {
      "type": "object",
      "description": "Semantically tagged image gallery for AI visual context",
      "properties": {
        "product_shots": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UCPImage"
          }
        },
        "lifestyle": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UCPImage"
          }
        },
        "size_comparison": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UCPImage"
          }
        },
        "mounting_detail": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UCPImage"
          }
        },
        "close_up": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UCPImage"
          }
        }
      }
    },
    "active_promotions": {
      "type": "array",
      "description": "Currently active promotional offers",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "qualifying_variants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "gift_value": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "active": {
            "type": "boolean"
          },
          "terms": {
            "type": "string"
          }
        }
      }
    },
    "finish_guide": {
      "type": "object",
      "description": "Finish selection guide for AI recommendations",
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "best_for": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "avoid_for": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "decision_rule": {
          "type": "string"
        }
      }
    },
    "b2b": {
      "type": "object",
      "description": "B2B purchasing information",
      "properties": {
        "available": {
          "type": "boolean"
        },
        "programs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "min_order": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "description": {
                "type": "string"
              }
            }
          }
        },
        "contact_email": {
          "type": "string",
          "format": "email"
        },
        "contact_subject": {
          "type": "string"
        },
        "b2b_page_url": {
          "type": "string",
          "format": "uri"
        },
        "vat_invoicing": {
          "type": "boolean"
        }
      }
    },
    "quality_assurance": {
      "type": "object",
      "description": "Quality assurance and trust signals",
      "properties": {
        "individual_inspection": {
          "type": "boolean"
        },
        "inspection_description": {
          "type": "string"
        },
        "color_accuracy": {
          "type": "string"
        },
        "production_method": {
          "type": "string"
        },
        "quality_standard": {
          "type": "string"
        },
        "defect_policy": {
          "type": "string"
        }
      }
    },
    "localized_urls": {
      "type": "object",
      "description": "Product URLs for all supported locales",
      "additionalProperties": {
        "type": "string",
        "format": "uri"
      }
    },
    "available_locales": {
      "type": "array",
      "description": "List of available locale codes",
      "items": {
        "type": "string"
      }
    },
    "ai_summary": {
      "type": "object",
      "description": "Structured AI-friendly summary for shopping agents and LLMs",
      "properties": {
        "one_liner": {
          "type": "string"
        },
        "key_differentiator": {
          "type": "string"
        },
        "ideal_for": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "not_ideal_for": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "decision_factors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "requires_photo_upload": {
          "type": "boolean"
        },
        "has_3d_preview": {
          "type": "boolean"
        },
        "has_template_editor": {
          "type": "boolean"
        },
        "production_timeline": {
          "type": "object",
          "description": "Made-to-order production timeline",
          "properties": {
            "min_days": {
              "type": "integer",
              "description": "Minimum production days"
            },
            "max_days": {
              "type": "integer",
              "description": "Maximum production days"
            },
            "note": {
              "type": "string",
              "description": "Production timeline note"
            }
          }
        },
        "price_breakdown": {
          "type": "array",
          "description": "Price breakdown per variant size",
          "items": {
            "type": "object",
            "properties": {
              "variant": {
                "type": "string"
              },
              "from": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "unique_benefits": {
          "type": "array",
          "description": "Product-specific benefits (e.g. tool_free_mounting, protective_uv_laminate_included)",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "ai_description": {
      "type": "string",
      "description": "Markdown-formatted product description optimized for LLM consumption"
    },
    "faqs": {
      "type": "array",
      "description": "Frequently asked questions about this product",
      "items": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        }
      }
    },
    "product_comparison": {
      "type": "object",
      "description": "Comparison with related products to help AI agents guide selection",
      "properties": {
        "vs_product": {
          "type": "string",
          "description": "Handle of the compared product"
        },
        "vs_product_title": {
          "type": "string",
          "description": "Title of the compared product"
        },
        "differences": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "when_to_choose_this": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "when_to_choose_other": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "shipping_zones": {
      "type": "array",
      "description": "Detailed shipping zone information with delivery estimates per region",
      "items": {
        "type": "object",
        "properties": {
          "zone": {
            "type": "string"
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "delivery_days": {
            "type": "object",
            "properties": {
              "min": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              }
            }
          },
          "carrier": {
            "type": "string"
          }
        }
      }
    }
  },
  "$defs": {
    "Image": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "altText": {
          "type": "string"
        },
        "width": {
          "type": "integer"
        },
        "height": {
          "type": "integer"
        }
      }
    },
    "Money": {
      "type": "object",
      "description": "Currency amounts use major units as decimal strings. v5.2.3 July 2026 Statement reference prices: PL 219 zł / DE €99 / CZ 1499 Kč / DK 749 kr / SE 999 kr / NO 999 kr / CH CHF129 / UK £79 / CA $229 / HU HUF25990 / RO RON319.",
      "properties": {
        "amount": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        }
      }
    },
    "UCPImage": {
      "type": "object",
      "description": "Semantically tagged product image",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "alt": {
          "type": "string"
        },
        "context": {
          "type": "string"
        },
        "width": {
          "type": "integer"
        },
        "height": {
          "type": "integer"
        }
      },
      "required": [
        "url",
        "alt"
      ]
    },
    "UCPVariant": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "sku": {
          "type": [
            "string",
            "null"
          ]
        },
        "price": {
          "$ref": "#/$defs/Money"
        },
        "availability": {
          "type": "string",
          "enum": [
            "in_stock",
            "out_of_stock"
          ]
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            }
          }
        },
        "dimensions": {
          "$ref": "#/$defs/UCPVariantDimensions"
        }
      }
    },
    "UCPVariantDimensions": {
      "type": "object",
      "description": "Verified face dimensions of a product variant",
      "properties": {
        "width_cm": {
          "type": "number",
          "description": "Width in centimeters"
        },
        "height_cm": {
          "type": "number",
          "description": "Height in centimeters"
        }
      }
    }
  }
}