OAI/Overlay-Specification

Overlay Specification

The Overlay Specification defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s).

This specification is a community-driven, open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.

Build, test, schema publication, and release command infrastructure is shared with other OpenAPI Initiative specification repositories through OAI/build-infra. See that repository's README and CONTRIBUTING guide for details on the shared tooling.

Overlays support a range of scenarios, including:

• Translating documentation into another language
• Providing configuration information for different deployment environments
• Allowing separation of concerns for metadata such as gateway configuration or SLA information
• Supporting a traits-like capability for applying a set of configuration data, such as multiple parameters or multiple headers, for targeted objects
• Providing default responses or parameters where they were not explicitly provided
• Applying configuration data globally or based on filter conditions

Overlay Document Schema

A JSON Schema is hosted on spec.openapis.org for informational purposes and to assist tooling. The specification is the only normative description of the document format. If the JSON Schema differs from the specification, then the specification MUST be considered authoritative.

Tools that Support Overlays

If you are looking for tools to use with Overlays, try these:

• Bump.sh CLI
• Speakeasy CLI
• overlays-js
• overlay-jvm
• apigee-go-gen CLI
• openapi-format CLI/UI
• oas-patch CLI
• oas-overlay-java
• Specmatic - Docs
• BinkyLabs.OpenApi.Overlays - dotnet
• Legba - Clojure OpenAPI toolkit
• Zuplo CLI

(Is something missing from the list? Send us a pull request to add it!)

Support for RFC9535 JSONPath

RFC9535 is a recent specification and libraries implementing JSONPath support might predate the RFC. Those libraries might differ entirely (expressions syntax is incompatible), implement additional capabilities (superset of the RFC), or support only a subset of the RFC.

In case the tool being use is not fully compliant with RFC9535, users MIGHT have to update some JSONPath query expressions to accommodate for the implementation in use.

This example JSONPath query expression:

$.paths.*.get.parameters[[email protected]=='filter' && @.in=='query']

might require additional optional parenthesis with some implementations like so:

$.paths.*.get.parameters[?(@.name=='filter' && @.in=='query')]

Licensing

See: License (Apache-2.0)