How can I use OpenAPI overlays to enrich schemas with additional validation rules?

How can I use OpenAPI overlays to enrich schemas with additional validation rules? #

Sometimes stricter validation rules apply in one context but not another — a sandbox environment might accept looser input for testing convenience, while production enforces tighter constraints; or a documentation-only “recommended” set of constraints might be presented to developers without actually being enforced by every consuming service yet. The OpenAPI Overlay Specification lets you layer these additional JSON Schema keywords onto an existing schema without editing the canonical component definition.

Adding Format and Pattern Constraints #

overlay: 1.0.0
info:
  title: Stricter Validation Overlay
  version: 1.0.0
actions:
  - target: $.components.schemas.User.properties.email
    update:
      format: "email"
      pattern: "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
  - target: $.components.schemas.User.properties.phoneNumber
    update:
      pattern: "^\\+[1-9]\\d{1,14}$"
      description: "Must be in E.164 format."

Tightening Numeric Bounds for Production #

  - target: $.components.schemas.Order.properties.quantity
    update:
      minimum: 1
      maximum: 1000

A sandbox overlay might instead leave these bounds relaxed or omit them entirely, allowing testers to submit edge-case values that production rejects.

Adding `enum` Constraints Progressively #

When introducing a new enum constraint on a previously free-form string field, it’s often safer to roll it out first as documentation-only (via description) and only later as an enforced overlay, once you’ve confirmed no existing clients send out-of-range values:

  - target: $.components.schemas.Order.properties.status
    update:
      enum: ["pending", "processing", "shipped", "delivered", "cancelled"]

Adding Cross-Field Validation Hints #

JSON Schema keywords like dependentRequired (available under OpenAPI 3.1’s full JSON Schema 2020-12 support) can be layered on to document conditional requirements:

  - target: $.components.schemas.ShippingAddress
    update:
      dependentRequired:
        poBox: ["poBoxCountryCode"]

Combining Multiple Constraints in One Pass #

  - target: $.components.schemas.Product.properties.sku
    update:
      pattern: "^[A-Z]{3}-\\d{6}$"
      minLength: 10
      maxLength: 10
      description: "Three uppercase letters, a hyphen, then six digits."

Validating That the Overlay Doesn’t Break Existing Data #

Before enforcing stricter constraints in production, run the enriched schema against a sample of real historical payloads to check that no legitimate existing data would suddenly fail validation:

redocly join openapi.yaml --overlay validation-overlay.yaml -o dist/openapi.yaml
ajv validate -s dist/openapi.yaml --data "samples/*.json"

Applying the Overlay Selectively #

Because validation strictness often needs to differ by environment, this technique pairs naturally with per-environment overlays — see the related guide below for combining both approaches.

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to customize documentation per environment (dev/staging/prod)? for combining environment- and validation-specific overlays.

Last updated on July 16, 2026.