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.

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

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

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

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

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[?@.name=='filter' && @.in=='query'] 

might require additional optional parenthesis with some implementations like so:

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

See: License (Apache-2.0)