openapi-conventions

Use when creating or editing an openapi.yaml for a service component — designing endpoints, request/response schemas, errors, pagination, or security for a REST API.

SKILL.md

GitHub

OpenAPI conventions

Every service component gets one spec at specs/design/components/<name>/openapi.yaml, authored as OpenAPI 3.0.3.

The spec is validated as it lands. A write to that path is rejected (INVALID_OPENAPI) unless the document is OpenAPI 3.x with at least one path and one operation, and a rejected write changes nothing. So a spec that applied cleanly has already passed that check: do not re-validate it with a separate tool. Handing your own spec back to a validator as pasted text costs a round trip and re-emits the entire document — for a check that already ran.

Coverage is checklist-driven, not vibes: walk the PRD (specs/requirements/prd.md) against the component's design.json responsibility, and give every capability the requirements assign to THIS component its resource(s) and every core entity its schema. A capability with no endpoint is a defect. Commonly dropped when consolidating services: audit trail/logs, user & role management, notification preferences, reporting/analytics — check for each explicitly before finishing.

Keep the spec COMPACT. Complete coverage, minimal prose: a short summary per operation and a one-line description per response — no multi-sentence descriptions, no example/examples blocks, no speculative endpoints the requirements don't imply. Schemas carry the required fields plus the few core properties that define the entity — not every conceivable attribute. A property whose name and type do not give its meaning, such as a unit, a direction or a sign, gets a one-line description in each schema that has it.

For resource taxonomy (collection/atomic/controller), URI grammar, HTTP-method semantics, and a full worked example, read references/wso2-rest-api-design-guidelines.md — the source of truth this summary condenses.

Structure

  • servers: is relative — - url: / — never an absolute external host.
  • Paths are kebab-case plural nouns (/expense-claims, /expense-claims/{claimId}/line-items); verbs only for controller actions (/expense-claims/{claimId}/submit). Max two nesting levels.
  • Every operation has operationId in lowerCamelCase verb+resource (listExpenseClaims, submitExpenseClaim) and a non-empty summary.
  • Every response has a non-empty description. Bodies are application/json. Reusable schemas live under components/schemas.

Errors — one shared schema

Define components/schemas/Error and reference it from EVERY 4xx/5xx response:

Error:
  type: object
  required: [code, message]
  properties:
    code: { type: integer, description: "HTTP or application error code" }
    message: { type: string, description: "short human-readable label" }
    description: { type: string, description: "detailed explanation" }
    moreInfo: { type: string, description: "URI to documentation" }

Each operation declares at least its failure modes: '400'/'404' where applicable, plus '401'/'403' when the API is authenticated.

Pagination — every collection GET

Parameters limit (integer, default 20, max 100) and offset (integer, default 0). The 200 response is an envelope, not a bare array:

type: object
required: [count, data]
properties:
  count: { type: integer, description: "total matching items" }
  next: { type: string, nullable: true, description: "relative URI of the next page" }
  previous: { type: string, nullable: true, description: "relative URI of the previous page" }
  data: { type: array, items: { $ref: '#/components/schemas/ExpenseClaim' } }

Filtering and searching are query parameters on the collection GET (?status=submitted, ?employeeId=...) — never separate endpoints.

Security

This block is the gateway's configuration, and the ONLY place the rule lives. Deploy renders one gateway route per operation from it: the audience it pins and the single scope it requires. The service holds no copy of it — a request that fails this check never reaches the service at all. Get it right here and there is nothing else to configure anywhere.

A component that depends on the sign-in resource type declares one scheme, one document-level default, and per-operation overrides:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/authorize
          tokenUrl: /oauth2/token
          scopes:
            claims:read: See own claims
            claims:submit: Create and send a claim
security:
  - oauth2: []        # document default: any signed-in user

Every scope key, here and on an operation, is a handle from specs/design/security.json — <resource>:<action> — for a resource THIS component owns. Never invent one.

openid, profile, email, group and ou are reserved OIDC scopes that ride every access token, so one of them on an operation would admit every signed-in person in the organisation — silently, and wide open. The gate refuses all five as an operation scope and as a flows.*.scopes key.

Three states, and only three. Each operation is exactly one of:

security on the operation Means Gateway Service
absent (inherits the document default) any signed-in user token required; signed assertion forwarded 401 when the assertion is missing or does not verify
security: [] public no token checked; no assertion minted reads no identity at all
security: [{oauth2: ["<handle>"]}] that permission scope enforced, whole-string; 401 otherwise no scope check — a request that arrives has passed it

The gateway answers 401 for every refusal (no token, expired, wrong audience, missing scope) with the same body and no WWW-Authenticate. No generated service answers 403: the only authorization question left to it is "is this row the caller's", and that answer is 404 (api-management).

Exactly one scope per operation. No two-element list, no second scheme object, no allOf/anyOf question for the gateway and the service to answer differently.

Reach is the path

Which rows an operation reaches is its path, and nothing else says it:

Path Reaches Guarded by
/me/<resource> the caller's own rows the resource's own-rows action — claims:read, claims:submit
/me/<relation>/<resource> rows of a relation of the caller's — /me/team/claims, /me/company/orders its own action — claims:review-manager
anything else every row the every-row action — claims:read-all, claims:approve

The <relation> is a noun the domain model has (team because Employee has a managerId), never a role or a group name — /me/team/claims, not /manager/claims. Some operation writes that relation: if none sets managerId, /me/team/claims is empty for every caller. The handler behind a /me/… path resolves the rows through the gateway assertion's sub and nothing the client sends; a row that is not the caller's does not exist there, so the answer is 404, never 403.

Two consequences, both mechanical:

  • One reach per handle. A handle guards operations under /me/ or outside it, never both — the same grant cannot mean "your rows" on one operation and "every row" on another. The gate refuses the document that mixes them, naming both operations. A capability with two reaches is two operations with two handles: GET /me/claims on claims:read, GET /claims on claims:read-all.
  • Nothing widens. There is no handler-side check that turns one list into a bigger one. A caller who may see every claim calls GET /claims; the SPA picks the operation for the screen, and the gateway is the whole of the decision. A role that needs both views holds both handles.

Say the reach in the operation's summary too — "The caller's claims", "Every claim" — so a reader of the contract does not have to parse the path for it.

bearerAuth is not used on this platform. A component with no sign-in dependency declares no security scheme at all.

Declare no identity header. The gateway hands the service the caller as a signed x-jwt-assertion; the unsigned X-User-* headers it also sets are not an authority and nothing reads them (api-management). Neither belongs in the contract: the assertion is a property of the deployment, not of the API, and a declared X-User-Id parameter invites a handler to bind one. The write gate refuses a required: true identity header and any identity header on a public operation; the correct document simply has none.

paths:
  /me/claims:
    get:
      summary: "The caller's claims"
      security:
        - oauth2: [claims:read]
  /claims:
    get:
      summary: "Every claim"
      security:
        - oauth2: [claims:read-all]
  /health:
    get:
      security: []

Never spec an auth endpoint. No /auth/login, /auth/register, /auth/logout, or any other token-issuance path on any service: the IDP issues tokens and the gateway validates them (see thunder-authentication). Specifying one puts the coding agent's issue in direct conflict with its skills.

YAML hygiene

2-space indentation throughout; quote status-code keys ('200', '404'). The file is edited with anchored string edits later, so consistent indentation is load-bearing. Put each summary and description value in double quotes. In a flow mapping ({ … }), a comma ends a value that has no quotes, and the text after it becomes a new key with no value: { type: string, description: "e.g. submitted, approved" }.