How can I use OpenAPI overlays to redact sensitive fields from an OpenAPI document?

How can I use OpenAPI overlays to redact sensitive fields from an OpenAPI document? #

Not every field in an OpenAPI schema is meant for public consumption. Internal identifiers, feature-flag fields, PII-adjacent attributes, or fields tied to unreleased functionality often need to be hidden from external-facing documentation while remaining fully documented internally. The OpenAPI Overlay Specification makes this a repeatable, declarative process instead of a manual editing chore.

Marking Sensitive Fields in the Base Document #

A consistent convention such as an x-sensitive: true extension on a property makes it straightforward to identify what needs redacting:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        internalRiskScore:
          type: number
          x-sensitive: true
        ssoProviderId:
          type: string
          x-sensitive: true

Removing a Property With an Overlay #

The remove action works on individual schema properties, not just whole paths:

overlay: 1.0.0
info:
  title: Public Redaction Overlay
  version: 1.0.0
actions:
  - target: $.components.schemas.User.properties.internalRiskScore
    remove: true
  - target: $.components.schemas.User.properties.ssoProviderId
    remove: true

Redacting Fields Across Every Schema #

If sensitive fields share a common name across multiple schemas (e.g., every schema has an internalNotes field), a wildcard target lets you remove them all in a single action:

  - target: $.components.schemas.*.properties.internalNotes
    remove: true

Redacting Response Headers #

Sensitive information sometimes leaks through response headers rather than the body. Overlays can remove these too:

  - target: $.paths['/users/{id}'].get.responses['200'].headers['X-Internal-Trace-Id']
    remove: true

Redacting Example Values Without Removing the Field #

Sometimes the field itself must stay (because it’s part of the public contract), but the example value used in documentation is sensitive or unrealistic. In that case, use update to replace the example rather than remove:

  - target: $.components.schemas.User.properties.email
    update:
      example: "jane.doe@example.com"

Verifying Nothing Was Missed #

After applying a redaction overlay, run a text search across the generated output for known sensitive terms as a safety net:

redocly join openapi.yaml --overlay redaction-overlay.yaml -o dist/public-openapi.yaml
grep -i "internalRiskScore\|ssoProviderId" dist/public-openapi.yaml && echo "REDACTION FAILED" || echo "OK"

Wiring this check into CI prevents a forgotten field from silently making it into public documentation.

See What is the OpenAPI Overlay Specification? for the underlying action model, and How can I use OpenAPI overlays to remove internal endpoints before publishing documentation? for the endpoint-level equivalent of this technique.

Last updated on July 16, 2026.