From d9847b2a518bdc5c58505ea82aa329827d42b16d Mon Sep 17 00:00:00 2001 From: Arkadiusz biel Date: Tue, 28 Jul 2026 16:58:31 +0100 Subject: [PATCH] Add targetFormat and generalize prose to target documents Overlay is already format agnostic in substance: Actions are RFC 9535 JSONPath queries over a JSON/YAML tree, the merge rules are defined only in terms of objects, arrays and primitives, and the JSON Schema places no constraint on the target. Only the prose ties it to OpenAPI. Generalize the prose in 1.2.0-dev to a defined "target document" term recognizing OpenAPI Descriptions, AsyncAPI documents and Arazzo Descriptions, and add an optional targetFormat field so an Overlay can declare the format it was written for. targetFormat is optional, so existing Overlays are unaffected and tools that ignore it stay conformant. Its values match Arazzo's Source Description "type" field exactly (openapi, asyncapi, arazzo); other values SHOULD be absolute URIs. Without it, applying an Overlay to the wrong kind of document fails silently, because a target selecting zero nodes is defined to succeed. Not an enum in the JSON Schema: the specification permits URI values for formats it does not define, so an enum would reject conformant documents. AsyncAPI and Arazzo are not in specref, so they are added to the localBiblio block that already carried a comment saying to do this. Refs #367 Co-Authored-By: Claude Opus 5 --- README.md | 4 +- compliant-sets/README.md | 6 +- .../arazzo-sandbox-workflow/arazzo.yaml | 20 ++ .../arazzo-sandbox-workflow/output.yaml | 22 ++ .../arazzo-sandbox-workflow/overlay.yaml | 14 + .../asyncapi.yaml | 40 +++ .../output.yaml | 28 ++ .../overlay.yaml | 17 ++ schemas/v1.2-dev/schema.yaml | 3 + scripts/md2html/md2html.js | 16 +- tests/v1.2-dev/fail/target-format-empty.yaml | 7 + .../fail/target-format-invalid-type.yaml | 8 + tests/v1.2-dev/pass/target-format-arazzo.yaml | 10 + .../v1.2-dev/pass/target-format-asyncapi.yaml | 9 + .../v1.2-dev/pass/target-format-openapi.yaml | 7 + tests/v1.2-dev/pass/target-format-uri.yaml | 7 + versions/1.2.0-dev.md | 250 +++++++++++++++++- 17 files changed, 453 insertions(+), 15 deletions(-) create mode 100644 compliant-sets/arazzo-sandbox-workflow/arazzo.yaml create mode 100644 compliant-sets/arazzo-sandbox-workflow/output.yaml create mode 100644 compliant-sets/arazzo-sandbox-workflow/overlay.yaml create mode 100644 compliant-sets/asyncapi-remove-internal-channels/asyncapi.yaml create mode 100644 compliant-sets/asyncapi-remove-internal-channels/output.yaml create mode 100644 compliant-sets/asyncapi-remove-internal-channels/overlay.yaml create mode 100644 tests/v1.2-dev/fail/target-format-empty.yaml create mode 100644 tests/v1.2-dev/fail/target-format-invalid-type.yaml create mode 100644 tests/v1.2-dev/pass/target-format-arazzo.yaml create mode 100644 tests/v1.2-dev/pass/target-format-asyncapi.yaml create mode 100644 tests/v1.2-dev/pass/target-format-openapi.yaml create mode 100644 tests/v1.2-dev/pass/target-format-uri.yaml diff --git a/README.md b/README.md index d3e7823..dc93ed2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Overlay Specification -The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). +The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing target document yet remains separate from the target document's source document(s). + +A target document is any JSON or YAML document. The specification recognizes [OpenAPI](https://www.openapis.org/) Descriptions, [AsyncAPI](https://www.asyncapi.com/) documents and [Arazzo](https://spec.openapis.org/arazzo/latest.html) Descriptions as target documents, and an Overlay can declare which of them it was designed for with the `targetFormat` field. This specification is a community-driven, open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. diff --git a/compliant-sets/README.md b/compliant-sets/README.md index 77d34b0..0a0a8af 100644 --- a/compliant-sets/README.md +++ b/compliant-sets/README.md @@ -1,9 +1,9 @@ # OpenAPI Overlay Compliant Sets -The folders in this directory contain sets of "known good" Overlays, along with OpenAPI descriptions before and after the Overlay. +The folders in this directory contain sets of "known good" Overlays, along with target documents before and after the Overlay. These files are offered as examples of how a series of Overlays are expected to be applied, with the aim of supporting people building tools that apply Overlays. Each directory contains: - `overlay.yaml` - the Overlay -- `openapi.yaml` - an OpenAPI description to use -- `output.yaml` - the OpenAPI description after the Overlay has been applied +- a target document to use, named after its format: `openapi.yaml`, `asyncapi.yaml` or `arazzo.yaml` +- `output.yaml` - the target document after the Overlay has been applied diff --git a/compliant-sets/arazzo-sandbox-workflow/arazzo.yaml b/compliant-sets/arazzo-sandbox-workflow/arazzo.yaml new file mode 100644 index 0000000..2d0fc43 --- /dev/null +++ b/compliant-sets/arazzo-sandbox-workflow/arazzo.yaml @@ -0,0 +1,20 @@ +arazzo: 1.1.0 +info: + title: Pet purchasing workflow + version: 1.0.0 +sourceDescriptions: + - name: petStoreDescription + url: https://api.example.com/petstore.openapi.yaml + type: openapi +workflows: + - workflowId: loginUserAndRetrievePet + summary: Login a user and then retrieve a pet + steps: + - stepId: loginStep + operationId: $sourceDescriptions.petStoreDescription.loginUser + successCriteria: + - condition: $statusCode == 200 + - stepId: getPetStep + operationId: $sourceDescriptions.petStoreDescription.getPetById + successCriteria: + - condition: $statusCode == 200 diff --git a/compliant-sets/arazzo-sandbox-workflow/output.yaml b/compliant-sets/arazzo-sandbox-workflow/output.yaml new file mode 100644 index 0000000..613f303 --- /dev/null +++ b/compliant-sets/arazzo-sandbox-workflow/output.yaml @@ -0,0 +1,22 @@ +arazzo: 1.1.0 +info: + title: Pet purchasing workflow + version: 1.0.0 +sourceDescriptions: + - name: petStoreDescription + url: https://sandbox.example.com/petstore.openapi.yaml + type: openapi +workflows: + - workflowId: loginUserAndRetrievePet + summary: Login a user and then retrieve a pet + steps: + - stepId: loginStep + operationId: $sourceDescriptions.petStoreDescription.loginUser + successCriteria: + - condition: $statusCode == 200 + - condition: $response.header.X-Response-Time < 1000 + - stepId: getPetStep + operationId: $sourceDescriptions.petStoreDescription.getPetById + successCriteria: + - condition: $statusCode == 200 + - condition: $response.header.X-Response-Time < 1000 diff --git a/compliant-sets/arazzo-sandbox-workflow/overlay.yaml b/compliant-sets/arazzo-sandbox-workflow/overlay.yaml new file mode 100644 index 0000000..cb75f57 --- /dev/null +++ b/compliant-sets/arazzo-sandbox-workflow/overlay.yaml @@ -0,0 +1,14 @@ +overlay: '1.2.0' +info: + title: Run the pet purchasing workflow against the sandbox + version: '1.0.0' +targetFormat: arazzo +actions: + - target: $.sourceDescriptions[?@.name == 'petStoreDescription'] + description: Use the sandbox API description as the source + update: + url: https://sandbox.example.com/petstore.openapi.yaml + - target: $.workflows[*].steps[*].successCriteria + description: Require every step to meet the sandbox response time budget + update: + condition: $response.header.X-Response-Time < 1000 diff --git a/compliant-sets/asyncapi-remove-internal-channels/asyncapi.yaml b/compliant-sets/asyncapi-remove-internal-channels/asyncapi.yaml new file mode 100644 index 0000000..96b7bd1 --- /dev/null +++ b/compliant-sets/asyncapi-remove-internal-channels/asyncapi.yaml @@ -0,0 +1,40 @@ +asyncapi: 3.1.0 +info: + title: Account Service + version: 1.0.0 +servers: + production: + host: broker.internal.example.com:9092 + protocol: kafka + description: Internal broker +channels: + userSignedUp: + address: user/signedup + messages: + UserSignedUp: + $ref: '#/components/messages/UserSignedUp' + userAudited: + address: user/audited + x-internal: true + messages: + UserAudited: + $ref: '#/components/messages/UserAudited' +operations: + sendUserSignedUp: + action: send + channel: + $ref: '#/channels/userSignedUp' +components: + messages: + UserSignedUp: + payload: + type: object + properties: + displayName: + type: string + UserAudited: + payload: + type: object + properties: + auditId: + type: string diff --git a/compliant-sets/asyncapi-remove-internal-channels/output.yaml b/compliant-sets/asyncapi-remove-internal-channels/output.yaml new file mode 100644 index 0000000..7f58ec4 --- /dev/null +++ b/compliant-sets/asyncapi-remove-internal-channels/output.yaml @@ -0,0 +1,28 @@ +asyncapi: 3.1.0 +info: + title: Account Service + version: 1.0.0 +servers: + production: + host: broker.example.com:9092 + protocol: kafka + description: Public broker +channels: + userSignedUp: + address: user/signedup + messages: + UserSignedUp: + $ref: '#/components/messages/UserSignedUp' +operations: + sendUserSignedUp: + action: send + channel: + $ref: '#/channels/userSignedUp' +components: + messages: + UserSignedUp: + payload: + type: object + properties: + displayName: + type: string diff --git a/compliant-sets/asyncapi-remove-internal-channels/overlay.yaml b/compliant-sets/asyncapi-remove-internal-channels/overlay.yaml new file mode 100644 index 0000000..941a024 --- /dev/null +++ b/compliant-sets/asyncapi-remove-internal-channels/overlay.yaml @@ -0,0 +1,17 @@ +overlay: '1.2.0' +info: + title: Prepare the Account Service document for publication + version: '1.0.0' +targetFormat: asyncapi +actions: + - target: $.servers.production + description: Point consumers at the public broker + update: + host: broker.example.com:9092 + description: Public broker + - target: $.channels[?@['x-internal'] == true] + description: Remove the channels that are not for public consumption + remove: true + - target: $.components.messages.UserAudited + description: Remove the message that is no longer referenced + remove: true diff --git a/schemas/v1.2-dev/schema.yaml b/schemas/v1.2-dev/schema.yaml index 4891415..07013a4 100644 --- a/schemas/v1.2-dev/schema.yaml +++ b/schemas/v1.2-dev/schema.yaml @@ -11,6 +11,9 @@ properties: extends: type: string format: uri-reference + targetFormat: + type: string + minLength: 1 actions: type: array minItems: 1 diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 7dc7c42..e2c2043 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -83,9 +83,19 @@ function preface(title,options) { ], }, ], - // localBiblio: { - // // add local bibliography entries here, add them to https://www.specref.org/, and remove them here once published - // } + // add local bibliography entries here, add them to https://www.specref.org/, and remove them here once published + localBiblio: { + "AsyncAPI": { + title: "AsyncAPI Specification", + href: "https://www.asyncapi.com/docs/reference/specification/latest", + publisher: "AsyncAPI Initiative", + }, + "Arazzo": { + title: "Arazzo Specification", + href: "https://spec.openapis.org/arazzo/latest.html", + publisher: "OpenAPI Initiative", + }, + } }; let preface = '\n' diff --git a/tests/v1.2-dev/fail/target-format-empty.yaml b/tests/v1.2-dev/fail/target-format-empty.yaml new file mode 100644 index 0000000..9d8486e --- /dev/null +++ b/tests/v1.2-dev/fail/target-format-empty.yaml @@ -0,0 +1,7 @@ +overlay: 1.2.0 +info: + title: Empty `targetFormat` value + version: 1.0.0 +targetFormat: '' +actions: + - target: '$' # Root of document diff --git a/tests/v1.2-dev/fail/target-format-invalid-type.yaml b/tests/v1.2-dev/fail/target-format-invalid-type.yaml new file mode 100644 index 0000000..d03abd5 --- /dev/null +++ b/tests/v1.2-dev/fail/target-format-invalid-type.yaml @@ -0,0 +1,8 @@ +overlay: 1.2.0 +info: + title: Invalid `targetFormat` type + version: 1.0.0 +targetFormat: + - openapi +actions: + - target: '$' # Root of document diff --git a/tests/v1.2-dev/pass/target-format-arazzo.yaml b/tests/v1.2-dev/pass/target-format-arazzo.yaml new file mode 100644 index 0000000..f4a1080 --- /dev/null +++ b/tests/v1.2-dev/pass/target-format-arazzo.yaml @@ -0,0 +1,10 @@ +overlay: 1.2.0 +info: + title: Overlay targeting an Arazzo Description + version: 1.0.0 +targetFormat: arazzo +extends: './pet-purchase.arazzo.yaml' +actions: + - target: $.workflows[*].steps[*].successCriteria + update: + condition: $response.header.X-Response-Time < 1000 diff --git a/tests/v1.2-dev/pass/target-format-asyncapi.yaml b/tests/v1.2-dev/pass/target-format-asyncapi.yaml new file mode 100644 index 0000000..f4f4245 --- /dev/null +++ b/tests/v1.2-dev/pass/target-format-asyncapi.yaml @@ -0,0 +1,9 @@ +overlay: 1.2.0 +info: + title: Overlay targeting an AsyncAPI document + version: 1.0.0 +targetFormat: asyncapi +actions: + - target: $.channels.* + update: + x-internal: true diff --git a/tests/v1.2-dev/pass/target-format-openapi.yaml b/tests/v1.2-dev/pass/target-format-openapi.yaml new file mode 100644 index 0000000..3c26813 --- /dev/null +++ b/tests/v1.2-dev/pass/target-format-openapi.yaml @@ -0,0 +1,7 @@ +overlay: 1.2.0 +info: + title: Overlay targeting an OpenAPI Description + version: 1.0.0 +targetFormat: openapi +actions: + - target: '$' # Root of document diff --git a/tests/v1.2-dev/pass/target-format-uri.yaml b/tests/v1.2-dev/pass/target-format-uri.yaml new file mode 100644 index 0000000..501f64d --- /dev/null +++ b/tests/v1.2-dev/pass/target-format-uri.yaml @@ -0,0 +1,7 @@ +overlay: 1.2.0 +info: + title: Overlay targeting a format identified by an absolute URI + version: 1.0.0 +targetFormat: https://example.com/formats/my-description-format +actions: + - target: '$' # Root of document diff --git a/versions/1.2.0-dev.md b/versions/1.2.0-dev.md index 7f771e7..d890a07 100644 --- a/versions/1.2.0-dev.md +++ b/versions/1.2.0-dev.md @@ -2,7 +2,7 @@ ## Abstract -The Overlay Specification defines a document format for information that augments an existing [[OpenAPI]] description yet remains separate from the OpenAPI description's source document(s). +The Overlay Specification defines a document format for information that augments an existing target document, such as an [[OpenAPI]], [[AsyncAPI]] or [[Arazzo]] description, yet remains separate from the target document's source document(s). ## Version 1.2.0 @@ -12,10 +12,12 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -The Overlay Specification is a companion to the [[OpenAPI]] Specification. -An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description. +The Overlay Specification is a companion to the [[OpenAPI]], [[AsyncAPI]] and [[Arazzo]] Specifications. +An Overlay describes a set of changes to be applied or "overlaid" onto an existing [target document](#target-document). -The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. An Overlay may be specific to a single OpenAPI description or be designed to apply the same transform to any OpenAPI description. +The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many target documents. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from a description before sharing it with partners. An Overlay may be specific to a single target document or be designed to apply the same transform to any target document of a given format. + +Because [Actions](#action-object) are expressed as [[RFC9535|JSONPath]] query expressions over the JSON or YAML structure of the target document, the Overlay Specification is not tied to any single target document format. This specification recognizes [[OpenAPI]] Descriptions, [[AsyncAPI]] documents and [[Arazzo]] Descriptions as target documents, and the [`targetFormat`](#overlay-target-format) field allows an Overlay to declare which of them it was designed for. ## Definitions @@ -23,6 +25,18 @@ The main purpose of the Overlay Specification is to provide a way to repeatably An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update`, `remove`, or `copy`). The `target` property is a [[RFC9535|RFC9535 JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change. +### Target Document + +A target document is the JSON or YAML document that an Overlay is applied to. + +The Overlay Specification places no constraints on the contents of a target document beyond it being a JSON or YAML document. The following target document formats are recognized by this specification and are identified by the [`targetFormat`](#overlay-target-format) field: + +- an [[OpenAPI]] Description +- an [[AsyncAPI]] document +- an [[Arazzo]] Description + +Tooling MAY support target document formats not listed here. + ## Specification ### Versions @@ -36,9 +50,11 @@ The Overlay Specification is versioned using a `major`.`minor`.`patch` versionin An Overlay document that conforms to the Overlay Specification is itself a JSON object, which may be represented either in [[RFC8259|JSON]] or [[YAML|YAML]] format. Examples in this specification will be shown in YAML for brevity. Implementations MUST support applying either JSON or YAML Overlay documents to -[[OpenAPI|OpenAPI]] descriptions +[target documents](#target-document) represented in either YAML or JSON format. +Implementations MAY support only a subset of the target document formats listed in [Target Document](#target-document), for example only [[OpenAPI|OpenAPI]] Descriptions. Such implementations SHOULD document the formats they support and SHOULD report an error when an Overlay declares a [`targetFormat`](#overlay-target-format) they do not support. + All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. @@ -83,7 +99,8 @@ This is the root object of the [Overlay](#overlay). | ---- | :----: | ---- | | overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. | | info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. | -| extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. | +| extends | `string` | URI reference that identifies the [target document](#target-document) (such as an [[OpenAPI]] document) this overlay applies to. | +| targetFormat | `string` | The format of the [target document](#target-document) this Overlay is designed to be applied to. The value MUST NOT be empty and MUST be one of the values defined in [Target Format Values](#target-format-values) or an absolute URI. | | actions | [[Action Object](#action-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -113,6 +130,44 @@ info: extends: './tictactoe.yaml' ``` +##### Target Format + +The `targetFormat` property declares the format of the [target document](#target-document) the Overlay was designed for. It is independent of `extends`: `extends` identifies a specific document, while `targetFormat` identifies the format of the document(s) the Overlay applies to. Either, both or neither MAY be present. + +In the following example the Overlay declares that it is designed to be applied to [[AsyncAPI]] documents, without naming a specific one. + +```yaml +overlay: 1.2.0 +info: + title: Mark all channels as internal + version: 1.0.0 +targetFormat: asyncapi +actions: + - target: $.channels.* + update: + x-internal: true +``` + +Where `targetFormat` is omitted, the Overlay makes no assertion about the format of the target document. + +Where `targetFormat` is present and tooling is able to determine the format of the target document, tooling SHOULD report an error and SHOULD NOT apply the Overlay if the two do not match. The format of a target document can usually be determined from the root field naming its specification version, for example `openapi`, `asyncapi` or `arazzo`. + +The `targetFormat` property identifies a format, not a version of that format. The version of the target document is determined from the target document itself. + +###### Target Format Values + +The following values are defined by this specification. Values are case sensitive. + +| Value | Target Document Format | +| ---- | ---- | +| `openapi` | An [[OpenAPI]] Description | +| `asyncapi` | An [[AsyncAPI]] document | +| `arazzo` | An [[Arazzo]] Description | + +Values that do not appear in the table above SHOULD be an absolute URI identifying the target document format, in order to avoid collisions with values this specification MAY define in the future. + +Tooling that does not recognize the value of `targetFormat` MAY apply the Overlay, but SHOULD warn that it is unable to verify the format of the target document. + #### Info Object The object provides metadata about the Overlay. @@ -559,6 +614,185 @@ paths: description: OK ``` +#### AsyncAPI Overlay Example + +Overlays are not limited to [[OpenAPI]] Descriptions. This example prepares an [[AsyncAPI]] document for publication by pointing the server at the public broker and removing the channels that are marked as internal. + +##### Source Document + +```yaml +asyncapi: 3.1.0 +info: + title: Account Service + version: 1.0.0 +servers: + production: + host: broker.internal.example.com:9092 + protocol: kafka + description: Internal broker +channels: + userSignedUp: + address: user/signedup + messages: + UserSignedUp: + $ref: '#/components/messages/UserSignedUp' + userAudited: + address: user/audited + x-internal: true + messages: + UserAudited: + $ref: '#/components/messages/UserAudited' +operations: + sendUserSignedUp: + action: send + channel: + $ref: '#/channels/userSignedUp' +components: + messages: + UserSignedUp: + payload: + type: object + properties: + displayName: + type: string + UserAudited: + payload: + type: object + properties: + auditId: + type: string +``` + +##### Overlay + +```yaml +overlay: 1.2.0 +info: + title: Prepare the Account Service document for publication + version: 1.0.0 +targetFormat: asyncapi +actions: + - target: $.servers.production + description: Point consumers at the public broker + update: + host: broker.example.com:9092 + description: Public broker + - target: $.channels[?@['x-internal'] == true] + description: Remove the channels that are not for public consumption + remove: true + - target: $.components.messages.UserAudited + description: Remove the message that is no longer referenced + remove: true +``` + +##### Result Document + +```yaml +asyncapi: 3.1.0 +info: + title: Account Service + version: 1.0.0 +servers: + production: + host: broker.example.com:9092 + protocol: kafka + description: Public broker +channels: + userSignedUp: + address: user/signedup + messages: + UserSignedUp: + $ref: '#/components/messages/UserSignedUp' +operations: + sendUserSignedUp: + action: send + channel: + $ref: '#/channels/userSignedUp' +components: + messages: + UserSignedUp: + payload: + type: object + properties: + displayName: + type: string +``` + +#### Arazzo Overlay Example + +This example retargets an [[Arazzo]] Description at a sandbox environment and adds a response time criterion to every step, demonstrating that an `update` of an array node appends to each selected array. + +##### Source Document + +```yaml +arazzo: 1.1.0 +info: + title: Pet purchasing workflow + version: 1.0.0 +sourceDescriptions: + - name: petStoreDescription + url: https://api.example.com/petstore.openapi.yaml + type: openapi +workflows: + - workflowId: loginUserAndRetrievePet + summary: Login a user and then retrieve a pet + steps: + - stepId: loginStep + operationId: $sourceDescriptions.petStoreDescription.loginUser + successCriteria: + - condition: $statusCode == 200 + - stepId: getPetStep + operationId: $sourceDescriptions.petStoreDescription.getPetById + successCriteria: + - condition: $statusCode == 200 +``` + +##### Overlay + +```yaml +overlay: 1.2.0 +info: + title: Run the pet purchasing workflow against the sandbox + version: 1.0.0 +targetFormat: arazzo +actions: + - target: $.sourceDescriptions[?@.name == 'petStoreDescription'] + description: Use the sandbox API description as the source + update: + url: https://sandbox.example.com/petstore.openapi.yaml + - target: $.workflows[*].steps[*].successCriteria + description: Require every step to meet the sandbox response time budget + update: + condition: $response.header.X-Response-Time < 1000 +``` + +##### Result Document + +```yaml +arazzo: 1.1.0 +info: + title: Pet purchasing workflow + version: 1.0.0 +sourceDescriptions: + - name: petStoreDescription + url: https://sandbox.example.com/petstore.openapi.yaml + type: openapi +workflows: + - workflowId: loginUserAndRetrievePet + summary: Login a user and then retrieve a pet + steps: + - stepId: loginStep + operationId: $sourceDescriptions.petStoreDescription.loginUser + successCriteria: + - condition: $statusCode == 200 + - condition: $response.header.X-Response-Time < 1000 + - stepId: getPetStep + operationId: $sourceDescriptions.petStoreDescription.getPetById + successCriteria: + - condition: $statusCode == 200 + - condition: $response.header.X-Response-Time < 1000 +``` + ### Specification Extensions While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. @@ -583,9 +817,9 @@ Other file naming conventions are also supported. Interoperable Overlay Documents MUST use RFC9535 JSONPath query expressions and MUST NOT use tool-specific JSONPath extensions. -### Comments in OpenAPI Descriptions +### Comments in Target Documents -Some formats, like [YAML](https://yaml.org/) or [JSONC](https://jsonc.org/), support using comments which do not impact the semantic meaning of the description. Applying Overlay Actions to a description MAY result in the loss of such comments in the updated description. The exact behavior is specific to the tool implementing the Overlay Specification. +Some formats, like [YAML](https://yaml.org/) or [JSONC](https://jsonc.org/), support using comments which do not impact the semantic meaning of the description. Applying Overlay Actions to a target document MAY result in the loss of such comments in the updated document. The exact behavior is specific to the tool implementing the Overlay Specification. ## Appendix A: Revision History