How can I use OpenAPI overlays to test and validate changes before publishing?

How can I use OpenAPI overlays to test and validate changes before publishing? #

An overlay that targets a JSONPath expression which no longer matches anything fails silently in most tooling — the action is simply skipped rather than raising an error. This makes validating the result of applying an overlay just as important as validating the base OpenAPI Overlay Specification document itself. A solid validation workflow catches broken targets, structural regressions, and unintended side effects before they reach a documentation portal or SDK build.

Layer 1: Validate the Base Document #

Before applying any overlay, confirm the base document is itself valid OpenAPI:

redocly lint openapi.yaml

Layer 2: Validate the Overlay File Itself #

Confirm the overlay file conforms to the Overlay Specification’s own schema (version, info, and well-formed actions):

redocly lint overlays/public.yaml --format=overlay

Not all tools support linting overlay files directly; check your specific tool’s documentation for overlay-schema validation support.

Layer 3: Validate the Merged Output #

After applying the overlay, lint the resulting document exactly as you would lint any other OpenAPI file:

redocly join openapi.yaml --overlay overlays/public.yaml -o dist/openapi.public.yaml
redocly lint dist/openapi.public.yaml

Layer 4: Assert That Expected Targets Actually Matched #

Since a mistyped JSONPath silently does nothing, write an explicit test that confirms known changes actually took effect:

const yaml = require('js-yaml');
const fs = require('node:fs');

const merged = yaml.load(fs.readFileSync('dist/openapi.public.yaml', 'utf8'));

if (merged.paths['/internal/admin']) {
  throw new Error('Overlay failed to remove /internal/admin — check the JSONPath target');
}

if (!merged.info.description.includes('public-facing')) {
  throw new Error('Overlay failed to update info.description');
}

Running this kind of assertion suite in CI turns a silent overlay failure into a loud, immediate build failure.

Layer 5: Diff Against the Previous Build #

Comparing the newly generated document against the last known-good version highlights unintended changes that a reviewer might otherwise miss in a large diff:

redocly diff dist/openapi.public.previous.yaml dist/openapi.public.yaml

Layer 6: Snapshot Test Generated Documentation #

For teams that render HTML documentation from the merged spec, a visual snapshot test (using a tool like Percy or Playwright screenshots) can catch rendering regressions introduced indirectly by an overlay change — for example, a missing example that leaves a documentation page looking sparse.

Putting It All Together in CI #

- name: Validate base
  run: redocly lint openapi.yaml

- name: Apply and validate overlay
  run: |
    redocly join openapi.yaml --overlay overlays/public.yaml -o dist/openapi.public.yaml
    redocly lint dist/openapi.public.yaml    

- name: Assert overlay effects
  run: node scripts/assert-overlay-effects.js

- name: Diff against previous build
  run: redocly diff dist/openapi.public.previous.yaml dist/openapi.public.yaml || true

See What is the OpenAPI Overlay Specification? for the underlying model, and How can I use OpenAPI overlays to automate changes in a CI/CD pipeline? for how this validation workflow fits into a broader automated pipeline.

Last updated on July 16, 2026.