Write the contract first

How to do it

Use OpenAPI 3.1 or 3.2, whose schemas are JSON Schema 2020-12. Review contract changes like code. Lint it with a tool such as Spectral or Redocly. An endpoint that follows an outside protocol, such as MCP or JSON-RPC, uses that protocol's schema as its contract instead.

Example

openapi: 3.1.1
info: { title: Example Shop API, version: 2.3.0 }
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: The order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
        '404': { description: Not found, content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } } }
components:
  schemas:
    Order: { type: object, required: [id], properties: { id: { type: string } } }
    Problem: { type: object, properties: { type: { type: string }, title: { type: string }, status: { type: integer } } }

How to check

The linter passes on the OpenAPI file in the build, and every route the server answers appears in it.