openapi: "3.0.3"
info:
  title: "Shipping and carriers API"
  version: "1.0.0"
  description: "Shipment events are an append-only log, and every event row needs a shipment id that already exists. The tracking number is unique per carrier in the real system, but the seed makes it globally unique to keep the constraint simple. weight_grams is strictly positive, so a generator that produces zero for an empty parcel fails the insert. The status enum has a returned member, because a carrier callback can move a shipment backwards from delivered to returned."
paths: {}
x-domain-id: "logistics"
x-dialect: "postgres"
components:
  schemas:
    carriers:
      type: "object"
      x-primary-key: "id"
      required: ["id", "code", "name"]
      properties:
        id:
          type: "string"
          format: "uuid"
        code:
          type: "string"
          x-unique: true
        name:
          type: "string"
    shipments:
      type: "object"
      x-primary-key: "id"
      required: ["id", "carrier_id", "tracking_number", "status", "weight_grams"]
      properties:
        id:
          type: "string"
          format: "uuid"
        carrier_id:
          $ref: "#/components/schemas/carriers"
        tracking_number:
          type: "string"
          x-unique: true
        status:
          type: "string"
          enum: ["created", "in_transit", "delivered", "returned"]
        weight_grams:
          type: "integer"
          minimum: 1
    shipment_events:
      type: "object"
      x-primary-key: "id"
      required: ["id", "shipment_id", "occurred_at", "location", "code"]
      properties:
        id:
          type: "string"
          format: "uuid"
        shipment_id:
          $ref: "#/components/schemas/shipments"
        occurred_at:
          type: "string"
          format: "date-time"
        location:
          type: "string"
        code:
          type: "string"
