This is one of the use cases I flagged as underexplored in my Many Use Cases for OpenAPI Overlays post, and it is quietly my favorite one. Most of the time when we talk about API governance, we mean a linter. You point Spectral at a spec, it checks the spec against a ruleset, and when the spec falls short it fails the build and hands the developer a list of grievances to go fix by hand. That is enforcement. It tells you that you are non-compliant, and then it stops. Useful, but it is fundamentally a nag with a exit code. What Spectral will never do is bring the spec into compliance for you. Overlays will.
An OpenAPI Overlay is a separate document that describes a set of targeted changes to apply to an OpenAPI description. Instead of encoding your org standard as a rule that fails a spec, you encode the standard as the patch that satisfies it. Same standard, opposite verb. Enforce says “your contact block is missing.” Apply says “here is the contact block.” Let me show you against my Products API teaching template, which is deliberately a little under-governed so there is something to fix.
Here is the org-standard overlay. It injects the contact and license blocks every API in the org is supposed to carry, defines the standard bearer-token security scheme and applies it at the top level, and stamps the mandatory products tag on the operations.
overlay: 1.1.0
info:
title: Acme Org Standard Overlay
version: 1.0.0
extends: https://raw.githubusercontent.com/api-evangelist/products-api/main/openapi/products-api-openapi.yml
actions:
- target: $.info
update:
contact:
name: Acme API Platform Team
email: [email protected]
url: https://developer.acme.example
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
- target: $.components.securitySchemes
update:
acmeBearer:
type: http
scheme: bearer
bearerFormat: JWT
- target: $
update:
security:
- acmeBearer: []
- target: $.paths[*][*].tags
update:
- products
Every one of those actions maps to a rule you have probably already written for Spectral. “info must have a contact.” “info must have a license.” “every API must declare a security scheme and reference it.” “every operation must be tagged.” The difference is that if I run this overlay against the Products API, the output is a spec that has those things, not a report saying it does not. The standard is not a promise anymore, it is a transformation.
The second overlay is server templating, which is where governance-as-artifact really earns its keep. The org convention is that every server URL is an {environment} template so the same spec drives dev, staging, and prod. The Products API ships a couple of hardcoded servers, so I replace them wholesale.
overlay: 1.1.0
info:
title: Acme Server Templating Overlay
version: 1.0.0
extends: https://raw.githubusercontent.com/api-evangelist/products-api/main/openapi/products-api-openapi.yml
actions:
- target: $.servers
update:
- url: https://{environment}.api.acme.example/products
description: Acme templated environment endpoint
variables:
environment:
default: prod
enum:
- dev
- staging
- prod
A Spectral rule can assert that servers[*].url matches your templating pattern and fail every spec that does not. This overlay makes the spec match the pattern. That is the whole argument in one action.
Here is why I keep coming back to this framing. Standards and artifacts outlive tools. Spectral is great, but it is a tool, and tools get swapped, versioned out, or abandoned. When your governance lives inside a linter config, it walks out the door with the linter. When your governance is an overlay, it is a version-controlled YAML document you can diff, review in a pull request, audit, and re-apply against any spec, forever, with whatever tooling reads Overlay 1.1.0. The standard is the artifact, not the enforcement of it.
An overlay turns a one-off edit into a named, diffable, re-appliable transformation. That is exactly the property that makes it a governance primitive and not just a convenience, and it is the reason I think most teams have the model backwards. Stop shipping rules that fail specs. Ship overlays that fix them.
