Revisit: should Overlays declare their target document format? (follow-up to #268)

[bielu]

Revisit: should Overlays declare their target document format? (follow-up to #268)

Why I am reopening this

#268 asked whether Overlays are intended for Arazzo, and was closed as NOT_PLANNED on 2026-02-10 with this reasoning:

Although this might technically be possible today this is not a "core function" of this specification, which is intended for OpenAPI descriptions. [...] The intent in the future might be to have selection mechanisms that are "type based" (visitor pattern), and opening overlays to other document types would generally go against such an improvement.

I am not asking the TDC to reverse that on the same evidence. #268 was a one-line question with no supporting argument, and the answer was reasonable given what was in front of it. I would like to put two things on the table that were not raised at the time — one about Arazzo, one about a failure mode — and to respond directly to the visitor-pattern objection, which I think is the strongest point in that thread and also the one most likely to be backwards.

1. Arazzo is already multi-format, and OAI already published the exact value set

This is the argument I most want a view on.

The released Arazzo 1.1.0 specification defines the Source Description Object's type field as:

The type of source description. Possible values are "openapi" or "asyncapi" or "arazzo".

That is not incidental. Arazzo has normative AsyncAPI-specific behavior — correlationId is documented as "Only applicable to asyncapi steps with action receive" — and its reference-resolution rules explicitly describe resolving "an OpenAPI or AsyncAPI description via a Source Description url field".

So within the OAI family, the position that a description-manipulating specification should be OpenAPI-only is already not the house style. Arazzo, the newer specification, is explicitly multi-format, and it settled on precisely the three-value set {openapi, asyncapi, arazzo}.

Two consequences:

• The cross-org concern is already spent. Naming AsyncAPI normatively in an OAI specification is not a new commitment for the Initiative to weigh — Arazzo made it, in a released version.
• Overlay would not be inventing a registry. It can adopt Arazzo's value set verbatim. Two OAI specifications describing the same three formats with the same three tokens seems strictly better than one of them declining to name them at all.

It seems odd for Overlay to be the specification that cannot be applied to an Arazzo document, when Arazzo itself is comfortable pointing at all three formats.

2. Wrong-format application fails silently, and the format has no way to catch it

Applying an Overlay to the wrong kind of document produces no error today. Since a target that selects zero nodes is defined to succeed without changing the document:

# written against an AsyncAPI document
overlay: 1.2.0
info:
  title: Mark all channels as internal
  version: 1.0.0
actions:
  - target: $.channels.*
    update:
      x-internal: true

Run that against an OpenAPI Description and every action selects nothing, every action succeeds, the tool exits 0, and the user believes their document was transformed. Nothing in the Overlay format lets a tool distinguish "this Overlay did not apply here" from "this Overlay had nothing to do".

This is worth addressing whatever the TDC decides about scope. Even a strictly OpenAPI-only Overlay ecosystem has this problem the moment anyone writes an Overlay against a document that is not an OpenAPI Description — which, per #268's own "might technically be possible today", they already can and do.

3. On the visitor-pattern objection

The concern in #268 was that type-based selection is a likely future direction, and opening Overlay to other document types would work against it.

I would argue the opposite: a type-based selector has to know which type model to apply before it can resolve, say, a selector for Operation Objects. In an OpenAPI-only world that knowledge is implicit — and being implicit, it is also unstated and unvalidated. A visitor is easier to build over an Overlay that declares the type model it was written against than over one where the tool has to sniff the target document first and hope.

Put differently: type-based selection needs a type model per format. Declaring the format is a prerequisite for that work, not an obstacle to it. If Overlay later grows type-aware selectors and stays OpenAPI-only, the declared format is simply always openapi and nothing is lost.

What I am actually proposing

Deliberately smaller than "Overlays for any JSON document" — that framing was rejected in #268 and I am not re-raising it.

A. Editorial. Define a target document term and state which formats the specification recognizes, rather than leaving the OpenAPI coupling implicit in the Abstract, the Introduction, the Format section, and a heading called Comments in OpenAPI Descriptions.

B. Normative. One optional field on the Overlay Object:

overlay: 1.2.0
info:
  title: Mark all channels as internal
  version: 1.0.0
targetFormat: asyncapi
actions:
  - target: $.channels.*
    update:
      x-internal: true

• Optional — omitted means no assertion, so every existing Overlay is unaffected and every existing tool stays conformant.
• Values openapi / asyncapi / arazzo, matching Arazzo's Source Description type exactly; other values SHOULD be absolute URIs so private formats cannot collide with future reserved ones.
• Independent of extends — extends names a document, targetFormat names a format.
• On mismatch, where tooling can determine the target's format (usually from the root openapi / asyncapi / arazzo field), it SHOULD report an error and SHOULD NOT apply.
• A format, not a version — the version comes from the target document.
• Unrecognized values MAY still be applied with a warning, so format-blind tools remain conformant.

Note that B is useful even if the TDC holds the line on scope. If Overlay stays OpenAPI-only, targetFormat: openapi is still the mechanism that turns "silently did nothing" into "this Overlay is not for this document".

Open questions

1. Field name. targetFormat matches OAI camelCase and the "target document" terminology, but sits next to the Action Object's unrelated target (a JSONPath). extendsFormat is an alternative. Arazzo just calls it type.
2. Single value or list? One string means an Overlay genuinely valid for several formats must omit the field.
3. SHOULD NOT or MUST NOT apply on mismatch? SHOULD leaves room for a --force escape hatch.
4. Scope split. Is A acceptable without B, or B without A?
5. Does this actually conflict with the visitor-pattern plan, in the view of whoever is furthest along thinking about it? I would rather find out now than after a PR.

Prototype

I have a working branch against versions/1.2.0-dev.md implementing both parts — spec text, the schema change, pass/fail fixtures, worked AsyncAPI and Arazzo examples, and matching compliant sets. The existing suite passes with JSON Schema keyword coverage still at 100%. I am deliberately not opening it as a PR until there is a view on direction, given #268.

Happy to bring this to a Tuesday Overlays call if that is the better venue.

[lornajane]

It's an interesting idea, and all topics are open for discussion. If you already have a branch, perhaps you can open a draft pull request to help us understand the changes? I think philosophically, the group is still pretty well aligned with the remarks in #268 but that's not a reason to not revisit this topic.

[bielu]

@lornajane pushed :)