If you’re one of the people who maintain overlays like this, this article was written just for you. We’ll go through three ways to stop pasting the same change into an overlay, show where each of them breaks, and look at what the new Overlay 1.2.0, released on 22 September 2026, changes about it.

What is an Overlay?

Let’s first define it. I took the following description directly from the Overlay specification:

An Overlay is represented in JSON or YAML and contains actions that are applied in order to an OpenAPI description. Each action uses a target expressed as a RFC9535 JSONPath query expression to identify where changes apply.

Overlay Specification 1.2.0

In practice, an overlay is how you keep one source description and still publish different versions of it: one for public docs, one for an SDK generator, one for a partner. Instead of maintaining copies of the description, you maintain a list of changes. Each action has a target that says where, and update, copy, or remove that says what.

The copy-paste problem

Here is a small OpenAPI description I’ll use for the rest of the article:

openapi: 3.1.0
info:
  title: Accounts API
  version: 1.0.0
paths:
  /accounts:
    get:
      operationId: listAccounts
      responses:
        '200':
          description: A page of accounts.
  /accounts/{id}:
    get:
      operationId: getAccount
      responses:
        '200':
          description: One account.
    delete:
      operationId: deleteAccount
      responses:
        '204':
          description: Account deleted.
  /transfers/{id}:
    get:
      operationId: getTransfer
      responses:
        '200':
          description: One transfer.

Every operation on /accounts/{id} and /transfers/{id} can return 404; listAccounts can’t. This is the overlay most people write first:

overlay: 1.1.0
info:
  title: Add error responses
  version: 1.0.0
actions:
  - target: $.paths['/accounts/{id}'].*.responses
    update:
      '404':
        description: The resource does not exist.
        content:
          application/problem+json:
            schema:
              $ref: '#/components/schemas/Problem'
  - target: $.paths['/transfers/{id}'].*.responses
    update:
      '404':
        description: The resource does not exist.
        content:
          application/problem+json:
            schema:
              $ref: '#/components/schemas/Problem'

It’s correct, and with two paths it’s even readable. But the duplication grows with every path you add, and it’s the worst kind of duplication: the copies are supposed to stay identical, nothing checks that they do, and an outdated copy still applies without any error.

There’s one thing this naive version gets right, though, and it’s worth keeping in mind for the rest of the article: every target is its own action. When you apply it with a strict tool, a target that matches nothing fails on its own. Not every shortcut below keeps that.

A word on union selectors

RFC 9535 JSONPath allows several names in one bracket, so a single action can reach both paths:

- target: $.paths['/accounts/{id}','/transfers/{id}'].*.responses

The copy is gone, and for a short, stable list of paths, this is perfectly fine. But let’s see what happens when somebody misspells /transfers/{id} as /transfer/{id}. I applied both versions with SpecLynx CLI and --strict, which fails when an action’s target matches nothing.

The union selector:

$ npx @speclynx/cli overlay apply union.overlay.yaml openapi.yaml --strict --verbose
Overlay: union.overlay.yaml -> openapi.yaml
  [ok] update $.paths['/accounts/{id}','/transfer/{id}'].*.responses (2 matches)
  Overlay was successfully applied

One action per target:

$ npx @speclynx/cli overlay apply errors.overlay.yaml openapi.yaml --strict --verbose
Overlay: errors.overlay.yaml -> openapi.yaml
  [ok] update $.paths['/accounts/{id}'].*.responses (2 matches)
  [FAIL] noop $.paths['/transfer/{id}'].*.responses (0 matches)
         Action target "$.paths['/transfer/{id}'].*.responses" matched zero nodes (strict mode)

Error: Action target "$.paths['/transfer/{id}'].*.responses" matched zero nodes (strict mode)

The union still matched two nodes, so as far as strict mode is concerned, the action worked, and the missing 404 on transfers went completely unnoticed. This isn’t a bug: the target as a whole did match something (apidom#688 has the reasoning). A union selector removes the copy by merging targets, and merging targets is exactly what hides a typo.

A word on YAML anchors

If your overlay is written in YAML, you might reach for anchors and aliases (&notFound and *notFound) to reuse the update block. In a YAML-only workflow, this works: you maintain one copy, and the parser replaces every alias with a copy of the anchored value. But the reuse lives in the YAML syntax, not in the overlay, and that has consequences:

• JSON overlays can’t use it. JSON has no anchors.
• It doesn’t survive conversion. RFC 9512, which Overlay 1.2 refers to for how YAML maps to JSON, treats aliases as a serialization detail that can be discarded. Convert the overlay to JSON once, and the copies are back for good.
• The anchor lives inside an action. YAML requires the anchor to come before its aliases, so the shared block sits in whichever action uses it first. Delete or move that action, and every alias after it stops parsing.

A word on generating overlays

The last DIY option is to stop writing the overlay by hand: keep a list of targets and a template, and generate the overlay with a small script (jq, yq, or a few lines of JavaScript). This works with any overlay version, in JSON and YAML, and with one action per target.

The cost is that you now maintain two things instead of one: the generator and its output. Reviewers review a generated file, and somebody eventually edits the output by hand instead of the input. For a team that already generates its OpenAPI description, this can be fine. For everybody else, it’s a lot of machinery for avoiding a copy.

Overlay 1.2: reusable actions

Overlay 1.2 adds what the workarounds above were reaching for: a named, reusable action that every target references on its own. The shared change lives in components.actions, and every entry in actions only says where it goes:

overlay: 1.2.0
info:
  title: Add error responses
  version: 1.0.0
components:
  actions:
    notFound:
      description: The 404 response every single-resource operation returns.
      fields:
        update:
          '404':
            description: The resource does not exist.
            content:
              application/problem+json:
                schema:
                  $ref: '#/components/schemas/Problem'
actions:
  - $ref: '#/components/actions/notFound'
    target: $.paths['/accounts/{id}'].*.responses
  - $ref: '#/components/actions/notFound'
    target: $.paths['/transfers/{id}'].*.responses
    description: Transfers share the 404 of accounts.

Please take a moment here and look at the shape. If you’ve ever written an OpenAPI description, it will look familiar: components holds the reusable parts and $ref points to them, the same way schemas and responses work in OpenAPI itself.

Let’s apply it:

$ npx @speclynx/cli overlay apply errors.overlay.yaml openapi.yaml -o result.yaml --verbose
Overlay: errors.overlay.yaml -> openapi.yaml
  [ok] update $.paths['/accounts/{id}'].*.responses (2 matches)
  [ok] update $.paths['/transfers/{id}'].*.responses (1 matches)
  Overlay was successfully applied

The result is byte for byte identical to the result of the copy-pasted 1.1 overlay. This is how it differs from the input:

@@ -15,14 +15,32 @@
       responses:
         '200':
           description: One account.
+        '404':
+          description: The resource does not exist.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
     delete:
       operationId: deleteAccount
       responses:
         '204':
           description: Account deleted.
+        '404':
+          description: The resource does not exist.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
   /transfers/{id}:
     get:
       operationId: getTransfer
       responses:
         '200':
           description: One transfer.
+        '404':
+          description: The resource does not exist.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'

A few rules are worth knowing before you write your first reusable action:

• The target always comes from the reference. A reusable action must not contain a target inside its fields, and a reference must always have one. A reusable action that nobody references does nothing.
• Only the description can be overridden. A reference has three fixed fields: $ref, target, and description. If both define a description, the reference’s description wins. You can’t change the update per use; for a different change, define a second reusable action.
• References are local. $ref must point into #/components/actions/ of the same overlay file. Keys are JSON Pointer tokens, so a key like a/b is referenced as #/components/actions/a~1b.

Let’s put all the approaches side by side:

The one column where reusable actions lose today is one I didn’t put in the table: tool support. Overlay 1.2 is a month old, and not every overlay tool reads it yet.

The overlay that only works on your machine

There’s a second problem Overlay 1.2 fixes, and it’s a quieter one. An overlay can say which OpenAPI description it was written for, using extends. Overlay 1.0 and 1.1 allowed extends to be a relative reference like ../openapi.yaml, but they never said what it’s relative to. Relative to the overlay file? To the directory you run the tool from? Every tool had to decide on its own, so an overlay that worked from the repository root wasn’t guaranteed to work in CI, from a different directory or with a different tool.

Overlay 1.2 settles it: a relative extends is resolved against the overlay’s $self field if it has one, and against the location the overlay was loaded from if it doesn’t. Never against your working directory.

Without $self, the overlay file’s location is what counts:

overlay: 1.2.0
extends: ../openapi.yaml
info:
  title: Add error responses
  version: 1.0.0
# ...

$ npx @speclynx/cli overlay apply demo/overlays/extends.overlay.yaml --verbose
Overlay: extends.overlay.yaml -> (extends)
  [ok] update $.paths['/accounts/{id}'].*.responses (2 matches)
  [ok] update $.paths['/transfers/{id}'].*.responses (1 matches)
  Overlay was successfully applied

The target argument is omitted here, so the overlay is applied to its extends, and you get the same result from whichever directory you run it.

With $self, the overlay carries its own identity, wherever the file happens to be. The following overlay lives on my disk, but it says it belongs next to the sample description from the SpecLynx getting-started guide:

overlay: 1.2.0
$self: https://speclynx.com/assets/samples/getting-started/petstore.overlay.yaml
extends: openapi.yaml
info:
  title: Add a server
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: https://api.petstore.example.com

$ npx @speclynx/cli overlay apply petstore.overlay.yaml --verbose
Overlay: petstore.overlay.yaml -> (extends)
  [ok] update $ (1 matches)
  Overlay was successfully applied

openapi: 3.1.0
info:
  title: Petstore API
...

extends: openapi.yaml was resolved against $self to https://speclynx.com/assets/samples/getting-started/openapi.yaml, not to a file next to the overlay on my disk.

The specification goes one step further and treats extends as a name rather than an address:

URIs used in an Overlay document, including $self and extends, are identifiers, and not necessarily locators (URLs).

Overlay Specification 1.2.0

If an OpenAPI 3.2 description declares its own $self, tools are expected to match extends against it. An overlay written for https://apis.example.com/approved/petstore.yaml then still applies to a copy of that description served from a mirror. Appendix B of the specification walks through all the cases, and I highly recommend reading it.

Catching mistakes before CI applies them

New fields mean new ways to get things wrong: a $self with a fragment, a target left inside a reusable action, a reference to notfound instead of notFound, a reference without a target. All of these are mistakes a linter can catch before anything is applied. Here is an overlay with four of them:

overlay: 1.2.0
$self: https://example.com/overlays/errors.overlay.yaml#v1
info:
  title: Add error responses
  version: 1.0.0
components:
  actions:
    notFound:
      fields:
        target: $.paths.*.*.responses
        update:
          '404':
            description: The resource does not exist.
actions:
  - $ref: '#/components/actions/notfound'
    target: $.paths['/accounts/{id}'].*.responses
  - $ref: '#/components/actions/notFound'

$ npx @speclynx/cli validate broken.overlay.yaml
broken.overlay.yaml
  2:8-2:59     error  10010602              $self must not contain a fragment identifier
  10:9-10:15   error  10050201              target must not be defined in Reusable Action fields; it is supplied by the Reusable Action Reference Object
  15:11-15:42  error  321-31-1792587509947  local reference not found
  17:5-18:1    error  10060200              should always have a 'target'

✖ 4 problems (4 errors)

Whatever tool you use, run a validation step like this in CI before the step that applies your overlays. A broken reference is much cheaper to fix in a pull request than in a published description.

What Overlay 1.2 doesn’t solve

Reusable actions remove the copy, but not everything around it:

• You still list every target. RFC 9535 JSONPath can’t select keys by pattern, so there’s no single expression for “every path with an {id} in it”. Each target still needs its own reference. It’s just one line now instead of a whole block.
• Reuse ends at the file. A reusable action can’t be shared across overlay files. If five overlays need the same 404, each of them defines it.
• No per-use variations. Apart from the description, a reference can’t change what the action does. Two variations of a change are two reusable actions.

Trying it today

Overlay 1.2 support is still new across the ecosystem. On the SpecLynx side, since version 1.5, SpecLynx CLI applies, validates, and generates 1.2 overlays (overlay diff now generates 1.2 by default, and --overlay-version 1.1.0 targets tools that don’t read 1.2 yet). Since version 2.14 (the latest is 3.0), the Language Service provides linting, completion, and hover documentation for 1.2. Both are built on ApiDOM, which supports 1.2 since version 6.0 and which you can use directly if you apply overlays from your own code. The OpenAPI Toolkit for VS Code and the browser Editor don’t support 1.2 yet. All examples in this article were run with SpecLynx CLI 1.5.2, the latest version at the time of writing.

Closing words

Copy-pasted actions are the most common way overlays rot: they apply cleanly while their copies drift apart. Every workaround available before 1.2 trades something away: union selectors hide typos, anchors don’t survive JSON, and generators add code to maintain. If your tools support it, go for Overlay 1.2: move the shared change into components.actions, give every target its own reference, and apply your overlays with strict mode on. Sounds pretty easy, right?

Have you found another way to keep overlays free of copies, or a case where reusable actions don’t fit? I’d be happy to add it to this article. And if your Overlay 1.2 document doesn’t apply the way the specification says it should, please open an issue with an example. I’d highly appreciate it!

Further reading: Overlay Specification 1.2.0 · RFC 9535: JSONPath · One Overlay, three JSONPaths · Your overlay changed one field. Why does the diff touch half the file?

If you work design-first, that document isn’t build output. You wrote it by hand, and the formatting is part of the work: descriptions wrapped where they read well, Markdown lists that render in your docs, comments that explain why an endpoint looks the way it does. Design-first people tend to be proud of their OpenAPI documents, and rightly so. Adding a single field with an overlay shouldn’t undo any of that.

There’s a second, practical problem: nobody can review a diff that touches half the file. In practice, people either stop reading the overlay output, or they stop using overlays and go back to maintaining copies by hand. Both are bad outcomes, and both have the same root cause: the tool didn’t round-trip the document.

Below I explain why this happens, give you two tests to run on your own tool, and show how four overlay CLIs did on them.

What is round-tripping?

Let’s first define it:

Round-tripping is reading a document, changing it, and writing it back so that everything you didn’t change comes out exactly as it went in.

For an Overlay tool, I’d split this into two rules:

1. Everything the overlay doesn’t target is kept byte for byte. Comments, quoting, indentation, block scalars, anchors, flow collections, line breaks. If the overlay didn’t ask for it, the output shouldn’t change it.
2. Everything the overlay adds keeps the overlay’s own style. If the overlay author wrote summary: "Fetch one account" with double quotes, or x-audience: [public] as a flow sequence, that’s how it should land in the result.

With both rules in place, the diff of an overlay run contains only what the overlay did, and you can review it again.

Why YAML makes this hard

JSON gives you few ways to write a given value. YAML gives you many:

• The same string can be plain (no quotes), single-quoted ('…'), double-quoted ("…"), or a block that spans several lines: a literal block (|) keeps the line breaks, a folded block (>) joins lines with spaces.
• A block can carry small markers: a chomping indicator (-, +) controls the trailing line break, and an indentation indicator (|2-) fixes the indentation.
• A list can be indented lines starting with - (a block sequence), or written inline as [a, b] (a flow sequence).
• A node can be named with an anchor (&account) and reused elsewhere with an alias (*account).
• And comments aren’t part of the data at all.

Most tools parse YAML into ordinary data (objects, arrays, strings) and throw all of that away. { title: "The user's accounts API" } doesn’t remember that it was written as 'The user''s accounts API'. When the tool serializes the value back, it picks its own style, and the document changes even where nothing was changed.

Sometimes it’s worse than style: the parser reads the value wrong. Here are three YAML edge cases where that happens:

• Escaped quotes. Inside a single-quoted string, an apostrophe is written twice: 'The user''s API' means The user's API. A parser that doesn’t turn '' back into ' stores The user''s API. When the serializer writes it out, it escapes both quotes again, giving 'The user''''s API'.
• Block indicators in either order. |2- and |-2 mean the same thing: content indented 2 spaces deeper than its parent, final line break and any trailing empty lines removed. A parser that only recognizes one order gets the indentation wrong, and the text comes back shifted.
• More-indented lines in folded blocks. In a > block, ordinary lines are joined into one paragraph, but lines indented further than the rest are kept exactly as written. That is how Markdown bullet lists and tables survive inside a description. A parser that joins those lines too merges the list into the surrounding prose.

In all three cases the damage happens while reading. Switching the output to JSON doesn’t help: the value is already wrong.

A small document that exercises all of it

Here is an OpenAPI document I’ll use for the rest of the article. It’s small on purpose, but every construct in it has a real bug report behind it:

openapi: 3.1.0
info:
  title: 'The user''s accounts API'
  version: 1.0.0
paths:
  # Read-only for now; writes land in v2.
  /accounts/{id}:
    get:
      operationId: getAccount
      tags: [accounts, read]
      responses:
        '200':
          description: >-
            Account details. If the response contains unmasked identifiers
            this is sensitive data which should only be exchanged if encrypted.
              * Routing number: identifies the institution;
              * Account number: identifies the customer account.
          content:
            application/json:
              schema: &account
                type: object
        '404':
          description: |2-

            No account with this id.
  /me:
    get:
      operationId: getMe
      responses:
        '200':
          description: The signed-in user's account.
          content:
            application/json:
              schema: *account

What you get when you build it yourself

If you’re tempted to write your own overlay script, the first step is a YAML library. This is what the round trip looks like with the two most popular ones in JavaScript, js-yaml and yaml. I parsed the document above and wrote it back without changing anything:

A value-level load and dump has nowhere to keep the style. The Document API keeps comments, quotes, and flow collections, but writes them back in its own layout: block scalars are re-folded and flow brackets get padding. The CST API (concrete syntax tree: the parser’s token-by-token view of the file) really round-trips: it keeps every token. CST.setScalarValue() changes a value in place and keeps its type (quoted stays quoted, folded stays folded), although block scalar headers and line breaks are regenerated. If all you need is to change existing single-line values, that is a great foundation.

An overlay engine needs more than that. JSONPath targets have to be mapped onto a tree of tokens. An update merges whole objects into the document, so you build new nodes by hand, indent them to fit, and keep the overlay’s style. A remove has to take the right comments and blank lines with it. The first version of such a script is easy. Keeping it correct on a real-world description tens of thousands of lines long is where the time goes.

How to check your overlay tool

You don’t have to take any tool’s word for it. Two quick tests tell you most of what you need to know.

The one-line test

Apply an overlay that adds a single extension field:

overlay: 1.0.0
info:
  title: Round-trip check
  version: 1.0.0
actions:
  - target: $.info
    update:
      x-round-trip-check: true

Apply it to your real document and diff the result against the input. The diff should be exactly one added line. Every other line that shows up is a line your tool will rewrite on every run, whatever your overlay does.

Why not an empty update: {}? A tool can notice there’s nothing to do and return the input untouched, so the empty diff proves nothing. A real change, however small, forces the full round trip.

The style test

Apply an overlay that adds values written in specific styles. Point the target at any operation in your own document; here it’s the sample’s /accounts/{id}:

overlay: 1.0.0
info:
  title: Add public description
  version: 1.0.0
actions:
  - target: $.paths['/accounts/{id}'].get
    update:
      summary: "Fetch one account"
      description: |
        Returns a single account.

        Requires the `accounts:read` scope.
      x-audience: [public]

The diff should contain exactly these lines, written the way they are written here: the double quotes, the literal block, the flow sequence.

When you read your diffs, look first at the constructs that break most often:

• escaped quotes ('it''s')
• comments
• Markdown lists and tables in > blocks
• block indicators (|2-, |+, >-)
• anchors and aliases
• flow collections ([a, b])
• Windows line breaks (CRLF)

How four overlay CLIs compare

I ran the one-line test and the style test on the sample document above, through four overlay CLIs at their latest versions on 18 October 2026: Speakeasy CLI 1.802.0, Bump.sh CLI 2.11.0, openapi-format 1.34.0, and SpecLynx CLI 1.5.1. Every tool ran with its default options. Full disclosure: I maintain SpecLynx CLI.

All values unchanged means that parsing the result gives exactly the input data plus the overlay’s changes; only the formatting may differ.

The commands I ran:

# Speakeasy CLI
$ speakeasy overlay apply -s openapi.yaml -o overlay.yaml --out result.yaml

# Bump.sh CLI
$ bump overlay openapi.yaml overlay.yaml -o result.yaml

# openapi-format
$ openapi-format openapi.yaml --overlayFile overlay.yaml -o result.yaml

# SpecLynx CLI
$ speclynx overlay apply overlay.yaml openapi.yaml -o result.yaml

Bump.sh CLI and openapi-format keep every value, but they rewrite most of the file, much like the js-yaml row above. Quotes, flow collections, and the anchor are gone. Bump.sh CLI rewrites both block scalars; openapi-format keeps the >- indicator but re-wraps its text and loses |2-. With its default options, openapi-format also drops the comment and reorders keys. Speakeasy CLI and Bump.sh CLI have no output formatting options, but openapi-format does, so I tried them all. Its best combination, --no-sort --keepComments --no-bundle, keeps the comment and key order and gets the one-line test down to 18 lines. The quotes, flow sequence, block scalars, and the overlay’s own style still change, and the anchor is kept but renamed to &a1.

Speakeasy CLI keeps nearly all of the style, which is impressive. But it re-wraps the folded description and adds an empty line to it, and it drops the empty first line of the |2- block. Both of those change the value. That’s the worst kind of change, because a reviewer reads it as formatting noise.

If I misused any of these tools, tell me and I’ll update the table.

How SpecLynx CLI got there

Until recently, SpecLynx CLI failed most of these checks too. Here is the style test applied to the sample document with SpecLynx CLI 1.5.1:

$ npx @speclynx/cli overlay apply overlay.yaml openapi.yaml -o result.yaml

The input is on the left and the result on the right, with changed lines shaded.

The only shaded lines are the ones the overlay added. Everything the overlay didn’t target is byte for byte identical, and everything it added is written the way the overlay author wrote it.

What changed under the hood

SpecLynx CLI applies overlays with SpecLynx ApiDOM, an open source parser for API descriptions. The fixes landed in ApiDOM 6.1.0 and fall into three groups:

The parser computes the right value. The three edge cases above are fixed, along with nearly twenty related ones.

Style preservation writes back what was written. Block scalars, flow scalars, anchors, aliases, and CRLF line breaks come back exactly as they were in the source.

Style survives the overlay itself. Values added by an overlay keep their YAML style, and objects and arrays merged by an update action keep theirs.

If you build tools on ApiDOM, all of this is opt-in (style: true when parsing, preserveStyle: true when writing YAML); see the Parsing guide.

What isn’t perfect yet

One edge I found while writing this: extra spaces before a comment get collapsed, so title: 'API' # note comes back as title: 'API' # note. It doesn’t change a value, but it shows up in a diff, and it’s tracked in apidom#682.

Thank you, Clyde Cutting

None of this would exist without Clyde Cutting (@cuttingclyde), who reported three issues against SpecLynx CLI between August and October:

• #138 showed Financial Data Exchange (FDX) descriptions with Markdown lists and tables being re-wrapped. It looked like a formatting preference and turned out to be a parser bug.
• #174 pointed at |2- blocks in the 75,000-line OpenAPI description of Plaid, a financial data API, with a “bonus” overlay proving that values coming from the overlay broke too. Its CRLF attachments became a test case of their own.
• #177 covered almost every quoting variant in one small file, which narrowed the bug down immediately.

Each report came with real files and a clear expected result. While fixing them, I kept finding related problems and fixed those in ApiDOM too. Thank you, Clyde. Issue reports like these are the most valuable contribution an open source project can get.

Closing words

An overlay is a promise: change these nodes and leave everything else alone. A tool that doesn’t leave the rest alone makes you choose between overlays and readable diffs. Whatever tool you use, run the one-line test on your own documents. It takes a minute and tells you whether your overlay diffs can be trusted.

If you want to try SpecLynx CLI, run the latest version:

$ npx @speclynx/cli@latest overlay apply overlay.yaml openapi.yaml

If anything outside your overlay’s targets changes, please open an issue with an example. That’s exactly how this release happened.

Further reading: Overlay Specification 1.2.0 · YAML 1.2.2 specification · SpecLynx CLI 1.5.1 release notes · ApiDOM 6.1.0 release notes · ApiDOM parsing guide

Error: Invalid JSONPath expression:
  "$.components.schemas.*[?(!@.x-fdx-csdf-account-categories && !@.x-fdx-csdf-technical)]".
  Syntax error at position 29, expected "[", "*", "_", "0", "-", ":", "!", "(", "@", "$", "-0", ".", "..", "&&", "||"

Nothing about the overlays changed. Nothing about the API descriptions changed. What changed is which JSONPath the tool on the other end speaks. That is the subject of this post: when an Overlay implementation is handed an expression written for a different JSONPath dialect, should it try to understand it anyway, or refuse?

Our answer is refuse, and be helpful about it. A canonical implementation should be strict about what it consumes. The rest of this post is the reasoning: what the dialects are, what the spec says, what other tools do, the honest case for leniency, and why strictness still wins.

There is no single JSONPath (until recently)

JSONPath started as a 2007 blog post by Stefan Gössner. It described a syntax, shipped a JavaScript implementation with eval() inside, and left plenty unspecified. Every language ecosystem then grew its own interpretation:

• Goessner-style libraries (jsonpath on npm, most Python and Java ports) are the classic. Filter expressions are small scripts handed to the host language, so anything the host can evaluate, including its regex syntax and its comparison operators, “works”.

• JSONPath Plus is a popular fork that added selectors the original never had: a parent selector, a property-name selector, and a handful of @-prefixed helpers and type selectors. Stoplight’s Spectral runs on this dialect: its own Nimma engine supports most JSONPath Plus additions, it falls back to jsonpath-plus for compatibility, and its docs say it is not yet aligned with RFC 9535. A lot of developers have muscle memory from writing rulesets against exactly this syntax.

• RFC 9535 is the IETF standard, published February 2024. Names in brackets must be quoted, names after a dot are limited to letters, digits and underscores, filters are a real expression grammar rather than host-language code, and regexes and lengths come from a fixed set of functions. For a compliant implementation in JavaScript, see @swaggerexpert/jsonpath.

For everyday paths (a named operation, all schemas under components, parameters filtered by in) all three agree. Then the edges bite:

Goessner and Plus columns checked against jsonpath 1.1.1 and jsonpath-plus 10.x; the RFC 9535 column against @swaggerexpert/jsonpath.

The first row is the shape of the banking overlays from the opening. Position 29 of the original expression is the hyphen in x-fdx-csdf-account-categories: a member name that RFC 9535’s dot-notation grammar doesn’t allow, and that a lenient parser happily reads through. Same file, two meanings of “valid”.

What the Overlay spec actually says

Overlay 1.0.0 (October 2024) defined target as “a JSONPath expression selecting nodes in the target document” and cited RFC 9535 as a normative reference. The wording was soft, but the intent was clear, and implementers generally read it the same way: RFC 9535 was the JSONPath the spec meant.

Overlay 1.1.0 (January 2026) closed the gap with a dedicated section, RFC9535 Compliance:

A tool or library MUST fully implement RFC9535 when parsing and expanding JSONPath query expressions to be compliant with the Overlay specification.

Interoperable Overlay Documents MUST use RFC9535 JSONPath query expressions and MUST NOT use tool-specific JSONPath extensions.

So the spec answers half the question: a compliant implementation must speak RFC 9535, and a portable overlay must not rely on anything else. What it doesn’t say is whether an implementation may also accept other dialects as a courtesy.

What the ecosystem actually does

A quick survey of open-source Overlay tooling, as of this writing:

• openapi-overlays-js (Lorna Mitchell’s reference-style implementation) depends on the jsonpath package: the Goessner dialect.
• Bump.sh CLI runs its overlay support on jsonpathly, which since version 3 is an RFC 9535 implementation.
• Speakeasy picks the dialect by Overlay version: a 1.0.0 document is evaluated with its legacy, Goessner-inspired yaml-jsonpath engine by default (with a warning on expressions that aren’t valid RFC 9535, and an opt-in x-speakeasy-jsonpath: rfc9535 extension), while a 1.1.0 document gets RFC 9535 by default with an opt-out back to legacy. It also ships an upgrade helper that moves an overlay from 1.0.0 to 1.1.0.
• SpecLynx CLI and @speclynx/apidom-overlay evaluate targets with @speclynx/apidom-json-path, which is RFC 9535-only for every Overlay version.

So the picture isn’t simply “Goessner tools vs. RFC tools”. The same target string can be evaluated by a Goessner engine, an RFC engine, or either one depending on the overlay: version field at the top of the file, and the spec says only one of those behaviours is compliant. The banking overlays from the opening were Overlay 1.0.0 documents, so the first CLI read them with its legacy engine, where hyphenated dot-names are fine. The second CLI read them as RFC 9535, where they aren’t.

The case for being lenient: a fair hearing

It’s a real case, so let’s make it honestly.

Existing overlays. People wrote overlays before 1.1.0 made the rule explicit, against whatever their tool accepted. Rejecting those files is friction on day one: five failing overlays and a bug report, in the story above.

Postel’s law. “Be conservative in what you send, liberal in what you accept” is the oldest instinct in protocol design. Accepting Goessner and Plus syntax alongside RFC 9535 would mean more overlays Just Work.

Adoption. Overlays are still early. A tool that says “no” to a working file is a tool people route around.

The strongest form of this argument is the one Speakeasy actually built: don’t guess, version-gate. Treat the overlay: 1.0.0 header as permission to use the old engine, warn loudly when an expression wouldn’t survive RFC 9535, make the standard the default the moment the author writes 1.1.0, and give them a one-command upgrade. That is leniency with a migration path designed in, and it’s a reasonable way to carry an existing user base across the line.

Why strict wins

And here’s why, for all that, the lenient case loses for a canonical implementation, the one meant to define what “correct” means.

An overlay is a portable artifact, not a script. Its whole value is that the same file can be applied by your docs tool, your SDK generator, and your CI gate and produce the same result. Every dialect an implementation accepts, even deliberately and with warnings, is a file that will break the moment it meets an implementation that doesn’t. Leniency doesn’t remove the interoperability problem; it moves it downstream, to someone who didn’t write the overlay and can’t see why it fails. That’s exactly how five overlays that “worked” arrived at a tool that couldn’t read them: the version gate kept them working in one place and tool-specific everywhere else.

Postel’s law has a known failure mode. The IETF itself revisited the robustness principle in RFC 9413, Maintaining Robust Protocols (2023): tolerating deviations lets them harden into de-facto requirements, and the ecosystem ossifies around the most lenient implementation instead of the standard. JSONPath’s two decades of dialect drift are that failure mode. RFC 9535 exists to end it, and an Overlay implementation that re-admits the dialects undoes the work.

Ambiguity is worse than an error. Some expressions parse in more than one dialect with different meanings. A lenient implementation has to guess which one the author meant. Guessing wrong doesn’t error; it edits the wrong node. For a tool whose job is to modify API contracts, a loud parse error is the kinder outcome.

“Strict input” still leaves room to help. Strictness is about what the implementation applies, not about how it treats the person. An error that names the offending expression and the exact position, plus a hint toward the RFC form, turns a rejection into a minutes-long fix. A linter or converter for legacy overlays can be a separate, honest tool; it doesn’t have to live inside apply.

Where SpecLynx landed

SpecLynx is RFC 9535 only, because the Overlay specification requires it and because we think that’s the right answer for a canonical implementation: @speclynx/apidom-json-path is fully RFC 9535 compliant, and SpecLynx CLI evaluates every target with it, whatever the overlay’s version field says:

npx @speclynx/cli overlay apply overlay.yaml openapi.yaml

An expression that isn’t valid RFC 9535 is rejected with a parse error that points at the offending position and lists what the grammar would have accepted there (the message at the top of this post is SpecLynx’s) rather than guessed at. The other common way an overlay silently does nothing is a target that matches no nodes at all; --strict turns that into a failure too:

npx @speclynx/cli overlay apply overlay.yaml openapi.yaml --strict

The opening story is real: speclynx-cli#127. The fix on the overlay side was mechanical (bracket the hyphenated names) and the author had all five working the same day.

Migrating an existing overlay

If you maintain overlays written against a Goessner or JSONPath Plus tool, the migration usually is that mechanical: quote bracketed names and anything with a hyphen, replace host-language regexes with match()/search(), and rewrite parent/property selectors as explicit paths. The table above covers most of what we’ve seen. The @swaggerexpert/jsonpath validator and jsonpath.com (in its RFC 9535 mode; it also offers a JSONPath Plus mode, which is the whole point of this post) will tell you whether an expression is valid RFC 9535 before you run anything.

For a larger batch, the prompt below does the conversion with any AI assistant, and is the one we handed over in that issue:

You are a JSONPath migration assistant. Convert the JSONPath expression below so that it is valid under RFC 9535 (the standard implemented by @swaggerexpert/jsonpath), while preserving its exact meaning.

Apply these rules:
1. Never write a dot directly before a bracket. `a.[...]` must become `a[...]`.
2. Dot-notation member names may only contain letters, digits, `_` and non-ASCII characters. Any name containing a hyphen, space, or other punctuation must be written in bracket notation with a quoted string, e.g. `@.x-foo-bar` -> `@['x-foo-bar']`, `$.some key` -> `$['some key']`.
3. Filters use `?` inside brackets: `[?<expr>]`. Parentheses around the whole expression are optional (`[?(expr)]` and `[?expr]` are both fine); keep them if present.
4. `!@...` / `@...` are existence tests (key present or not), not truthiness tests. Keep them as existence tests unless the original clearly compares values.
5. Comparisons must be `==`, `!=`, `<`, `<=`, `>`, `>=` between singular queries or literals; use `&&`, `||`, `!` for logic. Replace non-standard operators (`=~`, `in`, `nin`, `size`, `empty`, `contains`) with `match()`, `search()`, `length()`, `value()`, `count()` or equivalent comparisons, and say so explicitly.
6. Replace non-standard shorthands: `$..*` is fine, but script filters `[(@.length-1)]` become `[-1]`, `@.length` becomes `length(@)`, and `$.a.b.[*]` becomes `$.a.b[*]`.
7. Do not change what the expression selects. If a fully equivalent RFC 9535 form does not exist, say so and give the closest alternative with the difference explained.

Output:
- The migrated expression on its own line in a code block.
- A short bullet list of each change and why.
- If possible, a second, shorter equivalent form.

Expression to migrate:
<PASTE EXPRESSION HERE>

The short version

• Overlay target is JSONPath, and since Overlay 1.1.0 that means RFC 9535, for tools and for overlays that want to be portable.
• Dialects agree on the easy paths and diverge on filters, regexes, hyphenated names, and selector extensions, exactly where copy-pasted expressions live.
• A canonical implementation should be strict about what it consumes and generous about how it says no: clear errors and migration help, not silent dialect guessing.

Further reading: Overlay Specification 1.1.0 · RFC 9535 · RFC 9413 · SpecLynx CLI · @speclynx/apidom-overlay

Think of it as Babel.js, but for API specifications.

ApiDOM is the semantic core behind SpecLynx. It powers every layer of the stack: the Language Service, VS Code extension, browser editor, and CLI.

It parses OpenAPI, AsyncAPI, JSON Schema, Arazzo, and Overlay specs into a unified semantic tree you can traverse, transform, and serialize back out.

The goal is simple:

Let developers work with API specs programmatically without losing the structure, style, and intent of the original file.

Because that part matters.

You should be able to modify a spec and get back something that still looks like your file, not a machine-generated rewrite.

What you can build on it

SpecLynx ApiDOM is Apache-2.0 licensed, and you can use it to build your own:

• ✅ Linters
• ✅ Transforms
• ✅ Code generators
• ✅ Migration tools
• ✅ Spec-aware automation

What we did to make it ready

• Tree-sitter based parsing: so tooling stays useful even while specs are incomplete
• A semantic data model: not generic objects, but one that understands OpenAPI Operations and Schema Objects
• Lossless roundtrip: comments, indentation, and key ordering are preserved across transformations
• Performance and memory efficiency for large specs

Why open source it

We open-sourced ApiDOM to build trust. Every line of source code is now auditable and viewable, which also makes it usable in regulated environments where that’s not a nice-to-have but a requirement.

Try it

npm install @speclynx/apidom-reference

Parse an API specification and access its data model right away:

import { parse } from '@speclynx/apidom-reference';
import { toValue } from '@speclynx/apidom-core';

const result = await parse('/path/to/openapi.json');

toValue(result.api.info.title);   // document title
toValue(result.api.info.version); // document version

Get started

• GitHub: speclynx/apidom
• Documentation: speclynx.com/apidom

If you’ve ever had to parse, rewrite, or generate API specs: what broke first? Tell us in the discussions 👇