DRAFT: target document format declaration (targetFormat) — for discussion on #367

[bielu]

What this is

A draft PR opened at @lornajane's request on #367, to make the proposed changes concrete enough to discuss. It is not a request to merge.

To be explicit about where this stands: the response on #367 was that the group is "still pretty well aligned with the remarks in #268", and nothing here should be read as assuming otherwise. This exists so the discussion can be about specific text rather than a description of specific text. If the outcome is that Overlay stays OpenAPI-scoped, closing this is a perfectly good result — though I would flag that part of it (below) has value either way.

Refs #367, #268.

How to review this in pieces

The change splits cleanly in two, and the group may want one, the other, neither, or a smaller version of either. They are in one branch only for convenience and I am happy to separate them.

Part A — editorial: generalize prose to "target document"

versions/1.2.0-dev.md currently ties Overlay to OpenAPI in the Abstract, the Introduction, the Format section's Implementations MUST support applying ... to OpenAPI descriptions, and a heading called Comments in OpenAPI Descriptions. Part A introduces a defined target document term and names the three recognized formats, while explicitly permitting implementations to support only a subset — so an OpenAPI-only tool stays conformant.

This part is the one that depends on the scope question. If the group holds the #268 line, Part A largely goes away.

Two normative mentions of OpenAPI are left in place on purpose: the subset-support allowance, and the x-oai-/x-oas- extension reservation.

Part B — normative: optional targetFormat 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 existing Overlays and existing tools are unaffected.
• Values openapi / asyncapi / arazzo, matching Arazzo 1.1.0's Source Description type field exactly; other values SHOULD be absolute URIs so private formats cannot collide with future reserved values.
• Independent of extends — extends names a document, targetFormat names a format.
• On mismatch, where tooling can determine the target's format, it SHOULD report an error and SHOULD NOT apply. Unrecognized values MAY still be applied with a warning, so format-blind tools remain conformant.
• Identifies a format, not a version.

Part B stands on its own even if the scope question goes the other way. Its real job is the silent-failure case from #367: because a target selecting zero nodes is defined to succeed, applying an Overlay to the wrong document exits 0 having changed nothing. In an OpenAPI-only Overlay ecosystem that is still reachable, and targetFormat: openapi is still the thing that turns it into an error. If the group wants only Part B, scoped to a single legal value today, that is a coherent change and I would be glad to cut it down to that.

Implementation notes worth a second opinion

• targetFormat is type: string, minLength: 1 in the JSON Schema, deliberately not an enum. Since the spec text permits URI values for formats it does not define, an enum would make conformant documents fail schema validation. If the group would rather constrain it, that spec text needs to change too.
• update on an array node appends. The Arazzo example leans on this (appending a success criterion to every step's successCriteria). It follows the existing Action Object rules, but it is the least obvious behavior exercised here, so worth a look.
• Bibliography. [[AsyncAPI]] and [[Arazzo]] are not in specref ([[OpenAPI]] is), so they are added to the localBiblio block in scripts/md2html/md2html.js — which already carried a comment saying to do exactly this and to remove entries once published to specref. If these should be pushed to specref first, say so and I will drop the local entries.
• Compliant sets use overlay: '1.2.0' while the existing sets use 1.0.0, because they demonstrate a 1.2.0 feature. Flagging in case mixing versions in that directory is unwanted.
• The spec examples and the compliant sets are byte-identical on purpose, so the two cannot drift.

Verification

• npm test — 109 pass. JSON Schema keyword (statement) coverage stays 100%; v1.2-dev function coverage 91.9% → 95.5%.
• npx markdownlint-cli2 "*.md" "schemas/**/*.md" "versions/*.md" — 0 issues.
• node scripts/md2html/md2html.js --maintainers EDITORS.md versions/1.2.0-dev.md renders clean with the new localBiblio.
• Both new compliant-set overlays validated against schemas/v1.2-dev/schema.yaml. (scripts/validate.mjs is hardcoded to schemas/v1.0/, so this needed a one-off script — possibly worth a separate issue.)
• All new internal anchors resolve.
• linkspector could not run locally (headless-browser timeout); the two new external URLs were confirmed HTTP 200 by hand. CI will be the real check.

Open questions

Carried over from #367, still open:

1. Field name. targetFormat matches OAI camelCase and the "target document" terminology, but sits next to the Action Object's unrelated target (a JSONPath). Arazzo just calls it type.
2. Single value or list? One string means an Overlay 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. Does Part B conflict with the type-based selection / visitor-pattern direction raised in Overlay support for Arazzo #268? My argument on Revisit: should Overlays declare their target document format? (follow-up to #268) #367 is that it helps — a visitor needs to know which type model applies, and declaring it beats sniffing the document — but I would rather hear that from whoever is furthest along on it.

Per CONTRIBUTING.md, changes under versions/ need approval from two Overlay-Maintainers. Leaving this as a draft until there is a direction.