OpenAPI Initiative specifications are currently like London buses: You wait ages for one and then four come along at once. We saw the Arazzo Specification arrive on the scene in early 2024, sparking huge interest in the API community around describing multiple API calls as a workflow. We also had two patch releases to the main OpenAPI Specification in October 2024, together with Overlay version 1.0.0, a specification for executing updates to OpenAPI descriptions in a standardized way.

In fairness to the Overlay Specification, it has been published as an Implementers Draft for two years. The team involved in Overlay decided it was timely to formalize the specification as an official version. Implementers Drafts are great for getting the word out and getting early sight of key functionality, but official versions allow tooling makers to commit to building tools to support them.

The use case for Overlay is different from OpenAPI and Arazzo, in that it helps API providers publish and manage API descriptions, supporting automation, quality assurance, and governance functions. The great thing about the Overlay Specification is that it can be leveraged across the API lifecycle whenever an update to a given OpenAPI document is required.

What is an Overlay?

In simple terms, an Overlay is a JSON or YAML document that describes a series of updates to an OpenAPI description. Each update is based on an Action Object, which represents an imperative. At version 1.0.0, the supported imperatives are update and remove, with update being an instruction to add or merge an object provided in the Overlay document using an object defined as the update value. remove is always set to true.

The Action Object also implements a JSONPath as a pointer to the objects that should be processed. The great thing about using JSONPath is that it makes an Overlay highly extensible. The target in the Overlay Specification is an OpenAPI description, but it can feasibly be used for any JSON or YAML document.

As ever, explaining something like Overlay is best done by example. For example, the Server Object in the OpenAPI Specification provides deployment information to API consumers, including details of the URL a given API is hosted at. A servers property is provided at the root of an OpenAPI document. The snippet below is an example servers property, with a default local HTTP instance for development and a standardized value for production, with a hostname variable that defaults back to localhost.

servers:
 - url: 'http://localhost:8080'
 description: Local instance of API for development
 - url: 'https://{hostname}/api'
 description: Production API
 variables:
 hostname:
 description: The hostname for the deployed instance
 default: localhost

Let’s assume that an organization needs to apply governance to the Server Object values when publishing the API description, namely:

• The local instance over HTTP is removed, as this is never used outside a local development environment.
• The default value of the hostname variable of the production API needs to be changed to the correct value, so API consumers are automatically provided with the correct value.

The changes above are made whenever the API description is published, so automation makes good sense in this context. Describing these changes using an Overlay document makes this effort simple, as the API provider can write the required changes once and apply them multiple times. The maintainer of the Overlay document could also generate the Overlay document, if the source of truth for such is an internal system or build tool.

To remove the localhost instance served over HTTP, we can implement remove:

target: $.servers[?(@.url.match(/^http:\/\/localhost/))]
action: remove

The JSONPath uses the match function to remove anything hosted at localhost and served over HTTP, which can be expanded to cover anything served over HTTP, based on organizational security policies. The second action then updates the value of the Production API, changing the default value of the hostname variable:

target: $.servers[?(@.description == 'Production API')].variables.hostname.default
update: examples.nordicapis.io

Implemented together, an Overlay document containing these instructions is defined as follows:

overlay: 1.0.0
info:
 title: Nordic APIs `servers` example
 description: An example of using the Overlay Specification to update multiple Server Objects
 version: 1.0.0
actions:
 - target: $.servers[?(@.url == 'http://localhost:8080')]
 remove: true
 - target: $.servers[?(@.description == 'Production API')].variables.hostname.default
 update: examples.nordicapis.io

The Overlay document can then be used to process a given OpenAPI document, using a CLI like overlayjs:

overlayjs --openapi openapi.yaml --overlay update-servers.yaml

Approaching the task of keeping deployment information up-to-date, therefore, becomes a process of creating an Overlay document once, maintaining that document based on the correct source of truth, and then executing a script at the correct place in the API description pipeline.

Overlay and the API Lifecycle

The example above shows how the Overlay Specification provides a consistent, deterministic mechanism for updating one or more OpenAPI descriptions. Considering OpenAPI description updates as a one-off operation oversimplifies how such changes can occur across the API lifecycle, are often executed manually, and how information included in a given OpenAPI description comes from many different places. Encoding updates to OpenAPI descriptions using approaches like the Overlay Specification improves quality, reduces errors, and frees up technical resources in many departments.

Pose the following questions to yourself when you think about how deployment information is added to your OpenAPI descriptions, and the Server Object example above:

1. When your organization updates the servers values in your OpenAPI descriptions, who does that?
2. When the servers information is updated, is it always correct?
3. How is the information added to the document?

If the answers to the questions above are “a human”, “no”, and “copy-and-paste,” then Overlay may well be for you. You can use Overlay for all sorts of updates to your OpenAPI descriptions, including:

• Apply standardized Security Requirements based on corporate policies, and in doing so, take responsibility from API designers.
• Removing internal notes and Specification Extensions, as a clean-up mechanism before publishing to external API consumers.
• Providing default responses or standardized error responses across all HTTP status codes that reflect either API guidelines or the capabilities of your API gateway.

The Future of Overlay Specification

As ever, tooling support will take time to mature, with some options already available, but Overlay is a relatively simple specification to implement. Taking the plunge and creating your own implementation of Overlay is a great investment for the future, especially as tooling support grows, as your Overlay documents can migrated to other tools based on the standards at a later date. This is interoperability, which is one of the reasons why standards exist, and why initiatives like Overlay are so important to the API community.