x-mint extensions.
Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, openapi frontmatter references, and mint validate all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.
Create an overlay document
An overlay document has anoverlay version, an info object with a title and version, and an actions array. Each action selects nodes with a target RFC 9535 JSONPath expression and applies one modifier:
update: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.remove: Deletes each targeted node when set totrue.copy: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.
docs-overlay.yaml
extends field links an overlay to a specification for auto-discovery. Set it to a path relative to the overlay file, or to the exact URL your docs.json uses for a hosted specification.
Reference overlays in your docs.json
List overlays with the object form of theopenapi field, which works anywhere openapi is accepted, including inside arrays. Overlays apply in the order you list them.
docs.json
https. Referencing the same specification with different overlays lists in different places fails the build.
Auto-discover overlays
Any JSON or YAML file in your repository with a top-leveloverlay key is treated as an overlay document. If its extends field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an extends field never apply automatically.
An explicit overlays list replaces auto-discovery for that specification. Set "overlays": [] to disable all overlays for a specification, including auto-discovered ones.
Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.
Rename a path
The Overlay Specification has no move action. To rename a path, create the new path withupdate, copy the existing path item into it with copy, then delete the old path with remove.
rename-overlay.yaml
openapi: "POST /credit/accounts".
Test overlays locally
Inmint dev, editing or deleting an overlay file rebuilds the affected specifications. mint validate and mint openapi-check validate the transformed document, so errors reference your specification after overlays apply.