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.