Skip to main content
Version: v2

OpenAPI Authoring Standards

Audience: Tech Leads, Backend Engineers, API Designers, QA Engineers
Purpose: Standard rules for writing consistent, self-documenting OpenAPI schema modules across teams.
Last Updated: 2026-03-20
Version: 1.1.0
Change Process: Changes to these guidelines require review and approval.

1. Why These Guidelines Exist​

Schema modules should be reusable, reviewable, and consistent. Clear standards reduce contract drift, improve generator reliability, and simplify integration.

Goals:

  • Keep each schema self-describing for consumers and reviewers.
  • Keep request, response, and webhook models consistent across domains.
  • Ensure all $ref links resolve cleanly across files.
  • Enforce schema quality with automated lint checks.

2. File and Top-Level Structure​

Use this module structure:

openapi: 3.1.1
info:
  version: "v2"
components:
  schemas:

Rules:

  • Treat each file as a schema module, not a full API spec with paths.
  • Keep top-level key order as shown above.
  • Use YAML and preserve consistent indentation.
  • Run the project's schema lint command before merge.

3. Directory and File Organization​

Use a consistent folder structure:

  • <domain>/request/** for request schemas
  • <domain>/response/** for response schemas
  • <domain>/common/** for shared schema fragments
  • <domain>/webhook/** for webhook payload schemas

Rules:

  • Use kebab-case for webhook schema filenames (example: resource-created-webhook.schema.yaml).
  • Keep related fragments under common instead of duplicating fields.
  • Place success and error responses under dedicated response subfolders.

4. Naming Conventions​

Rules:

  • Use PascalCase for components.schemas keys.
  • Use consistent suffixes (Request, Response, Base, Details).
  • Keep operation-level wrappers explicit (for example Resource200Response, Resource422Response).

5. Reference Strategy​

Rules:

  • Use local anchors for same-file refs: #/components/schemas/....
  • Use relative refs for cross-file links with schema anchors.
  • Do not use same-file relative path refs like ./this-file.yaml#/components/schemas/....
  • Prefer shared refs over inline duplication.

6. Request Schema Patterns​

Rules:

  • Keep required fields in object-level required.
  • Keep field constraints in schema keywords (minimum, maxLength, pattern, minItems, etc.).
  • Use allOf to extend common base request schemas.
  • For mutually exclusive request shapes, use oneOf plus branch constraints.

7. Response Schema Patterns​

Rules:

  • Use consistent response wrappers for success and errors.
  • Keep status-specific schemas explicit and reusable.
  • Keep shared response fields in common base response schemas.
  • Ensure required wrapper fields are declared where contractually mandatory.

8. Webhook Schema Patterns​

Rules:

  • Keep event payload schemas under <domain>/webhook/**.
  • Reuse common webhook response fragments from <domain>/webhook/common/**.
  • Keep event naming and payload mapping consistent with resource schemas.
  • Ensure webhook file names and $ref paths stay aligned.

9. OpenAPI 3.1 Validation Rules​

  • default values must conform to declared type.
  • required applies to properties in the same object schema branch.
  • Use format only with compatible base types.
  • If type: array is present, define items.
  • Examples should conform to schema constraints.

10. Property Documentation Rules​

Rules:

  • Include description for public-facing or non-obvious fields.
  • Use concise processing notes where behavior is conditional.
  • Keep prose aligned with actual schema constraints.
  • Use consistent terminology for required, nullable, and constraints.

11. Enum Rules​

Rules:

  • Keep enum values consistent in style and meaning.
  • Document restricted subsets per context using composition where needed.
  • Mark internal-only enum values clearly in descriptions.

12. Error Schema Rules​

Rules:

  • Keep structural and business-error schemas distinct.
  • Reuse shared error structures where possible.
  • Keep async failure payloads consistent with resource shape conventions.

13. Composition and Strictness​

Rules:

  • Use allOf for extension and contextual overrides.
  • Use oneOf for exclusive variants and avoid ambiguous overlap.
  • Use additionalProperties: false or unevaluatedProperties: false only when strict contracts are intended.
  • Keep required and properties aligned within each object scope.

14. Common Anti-Patterns​

  • Duplicating schema fragments instead of reusing $ref.
  • Declaring constraints only in description text.
  • Mismatching filename conventions and $ref paths.
  • Using inconsistent names for equivalent schemas.

15. Review Checklist​

Schema File​

  • Top-level structure uses openapi, info, components.
  • info.version is set consistently for the target module version.
  • Schema keys are PascalCase.

References​

  • Same-file refs use local anchors.
  • Cross-file refs resolve and include schema anchors.
  • No stale refs after file moves/renames.

Request/Response/Webhook​

  • Request schemas use correct required fields and constraints.
  • Response wrappers and status-specific schemas are consistent.
  • Webhook payload schemas are aligned to event names and file names.

Quality Gates​

  • Project schema lint command passes.
  • No unresolved $ref targets.
  • No duplicated schema definitions where shared refs exist.