{
  "openapi": "3.1.2",
  "info": {
    "title": "Example Work Orders API",
    "version": "1.2.0",
    "summary": "A fictional consumer contract for work-order records.",
    "description": "This reserved-domain example documents a consumer-facing API contract. It does not prove an implementation, deployed service, provider integration, or production behavior."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://api.example.test/v1",
      "description": "Reserved example server. It is intentionally not deployed."
    }
  ],
  "tags": [
    {
      "name": "Work orders",
      "description": "Create and inspect fictional work-order records."
    }
  ],
  "security": [
    {
      "oauth2": ["work_orders:read"]
    }
  ],
  "paths": {
    "/work-orders": {
      "get": {
        "operationId": "listWorkOrders",
        "summary": "List work orders",
        "description": "Returns a cursor-paginated collection visible to the authenticated client.",
        "tags": ["Work orders"],
        "security": [
          {
            "oauth2": ["work_orders:read"]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageCursor"
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of work orders.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderList"
                },
                "example": {
                  "items": [
                    {
                      "id": "wo_01hx7m2q",
                      "summary": "Inspect ventilation unit",
                      "priority": "normal",
                      "status": "scheduled",
                      "version": 3,
                      "createdAt": "2026-07-31T09:30:00Z"
                    }
                  ],
                  "nextCursor": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedProblem"
          }
        }
      },
      "post": {
        "operationId": "createWorkOrder",
        "summary": "Create a work order",
        "description": "Creates one work order when validation and the application-level idempotency contract succeed.",
        "tags": ["Work orders"],
        "security": [
          {
            "oauth2": ["work_orders:write"]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkOrderCreate"
              },
              "example": {
                "summary": "Inspect ventilation unit",
                "priority": "normal"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The work order was created and durably identified.",
            "headers": {
              "Location": {
                "description": "Relative location of the created resource.",
                "schema": {
                  "type": "string",
                  "example": "/v1/work-orders/wo_01hx7m2q"
                }
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrder"
                },
                "example": {
                  "id": "wo_01hx7m2q",
                  "summary": "Inspect ventilation unit",
                  "priority": "normal",
                  "status": "scheduled",
                  "version": 1,
                  "createdAt": "2026-07-31T09:30:00Z"
                }
              }
            },
            "links": {
              "GetCreatedWorkOrder": {
                "operationId": "getWorkOrder",
                "parameters": {
                  "workOrderId": "$response.body#/id"
                },
                "description": "Read the newly created record by its response ID."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationProblem"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyConflict"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedProblem"
          }
        },
        "x-idempotency": {
          "kind": "application-convention",
          "keyScope": "authenticated-client plus POST /work-orders",
          "requestFingerprint": "SHA-256 of the normalized request method, path, media type, and body",
          "concurrentFirstWrite": "one request reserves the key; concurrent requests wait for or replay the committed result",
          "retention": "24 hours from the first accepted request",
          "replay": "same key and fingerprint returns the original status, headers, and body",
          "conflict": "same key with another fingerprint returns 409 idempotency_key_reused",
          "reconciliation": "the operator reconciles any downstream side effect by the stored work-order ID before retry"
        }
      }
    },
    "/work-orders/{workOrderId}": {
      "get": {
        "operationId": "getWorkOrder",
        "summary": "Get a work order",
        "description": "Returns one work order by its stable identifier.",
        "tags": ["Work orders"],
        "security": [
          {
            "oauth2": ["work_orders:read"]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkOrderId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested work order.",
            "headers": {
              "ETag": {
                "description": "Opaque representation version for conditional requests.",
                "schema": {
                  "type": "string",
                  "example": "\"work-order-3\""
                }
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrder"
                },
                "example": {
                  "id": "wo_01hx7m2q",
                  "summary": "Inspect ventilation unit",
                  "priority": "normal",
                  "status": "scheduled",
                  "version": 3,
                  "createdAt": "2026-07-31T09:30:00Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedProblem"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Fictional client-credentials flow. Tokens and client secrets stay server-side.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.example.test/oauth2/token",
            "scopes": {
              "work_orders:read": "Read work-order records.",
              "work_orders:write": "Create work-order records."
            }
          }
        }
      }
    },
    "parameters": {
      "WorkOrderId": {
        "name": "workOrderId",
        "in": "path",
        "required": true,
        "description": "Stable work-order identifier.",
        "schema": {
          "$ref": "#/components/schemas/WorkOrderId"
        }
      },
      "PageCursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Opaque cursor returned by the previous page.",
        "schema": {
          "type": ["string", "null"],
          "minLength": 1
        }
      },
      "PageLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Maximum number of records to return.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Application-level replay key. This header is a documented convention, not proof of an HTTP standard or automatic safety.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{16,64}$"
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Opaque request correlation identifier. It contains no credential or customer data.",
        "schema": {
          "type": "string",
          "pattern": "^req_[a-z0-9]{12}$"
        }
      }
    },
    "responses": {
      "ValidationProblem": {
        "description": "The request failed validation.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/validation",
              "title": "Request validation failed",
              "status": 400,
              "detail": "One or more fields are invalid.",
              "instance": "/v1/work-orders",
              "code": "validation_failed",
              "requestId": "req_01hx7m2q9abc",
              "errors": [
                {
                  "pointer": "/summary",
                  "detail": "Must contain at least 3 characters."
                }
              ]
            }
          }
        }
      },
      "Unauthorized": {
        "description": "A valid access token was not supplied.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/authentication-required",
              "title": "Authentication required",
              "status": 401,
              "detail": "Supply a valid bearer access token.",
              "instance": "/v1/work-orders",
              "code": "authentication_required",
              "requestId": "req_01hx7m2q9abc",
              "errors": []
            }
          }
        }
      },
      "Forbidden": {
        "description": "The token lacks the required scope.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/insufficient-scope",
              "title": "Insufficient scope",
              "status": 403,
              "detail": "The operation requires another documented scope.",
              "instance": "/v1/work-orders",
              "code": "insufficient_scope",
              "requestId": "req_01hx7m2q9abc",
              "errors": []
            }
          }
        }
      },
      "NotFound": {
        "description": "The work-order record was not found or is not visible to the client.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/not-found",
              "title": "Work order not found",
              "status": 404,
              "detail": "No visible work order matched the supplied identifier.",
              "instance": "/v1/work-orders/wo_01hx7m2q",
              "code": "work_order_not_found",
              "requestId": "req_01hx7m2q9abc",
              "errors": []
            }
          }
        }
      },
      "IdempotencyConflict": {
        "description": "The idempotency key was already used for another request fingerprint.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/idempotency-key-reused",
              "title": "Idempotency key reused",
              "status": 409,
              "detail": "Use a new key when the normalized request changes.",
              "instance": "/v1/work-orders",
              "code": "idempotency_key_reused",
              "requestId": "req_01hx7m2q9abc",
              "errors": []
            }
          }
        }
      },
      "UnexpectedProblem": {
        "description": "An unexpected problem occurred. The client may retry only under its documented policy.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "https://api.example.test/problems/unexpected",
              "title": "Unexpected problem",
              "status": 500,
              "detail": "The request could not be completed.",
              "instance": "/v1/work-orders",
              "code": "unexpected_problem",
              "requestId": "req_01hx7m2q9abc",
              "errors": []
            }
          }
        }
      }
    },
    "schemas": {
      "WorkOrderId": {
        "type": "string",
        "pattern": "^wo_[a-z0-9]{8}$"
      },
      "WorkOrderCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": ["summary", "priority"],
        "properties": {
          "summary": {
            "type": "string",
            "minLength": 3,
            "maxLength": 160
          },
          "priority": {
            "type": "string",
            "enum": ["low", "normal", "high"]
          }
        }
      },
      "WorkOrder": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "summary", "priority", "status", "version", "createdAt"],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/WorkOrderId"
          },
          "summary": {
            "type": "string",
            "minLength": 3,
            "maxLength": 160
          },
          "priority": {
            "type": "string",
            "enum": ["low", "normal", "high"]
          },
          "status": {
            "type": "string",
            "enum": ["scheduled", "in_progress", "completed", "cancelled"]
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WorkOrderList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items", "nextCursor"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkOrder"
            }
          },
          "nextCursor": {
            "type": ["string", "null"],
            "minLength": 1
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["pointer", "detail"],
        "properties": {
          "pointer": {
            "type": "string",
            "pattern": "^/"
          },
          "detail": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "requestId",
          "errors"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "minLength": 1
          },
          "instance": {
            "type": "string",
            "pattern": "^/"
          },
          "code": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]+$"
          },
          "requestId": {
            "type": "string",
            "pattern": "^req_[a-z0-9]{12}$"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      }
    }
  },
  "x-changelog": [
    {
      "version": "1.2.0",
      "date": "2026-07-31",
      "status": "current",
      "changes": [
        "Documented application-level idempotency behavior for work-order creation.",
        "Added request correlation identifiers to success and problem responses."
      ]
    },
    {
      "version": "1.1.0",
      "date": "2026-06-15",
      "status": "supported",
      "changes": ["Added cursor pagination to the work-order collection."]
    },
    {
      "version": "1.0.0",
      "date": "2026-05-01",
      "status": "retired-example",
      "changes": ["Published the first fictional documentation contract."]
    }
  ]
}