Overlays: Our purpose is for understanding change

[smikulcik]

On the overlays SIG meeting today, we had an interesting conversation w.r.t. the “add” operator (#132 (reply in thread)).

Notes from today:

• Existing operators (update, remove, copy) cannot fail, they can do a no-op, but they don’t have a “failure mode”. If we were to add some protections for “add”, it would be a novel inclusion of a failure modality where it has not been previously
• Overlays characterized as “transforms” rather than “diffs”
  • Similar to XSLT where a stylesheet “transforms” XML into HTML. It doesn’t fail, but the output may not be “useful”.
  • I also see this as similar to how jq works. Given an input JSON document, a jq filter can produce a variety of output formats. Though, jq can fail at times if the input document doesn’t match up with filter expectations.

I think our purpose statement is short-sighted: Section 2. Introduction

The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions

If the goal were to describe repeatable transformations, I’d say simple scripts would be better at describing and applying a change in a repeatable fashion. To me, the real value of overlays is in it’s ability to communicate a change to an OAD. Having a limited-vocabulary change descriptor helps make it easier to understand.

function RemoveInternal(oad){
  for(const pathItem of oad.paths){
    for(const method in pathItem){
      if (pathItem[method]['x-internal'] === true){
        delete pathItem[method]
      }
    }
  }
  return oad
}

overlay: 1.2.0
info:
  title: RemoveInternal
actions:
  - target: $.paths.*[?(@.x-internal == true)]
    remove: true

As far as repeatable transformations go, the script is extensible, deterministic, testable, well supported, composable, and many developers quickly understand what the logic does. To understand what the overlay does, the reader must understand the structure of OpenAPI documents, this Overlay yaml format, JSONPath semantics, and the specifics on the base OAD on which this overlay is applied.

I point this example out not to belittle the utility of the overlay document. Rather, I wish to reposition the overlay as a change set with the purpose of fostering a clearer understanding of API changes.

For a human to understand OpenAPI semantics, sure, they must appreciate the structure of the base OpenAPI document. When we start comparing specs to each other, now we have 2 documents with many difference formats to choose from: git-diffs, JSON Patch, JSON Merge-Patch, etc. To make sense of what and OpenAPI document change actually means, it takes quite some experience in understanding how $ref works, JSON Schemas, URI ecosystems, etc.

We have a real need in our community to teach people how to explain API changes.

A good change format has at least these characteristics

1. Complete - all types of changes are expressible
2. Well-defined - application of the change is repeatable without ambiguity of interpretation
3. Nuanced - Invites change authors to bring nuance and clarity into the change process
4. Understandable - Consumers of the change document must be able to underestand the what, and the why of the scope of change.
5. Concise - Complex patterns should be easy to express with minimal bytes. Verbose change formats are difficult to grok.

Frankly, the existing Overlay document meets many of these characteristics as it is.

1. Complete - yes, comparing 2 documents, we can deterministically describe a repeatable change
2. Well-defined - yes, overlays provides unambiguous semantics
3. Nuanced - Actions are flexible enough to encourage authors to describe their change with description properties and schema extensions
4. Understandable - As a plain text format, both humans and agents can read the document and understand the full scope of the change
5. Concise - Overlays provides several "quality of life" options like JSONPath, copy, etc. These drastically cut down on the number of lines to understand to enable complexity to be expressed concisely.

If overlays are to be limited to transformers focused on repeatability, they will only be useful as far as a lightweight automation DSL.

We still have the need in the community to express API change-sets in a way that fosters broader change understanding. I want to empower tooling vendors to automate the explanation of an API change across modalities to strengthen the foundational relationships between service providers and consumers. All of that starts at the interface description layer (OpenAPI) and how we evolve that relationship over time (Change-sets -- hopefully Overlays).

Related conversation

• Overlays Meeting (2025-11-18) #211 (comment) - first hint at a potential mission/purpose misalignemnt
• Overlays Meeting (2026-10-06) #397 Today's meeting notes

[SensibleWood]

We still have the need in the community to express API change-sets in a way that fosters broader change understanding. I want to empower tooling vendors to automate the explanation of an API change across modalities to strengthen the foundational relationships between service providers and consumers. All of that starts at the interface description layer (OpenAPI) and how we evolve that relationship over time (Change-sets -- hopefully Overlays).

@smikulcik are you able to add a concrete example to this discussion of how Overlay can be improved in the "change set" guise described above? I understand the discussion above well enough, but without a concrete example of a "what if we did this" feature, its hard to understand how Overlay can morph from transformation layer to change set.

[smikulcik]

Sure, this conversation is stemming from the consideration of the "add" operator.

base document

components:
  schemas:
    Pet:
      properties:
        name:
          type: string
          description: "The name of the pet"

This overlay is risky since it may be an addition, or it may be an update.

overlay: 1.2.0
info:
  title: 
actions:
- target: '$.components.schemas.Pet'
  update:
    properties:
      name:
        type: string
        description: "The updated name of the pet" # <-- This is a "REPLACE" but it's hard to tell from just the overlay.

This overlay is safer since I know by looking at it, the change described is strictly adding the "name" property as that one doesn't exist. This overlay would fail to apply on the base document since Pet already has a name property.

overlay: 1.2.0
info:
  title: 
actions:
- target: '$.components.schemas.Pet.properties.name'
  add: # <-- "add" actions may only apply if the target selects 0 items
    type: string
    description: "The name of the pet"

[SensibleWood]

@smikulcik reflecting on what @kinlane said here and my own similar, but different use cases for Overlay. Where I see this:

description: "The updated name of the pet" # <-- This is a "REPLACE" but it's hard to tell from just the overlay.

I honestly say here in many cases "I don't care" because my version of the truth is the one I want to Overlay on an existing specification. In my cases an update I write is aimed at improving quality and reducing ambiguity. I don't care if it exists - I just want it - it makes the API I am publishing better in my pipeline.

A pipeline view of API descriptions will take a closed world view here, based on what the tooling does and the result of the JSONPath expression (true or false). If the result is true, apply the change. If the result is false, do nothing. Tooling can take care of how that is reported.

Talking specifics of a new feature in Overlay I'd say there is also a case for an "upsert" action, similar to that operation in the database world, where its an insert or an overwrite based on false or true respectively. I want that thing, where I want it, and I don't care if something comes before it. My version of the truth is the truth, come what may. The tool reports what action is take, because it sees the result of the JSONPath expression.

Just a side note. Any add or upsert action of course needs to cognisant of what exists i.e. where does a tool start building the parent path? Semantically a JSONPath should resolve to something that is described by OpenAPI so a path like $.random.factor is out of scope.

[kinlane]

Thanks for writing this up, @smikulcik. I think you're pointing at something real, and I want to add a perspective from the other side of the table, since my use of Overlays is almost entirely against OpenAPI documents I don't own.

I maintain a catalog of public APIs, and Overlays are how I add to provider contracts without forking them. As of today that's 28,652 Overlay documents across 3,776 providers. 185,707 of their actions are update and 91 are remove. 16,049 of them do one thing: attach conversational phrasing (the questions people ask about each operation) as an x- extension, so an agent can find the right one. Every one of them has to survive the provider regenerating their spec next week. That's the property I'd least want to lose.

I think the purpose of the spec is already in the name: Over-lays. You lay something over a document that stays as it is underneath. So I'd put it a third way: an overlay is a layer, not a diff and not a script. Your example shows why it beats the script. The value isn't only that it's repeatable; it's that the intent sits next to the document in a vocabulary anyone can review, without touching the source. And it's why an overlay isn't a diff: one target like $.paths..responses[?(!@['401'])] means "every operation that doesn't already describe a 401". That's a statement about the shape of the API, not a list of lines that changed between two snapshots. A diff can only describe what was different once. An overlay describes what should be true of whatever the provider publishes next. I agree that communicating change is the bigger prize. I just think that comes from intent riding along with a repeatable edit. description on every action is where the "why" lives, and an overlay without descriptions is a diff with no commit message. I don't think it needs a new failure mode to get there.

On add specifically, I think there are two different operators hiding in this thread, and it would help to name them apart:

1. Add-if-absent. Apply only when the target selects nothing, and quietly do nothing otherwise. That's the document-wide defaults @handrews described in Conditional updates #132, and the "add missing error responses without overwriting" case @lornajane opened it with. It keeps the property your own notes point out, that existing actions can no-op but never fail, so an overlay stays safe to re-run.
2. Assert-absent. Fail when the target already exists. That's a useful signal when you're reviewing a change. But the moment the upstream catches up and adds the thing you were adding, every pipeline that re-applies the overlay breaks. That's the brownfield case my whole catalog lives in. A gateway strips operations; my overlay puts them back; the provider fixes their export; my overlay should become a no-op, not an error.

I'd support (1) in the document, with the semantics that make it hold. I'd treat (2) as what @baywet called "the behaviour of the tool": a strict or report mode where the tool tells you an add found its target already present, without the document itself deciding to fail. Your safety argument is fully served by a tool that says "this action was a no-op because name already exists". That's arguably better change communication than an error, because it tells you what changed upstream.

On the purpose statement, I wouldn't rewrite it, either toward "change sets" or anything else. OpenAPI got where it is by solving problems nobody listed at the start, and I suspect Overlays will too. What I'd find more useful than a new definition is naming the things Overlays will never try to do — no string interpolation, no logic, no new formats, nothing a vendor couldn't implement in an afternoon — and treating everything inside that line as fair game. That bounds it without nailing it down.

Where I fully agree with you is that the community needs a way to describe API change. I just don't think Overlays should be bent into that shape. Change deserves its own specification. I'd sign on today to an OAI SIG for something like OverDiffs, or OverChange: a format for describing what changed between two OpenAPI descriptions, and why. I'd support it in my own APIs. APIs.io already compares providers side by side and reports what changed across the catalog since a given date, and a standard change format is exactly what those responses should return. Your five characteristics of a good change format would be a strong start on a charter for it: complete, well-defined, nuanced, understandable, concise.

In the meantime, those same five make great authoring guidance for Overlays. I'd love to see them on the learn site, with worked examples of overlays whose descriptions explain the change. That gets people writing better overlays now without asking anything new of the tools. And the tools are the reason this works at all. Overlays are small enough that nearly every OpenAPI tool supports them, which is why I can rely on them across thousands of providers. Every new failure mode is a cost every one of those implementations has to pay, and I'd rather keep the thing that's everywhere.

Happy to share real overlays from the catalog as test cases for either version of add, especially the brownfield ones where re-application is the whole point.