OpenAPI documents

Interfaces are described in OpenAPI 3. The document is the contract: it says which endpoints exist, what they accept, what they return, and what they return when they fail.

What the document specifies

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0

paths:
  /orders/{orderId}/refund:
    post:
      operationId: requestRefund
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, pattern: '^A-[0-9]+$' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RefundRequest' }
      responses:
        '200':
          description: Refund granted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RefundResult' }
        '422':
          description: Refund refused
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

components:
  schemas:
    RefundRequest:
      type: object
      required: [reason]
      properties:
        reason:
          type: string
          minLength: 3
          maxLength: 280
    RefundResult:
      type: object
      required: [orderId, amount, currency, status]
      properties:
        orderId: { type: string }
        amount: { type: number, format: decimal }
        currency: { type: string, enum: [EUR, USD, GBP] }
        status: { type: string, enum: [refunded] }

The things worth noticing:

operationId is mandatory and stable. It is the join key between the interface and the behaviour. A scenario that references requestRefund can be checked against the document; a scenario that references a path by hand cannot be checked reliably.

Responses include the failures, with the same rigour as the success. A contract that documents only the 200 response is not a contract. The failure responses here carry a schema, which is what makes an error path checkable.

Schemas are named, not inline. $ref to components/schemas keeps the document readable and makes the schema reusable — and reusable schemas are the ones that stay consistent.

Enums and patterns carry real constraints. enum: [refunded] and pattern: '^A-[0-9]+$' are assertions the platform can check against a live response. An anyOf with a comment saying "one of these" is not.

What the contract checks can prove

An OpenAPI document is executable. That is the point of specifying in a machine-readable format.

Schema conformance. Every response is validated against its declared schema. Fields with the wrong type, missing required fields, unexpected extra fields, and enum violations are all caught. This is the check that finds the majority of real integration bugs.

Contract compatibility. The document is linted for breaking changes against the previous version. Removing an operation, narrowing an accepted type, adding a required field, or changing a response code are all breaking changes and are flagged as such.

Example validity. Every example in the document is validated against its schema. An example that does not satisfy the schema it sits under is a broken document, and it is exactly the kind of error that survives because nobody reads the examples.

Operation existence. Every operation a scenario references exists in the document. See cross-format consistency.

What the contract cannot prove

A schema constrains shape. It says nothing about meaning.

A perfectly valid response can still be wrong: the right fields with the wrong values, the right status code for the wrong reason, a 200 where a 409 was owed. No amount of schema validation catches that, because the schema has no way to express "the refund amount must equal the order total".

This is the boundary between the two formats. OpenAPI proves the shape of the response; Gherkin proves the behaviour of the system. A specification that uses only OpenAPI has a gap exactly where the business rules live.

Versioning

The document carries a version, and the platform keeps the previous version alongside it so that contract compatibility can be checked on every change. We recommend semver on the document version, and a separate breaking-change flag when the break is intentional and coordinated.

When a breaking change is approved, the platform records the exemption against the specific operation and the specific clause that justified it. That exemption is then visible in the completion map rather than buried in a commit message.

Next