OAI/Overlay-Specification

The Overlay Specification is a document format standard that augments existing OpenAPI descriptions while remaining separate from their source documents.

The specification addresses the need to extend and modify OpenAPI descriptions without altering the original source. It enables scenarios such as translating documentation into other languages, providing environment-specific configuration, separating concerns like gateway settings or SLA metadata, applying trait-like configuration sets to targeted objects, supplying default responses or parameters, and applying configuration data globally or conditionally. Overlays accomplish this through a JSON Schema-based document format that references and modifies elements of an existing OpenAPI description using JSONPath expressions.

Organizations should adopt this specification when they need to maintain multiple variants of API documentation or configuration without duplicating or modifying the canonical OpenAPI source. It suits projects where different teams or deployment environments require different metadata, documentation languages, or configuration parameters layered on top of a shared API definition. The specification is particularly valuable in large organizations where API gateway teams, documentation teams, and backend teams need to independently augment the same API contract. A JSON Schema is available for tooling support, though the specification document itself remains the authoritative reference.

The project is maintained as a community-driven specification within the OpenAPI Initiative under the Linux Foundation. Build, test, schema publication, and release infrastructure is shared with other OpenAPI Initiative specification repositories through a centralized build infrastructure repository. The specification includes guidance on RFC9535 JSONPath compliance, acknowledging that tools implementing overlays may have varying levels of conformance to the standard and may require users to adjust JSONPath expressions accordingly.