English · 日本語 · 简体中文 · 繁體中文 · 한국어 · Español · Русский · Français · Deutsch · Português (BR)
Language- and tooling-agnostic principles for reviewing changes to OpenAPI definitions (API surface / schema design). The rules describe why a given naming, nullability, typing, structure, or modeling choice should be flagged in review — at an abstraction level that does not depend on any specific programming language, code generator, or YAML syntax.
These are principles, not absolute laws. Deviations are legitimate when justified by compatibility with persisted data or external APIs, or by an established business reason — but such deviations should be made explicit in the review.
The full ruleset is maintained in parallel translations. The Japanese version
(languages/openapi-review-guidelines.ja.md) is the source of truth; other languages are translations
of it. Filenames use ISO 639-1
language codes with a script subtag (Hans/Hant) or region suffix (BR) where relevant.
| Language | File |
|---|---|
| 日本語 (Japanese, source) | openapi-review-guidelines.ja.md |
| English | openapi-review-guidelines.en.md |
| 中文（简体）/ Chinese (Simplified) | openapi-review-guidelines.zh-Hans.md |
| 中文（繁體）/ Chinese (Traditional) | openapi-review-guidelines.zh-Hant.md |
| 한국어 / Korean | openapi-review-guidelines.ko.md |
| Español / Spanish | openapi-review-guidelines.es.md |
| Русский / Russian | openapi-review-guidelines.ru.md |
| Français / French | openapi-review-guidelines.fr.md |
| Deutsch / German | openapi-review-guidelines.de.md |
| Português (Brasil) / Portuguese (Brazil) | openapi-review-guidelines.pt-BR.md |
When editing the rules, change
languages/openapi-review-guidelines.ja.mdfirst, then propagate the change to every translation so the set stays in sync.
- Naming — clarity over brevity, no ad-hoc abbreviations, no implementation/history
leakage, name–value semantic match, correct English, boolean prefixes (
is/has/can), plural arrays, concept-based schema names. - Nullability — separating optional (non-
required) from nullable; grounding null in a real use case; documenting the meaning of null; distinguishing "zero" from "absent". - Types & formats — numeric/boolean types over strings, integer counters, consistent ID
types, RFC 3339 date-time vs date,
uriformat, decimal precision. - Schema structure & reuse — extract repeated structures to components (SSOT),
composition with
allOf, one schema per contractual concept,oneOf/anyOf/discriminator, avoiding derivable fields. - Conceptual modeling & responsibility — single responsibility per schema, one classification axis per enum, domain vs UI-presentation separation, server-side authoritative computation, not leaking external code systems.
- Consistency — uniform spelling/case/pluralization across tags, paths, schemas, enums, properties; matching description to implementation; consistent pagination.
- Intuitive understandability — replacing magic numbers with enums, self-describing enum values, open vs closed enums for forward compatibility, self-contained descriptions, removing dead fields.
- Security & auth — centralizing shared headers as reusable parameters, separating server-to-server webhooks, grounding external-API schemas in real behavior.
- Spec health — single source of truth, validated specs, cross-file propagation of fixes.
examples/github-actions/openapi-ai-review.yml— a minimal, language-parameterized GitHub Actions workflow that reviews a PR's OpenAPI diff against these rules and posts inline comments. Seeexamples/README.md.
The ruleset has been cross-checked against the following authoritative and widely-referenced sources, with which it is broadly aligned:
- OpenAPI Initiative — Best Practices — design-first, single source of truth, version control, component reuse, tags. https://learn.openapis.org/best-practices.html
- OpenAPI Specification — the spec itself (incl.
oneOf/anyOf/allOf,discriminator,nullable, formats). https://spec.openapis.org/ · https://github.com/OAI/OpenAPI-Specification - JSON Schema — the schema vocabulary OpenAPI builds on. https://json-schema.org/
- Zalando RESTful API Guidelines — the most comprehensive public corporate guideline;
naming, null handling (rules 122–124), date-time formats (169), extensible enums
(
x-extensible-enum, 112), composition over inheritance (173), common fields (174), pagination (159–161). http://opensource.zalando.com/restful-api-guidelines/ - Google API Improvement Proposals (AIP) — resource-oriented design, consistent vocabulary, resource naming. https://google.aip.dev/ · AIP-121 / AIP-122 / AIP-190 · Cloud API Design Guide https://cloud.google.com/apis/design
- Microsoft REST API Guidelines (Azure & Graph) — boolean naming, required vs nullable, breaking-change rules for required fields. https://github.com/microsoft/api-guidelines
- Speakeasy — Null in OpenAPI — the optional-vs-nullable three-state problem and its SDK cost. https://www.speakeasy.com/openapi/schemas/null
- Speakeasy — Enums in OpenAPI — open vs closed enums, forward compatibility. https://www.speakeasy.com/openapi/schemas/enums
- API Stylebook — a curated collection of public API design guidelines. https://apistylebook.com/
Areas the literature emphasizes that this ruleset currently covers only lightly, and which are worth consulting in the sources above when relevant:
- Standardized error format — RFC 9457 / RFC 7807 (Problem Details).
- Response-side pagination shape (cursor pagination, standard paging objects with links).
- Idempotency & optimistic locking (
ETag/If-Match). - Standard value formats — ISO 4217 (currency), ISO 3166 (country), ISO 639 (language).
- API versioning strategy specifics (URL path vs media type vs header).
additionalProperties/ maps & dictionaries handling.
MIT © 2026 Kotaro Matsumoto