openapi: "3.0.3"
info:
  title: "Product catalog API"
  version: "1.0.0"
  description: "A product has no price by itself; the price lives on the variant, which is why a seed that only fills products produces a catalog that renders empty. The stock column is constrained to be non-negative because overselling is caught by the checkout service rather than by the database. Inventory items are a third level of nesting, and each level needs its own id to be reused by the level below it. The product slug is unique because the storefront routes by slug, so two identical slugs break the whole public site."
paths: {}
x-domain-id: "catalog"
x-dialect: "postgres"
components:
  schemas:
    products:
      type: "object"
      x-primary-key: "id"
      required: ["id", "slug", "title", "status", "created_at"]
      properties:
        id:
          type: "string"
          format: "uuid"
        slug:
          type: "string"
          x-unique: true
        title:
          type: "string"
        status:
          type: "string"
          enum: ["draft", "active", "archived"]
        created_at:
          type: "string"
          format: "date-time"
    variants:
      type: "object"
      x-primary-key: "id"
      required: ["id", "product_id", "sku", "price_cents", "stock"]
      properties:
        id:
          type: "string"
          format: "uuid"
        product_id:
          $ref: "#/components/schemas/products"
        sku:
          type: "string"
          x-unique: true
        price_cents:
          type: "integer"
          minimum: 0
        stock:
          type: "integer"
          minimum: 0
    inventory_items:
      type: "object"
      x-primary-key: "id"
      required: ["id", "variant_id", "warehouse", "on_hand", "reserved"]
      properties:
        id:
          type: "string"
          format: "uuid"
        variant_id:
          $ref: "#/components/schemas/variants"
        warehouse:
          type: "string"
        on_hand:
          type: "integer"
          minimum: 0
        reserved:
          type: "integer"
          minimum: 0
