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

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.
 

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

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

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

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

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

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

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

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

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 = '<!DOCTYPE html><html lang="en"><head>\n'

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

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

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

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

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

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