openapi: "3.0.3"
info:
  title: "Orders API"
  version: "1.0.0"
  description: "An order row is meaningless on its own: every order carries a user_id, so the user row has to be written first. The total_cents CHECK constraint exists because the billing service rejects negative totals with a 422 before it ever reaches the ledger. order_items is the table that breaks naive generators, because each item must point at an order id that was actually inserted a few lines above. Placing an order and shipping an order are different transitions, so the status enum has four members rather than a boolean flag."
paths: {}
x-domain-id: "orders"
x-dialect: "postgres"
components:
  schemas:
    users:
      type: "object"
      x-primary-key: "id"
      required: ["id", "email", "created_at"]
      properties:
        id:
          type: "string"
          format: "uuid"
        email:
          type: "string"
          format: "email"
          x-unique: true
        created_at:
          type: "string"
          format: "date-time"
    orders:
      type: "object"
      x-primary-key: "id"
      required: ["id", "user_id", "status", "total_cents", "placed_at"]
      properties:
        id:
          type: "string"
          format: "uuid"
        user_id:
          $ref: "#/components/schemas/users"
        status:
          type: "string"
          enum: ["placed", "paid", "shipped", "cancelled"]
        total_cents:
          type: "integer"
          minimum: 0
        placed_at:
          type: "string"
          format: "date-time"
    order_items:
      type: "object"
      x-primary-key: "id"
      required: ["id", "order_id", "sku", "qty", "unit_price_cents"]
      properties:
        id:
          type: "string"
          format: "uuid"
        order_id:
          $ref: "#/components/schemas/orders"
        sku:
          type: "string"
        qty:
          type: "integer"
          minimum: 1
        unit_price_cents:
          type: "integer"
          minimum: 0
