<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for Gemini: scripts/model-profiles.json -->

#Purpose

Rules for OpenAPI (3.1). The value of a specification is entirely in whether it matches the running service. A hand-written document that drifts is worse than no document — it makes integrators confident and wrong.

Everything here serves one goal: make drift impossible, mechanically.

---

#One source of truth

Pick a direction and enforce it. Both work; maintaining the spec and the code independently does not.

ts
// Code-first: the validator and the spec come from the same zod schema,
// so a route that validates differently than it documents cannot exist.
const OrderSchema = z.object({ id: z.string(), totalCents: z.number().int() });
registry.registerPath({
  method: "get", path: "/v1/orders/{id}",
  responses: { 200: { content: { "application/json": { schema: OrderSchema } } } },
});

Tooling worth naming: zod-to-openapi, @asteasolutions/zod-to-openapi, fastapi (spec is a by-product), drf-spectacular, springdoc-openapi, tsoa, huma. Spec-first: openapi-generator, orval, openapi-typescript, oapi-codegen.

Never hand-maintain a spec beside hand-written route handlers. It will drift within one sprint, and nobody will notice until an integrator does.

---

#Write it so it is usable

yaml
paths:
  /v1/orders/{id}:
    get:
      operationId: getOrder          # becomes the SDK method name — keep it stable
      summary: Fetch an order
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
              examples:
                paid: { $ref: "#/components/examples/PaidOrder" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

Group with tags, and order them for a reader who has never seen the API.

---

#Gate it in CI

Four checks, all cheap:

yaml
- run: npx @redocly/cli lint spec/openapi.yaml --format=github     # valid + style
- run: npx oasdiff breaking origin/main:spec/openapi.yaml spec/openapi.yaml --fail-on ERR
- run: npx @stoplight/spectral-cli lint spec/openapi.yaml          # house rules
- run: npx schemathesis run spec/openapi.yaml --base-url=$URL      # spec vs reality

1. Validity and style — redocly lint or spectral. Add house rules: every operation has an operationId, a description, and a documented 4xx.
2. Breaking-change diff — oasdiff breaking against the merge base. This is the check that actually prevents outages.
3. Spec matches the running service — schemathesis generates requests from the spec and asserts responses conform. It finds drift no diff can.
4. Regenerate and commit — if the spec is generated, CI regenerates it and fails when the committed file differs. Same pattern as any generated artefact.

Contract tests between services close the loop: the consumer's recorded expectations run against the provider's build. → Testing/integration

---

#Downstream artefacts

One spec should produce everything, so nothing is written twice:

• Reference docs — Redoc, Scalar, Stoplight Elements. Never a hand-written endpoint table.
• Typed clients — openapi-typescript for types, orval/openapi-generator for full SDKs. Publish them versioned alongside the API.
• Mock servers — Prism serves the spec, so frontend work starts before the backend exists.
• Postman / Bruno collections — imported from the spec, not curated by hand.

Publish the spec at a stable URL (/openapi.json), versioned. Integrators, their code generators and their AI tooling all read it directly.

Never hand-edit a generated SDK. The next regeneration discards it; fix the spec or the generator template.

---

#Anti-patterns

---

#Checklist

• Verify: One direction — code-first or spec-first — is chosen and enforced
• Verify: Request validation and the spec derive from the same schema definitions
• Verify: Every operation has a stable operationId, summary and description
• Verify: Error responses including 4xx and 429 are documented
• Verify: Shared schemas live in components and are referenced, not duplicated
• Verify: Examples are realistic and reflect actual payloads
• Verify: securitySchemes are declared and applied per operation
• Verify: Constraints (pattern, minimum, maxLength) are expressed in the schema
• Verify: CI lints the spec against house rules
• Verify: CI fails on a breaking diff against the merge base
• Verify: The running service is tested against the spec
• Verify: A generated spec is committed and checked for freshness in CI
• Verify: Docs, SDKs and mocks are all generated from the spec
• Verify: The spec is published at a stable, versioned URL

---

#Anchors (restated last, read last)

The rules that must hold when you stop, repeated here because the end of the context is what you act on:

• Never hand-maintain a spec beside hand-written route handlers. It will drift within one sprint, and nobody will notice until an integrator does.

• Never hand-edit a generated SDK. The next regeneration discards it; fix the spec or the generator template.

• One direction — code-first or spec-first — is chosen and enforced

• Request validation and the spec derive from the same schema definitions

• Every operation has a stable operationId, summary and description

• Error responses including 4xx and 429 are documented

• Shared schemas live in components and are referenced, not duplicated

• Examples are realistic and reflect actual payloads

Before reporting done, prove the module still imports — run the line for this stack and paste its output:

bash
python -c "import <package>"          # Python: the package you changed
node -e "require('./<entry>')"       # Node CJS, or: node --input-type=module -e "import './<entry>.js'"
go build ./...                        # Go