diff --git a/examples/1.1.0/pet-asyncapi.yaml b/examples/1.1.0/pet-asyncapi.yaml new file mode 100644 index 0000000..3c7d1ef --- /dev/null +++ b/examples/1.1.0/pet-asyncapi.yaml @@ -0,0 +1,81 @@ +asyncapi: 3.0.0 + +info: + title: Simple Pet Purchase API + version: "1.0.0" + +servers: + localKafka: + host: localhost:9092 + protocol: kafka + +channels: + place-order: + address: place-order + messages: + placeOrder.message: + $ref: "#/components/messages/OrderRequest" + + confirm-order: + address: confirm-order + messages: + confirmOrder.message: + $ref: "#/components/messages/OrderResponse" + +operations: + placeOrder: + description: Place an order + action: receive + channel: + $ref: "#/channels/place-order" + messages: + - $ref: "#/channels/place-order/messages/placeOrder.message" + reply: + channel: + $ref: "#/channels/confirm-order" + messages: + - $ref: "#/channels/confirm-order/messages/confirmOrder.message" + +components: + messages: + OrderRequest: + contentType: application/json + correlationId: + description: Identifier that correlates this request with a response + location: $message.header#/orderRequestId + headers: + type: object + required: + - orderRequestId + properties: + orderRequestId: + type: string + description: Unique ID for tracking the order flow + payload: + type: object + required: + - petId + properties: + petId: + type: integer + + OrderResponse: + contentType: application/json + correlationId: + description: Identifier that correlates this response with a request + location: $message.header#/orderRequestId + headers: + type: object + required: + - orderRequestId + properties: + orderRequestId: + type: string + description: Unique ID for tracking the order flow + payload: + type: object + required: + - orderId + properties: + orderId: + type: integer \ No newline at end of file diff --git a/src/arazzo.md b/src/arazzo.md index 02a254e..e6d2ae7 100644 --- a/src/arazzo.md +++ b/src/arazzo.md @@ -92,13 +92,13 @@ As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/htm The formats defined are: -| `format` | JSON Data Type | Comments | -| ---- | ---- | ---- | -| `int32` | number | signed 32 bits | -| `int64` | number | signed 64 bits (a.k.a long) | -| `float` | number | | -| `double` | number | | -| `password` | string | A hint to obscure the value. | +| `format` | JSON Data Type | Comments | +|------------|----------------|------------------------------| +| `int32` | number | signed 32 bits | +| `int64` | number | signed 64 bits (a.k.a long) | +| `float` | number | | +| `double` | number | | +| `password` | string | A hint to obscure the value. | ### Parsing Documents @@ -196,21 +196,21 @@ This is the root object of the [Arazzo Description](#arazzo-description). ##### Fixed Fields -| Field Name | Type | Description | -| ---- | :----: | ---- | -| arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. | -| $self | `string` | A URI-reference for the Arazzo Description. This string MUST be in the form of a URI-reference as defined by [RFC3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). When present, this field provides the self-assigned URI of this Arazzo Description, which also serves as its base URI in accordance with [RFC3986 Section 5.1.1](https://tools.ietf.org/html/rfc3986#section-5.1.1) for resolving relative references within this document. The `$self` URI MUST NOT contain a fragment identifier. Arazzo Description documents can include a `$self` field to ensure portable, unambiguous reference resolution. | -| info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. | -| sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. | -| workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. | -| components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. | +| Field Name | Type | Description | +|------------------------------------------------|:---------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. | +| $self | `string` | A URI-reference for the Arazzo Description. This string MUST be in the form of a URI-reference as defined by [RFC3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). When present, this field provides the self-assigned URI of this Arazzo Description, which also serves as its base URI in accordance with [RFC3986 Section 5.1.1](https://tools.ietf.org/html/rfc3986#section-5.1.1) for resolving relative references within this document. The `$self` URI MUST NOT contain a fragment identifier. Arazzo Description documents can include a `$self` field to ensure portable, unambiguous reference resolution. | +| info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. | +| sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. | +| workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. | +| components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. | This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Arazzo Specification Object Example ```yaml -arazzo: 1.0.1 +arazzo: 1.1.0 $self: https://api.example.com/workflows/pet-purchase.arazzo.yaml info: title: A pet purchasing workflow @@ -222,6 +222,9 @@ sourceDescriptions: - name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi +- name: asyncOrderApiDescription + url: https://raw.githubusercontent.com/OAI/Arazzo-Specification/main/examples/1.1.0/pet-asyncapi.yaml + type: asyncapi workflows: - workflowId: loginUserAndRetrievePet @@ -234,10 +237,12 @@ workflows: type: string password: type: string + orderCorrelationId: + type: string steps: - stepId: loginStep description: This step demonstrates the user login step - operationId: loginUser + operationId: $sourceDescriptions.petstoreDescription.loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username @@ -266,11 +271,35 @@ workflows: value: $steps.loginStep.outputs.sessionToken successCriteria: - condition: $statusCode == 200 + onSuccess: + - name: 'noPetsAvailable' + type: "end" + criteria: + - condition: $response.body#/0 == null outputs: - # outputs from this step - availablePets: $response.body + petId: $response.body#/0/id + - stepId: purchasePetStep + description: purchase a pet by posting an message on place-order channel + operationPath: $sourceDescriptions.asyncOrderApiDescription.placeOrder + action: send + parameters: + - name: orderCorrelationId + in: header + value: $inputs.orderCorrelationId + requestBody: + contentType: application/json + payload: + petId: $steps.getPetStep.outputs.petId + - stepId: confirmPetPurchaseStep + description: confirm the purchase of a pet + operationPath: $sourceDescriptions.asyncOrderApiDescription.confirmOrder + correlationId: $inputs.orderCorrelationId + timeout: 6000 + action: receive + outputs: + orderId: $message.payload.orderId outputs: - available: $steps.getPetStep.outputs.availablePets + orderId: $steps.confirmPetPurchaseStep.outputs.orderId ``` #### Info Object @@ -280,12 +309,12 @@ The metadata MAY be used by the clients if needed. ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. | -| summary | `string` | A short summary of the Arazzo Description. | +| Field Name | Type | Description | +|-------------------------------------------|:--------:|----------------------------------------------------------------------------------------------------------------------------------------------------| +| title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. | +| summary | `string` | A short summary of the Arazzo Description. | | description | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). | +| version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -308,11 +337,11 @@ An object storing a map between named description keys and location URLs to the ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | +| Field Name | Type | Description | +|-------------------------------|:--------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | -| url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). | -| type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. | +| url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). | +| type | `string` | The type of source description. Possible values are `"openapi"` or `"asyncapi"` or `"arazzo"`. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -331,18 +360,18 @@ Describes the steps to be taken across one or more APIs to achieve an objective. ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows described in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | -| summary | `string` | A summary of the purpose or objective of the workflow. | -| description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. | -| dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. | -| steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. | -| successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | -| failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | -| outputs | Map[`string`, {expression} \| [Selector Object](#selector-object) ] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions) or [Selector Object](#selector-object). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | -| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | +| Field Name | Type | Description | +|-----------------------------------------------------|:----------------------------------------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows described in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | +| summary | `string` | A summary of the purpose or objective of the workflow. | +| description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. | +| dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. | +| steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. | +| successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | +| failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | +| outputs | Map[`string`, {expression} \| [Selector Object](#selector-object) ] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions) or [Selector Object](#selector-object). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -385,26 +414,74 @@ outputs: #### Step Object -Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object)) or another [Workflow Object](#workflow-object). +Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object)), ([AysncAPI Operations Object](https://www.asyncapi.com/docs/reference/specification/latest#operationsObject)) or another [Workflow Object](#workflow-object). ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | -| operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. | -| operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. | -| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. | -| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | -| requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC9110](https://tools.ietf.org/html/rfc9110#section-9.3) explicitly defines semantics for "content" like request bodies, such as within POST, PUT, and PATCH methods. For methods where the HTTP specification provides less clarity—such as GET, HEAD, and DELETE—the use of `requestBody` is permitted but does not have well-defined semantics. In these cases, its use SHOULD be avoided if possible. | -| successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. | -| onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | -| onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | -| outputs | Map[`string`, {expression} \| [Selector Object](#selector-object)] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions) or [Selector Object](#selector-object). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | +| Field Name | Type | Description | +|---------------------------------------------------|:----------------------------------------------------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. | +| operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. | +| operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. | +| channelPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an event channel. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `channelPath`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. | +| requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC9110](https://tools.ietf.org/html/rfc9110#section-9.3) explicitly defines semantics for "content" like request bodies, such as within POST, PUT, and PATCH methods. For methods where the HTTP specification provides less clarity—such as GET, HEAD, and DELETE—the use of `requestBody` is permitted but does not have well-defined semantics. In these cases, its use SHOULD be avoided if possible. | +| successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. If `successCriteria` is provided, it `MUST` contain at least one [Criterion Object](#criterion-object). | +| onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. | +| onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. | +| outputs | Map[`string`, {expression} \| [Selector Object](#selector-object)] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions) or [Selector Object](#selector-object). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. | +| timeout | `integer` | The maximum number of milli-seconds to wait for the step to complete before aborting and failing the step. Consequently this will fail the workflow unless `onFailure` actions are defined. | +| correlationId | `string` | A correlationId in AsyncAPI links a request with its response (or more broadly, to trace a single logical transaction across multiple asynchronous messages). Only applicable to `asyncapi` steps with action `receive` and has to be in-sync with correlationId defined in the AsyncAPI document. | +| action | `send or receive` | Describes the intent of the message flow. Indicates whether the step will send (publish) or receive (subscribe) to a message on a channel described in an AsyncAPI document, Only applicable for `asyncapi` steps. | +| dependsOn | List[`string`] | A list of steps that MUST be completed before this step can be executed. `dependsOn` only establishes a prerequisite relationship for the current step and does not trigger execution of the referenced steps. Each value provided MUST be a `stepId`. The `stepId` value is case-sensitive. If the step depended on is defined within the **current workflow**, specify the `stepId` directly (e.g., `authStep`). If the step is defined in a **different workflow within the current Arazzo Document**, reference it using `$workflows..steps.`. If the step is defined in a **separate Arazzo Document**, the workflow MUST be defined in `sourceDescriptions` and referenced using `$sourceDescriptions...steps.` to avoid ambiguity. If your step depends on the output of a non-blocking/asynchronous step, then you SHOULD use `dependsOn` and refer to the async step using one of these patterns. | This object MAY be extended with [Specification Extensions](#specification-extensions). +##### Step Dependencies and Execution Order + +The `dependsOn` field at the step level is primarily intended to coordinate asynchronous operations. + +###### Recommended Approach for Synchronous Workflows + +For workflows containing only synchronous steps, the RECOMMENDED approach is to order steps sequentially in the steps array without using `dependsOn`. This provides the simplest and clearest execution model. Step-level `dependsOn` is typically unnecessary when all operations complete synchronously and execution follows a linear path. + +###### Use Case: Async Coordination + +When a step must wait for an asynchronous operation to complete before proceeding, `dependsOn` establishes a join point for in-flight async work. For example, a step that requests an order status SHOULD declare `dependsOn` on the step that receives order creation status from an async order placement, even if no explicit output reference exists. This ensures the async operation completes before the dependent step executes. + +###### Authoring Guidance + +For async workflows, authors SHOULD use `dependsOn` to explicitly declare when a step must wait for async work to complete, regardless of output references. This is the intended use case for step-level dependencies. + +###### Tool Behavior + +Tools MUST respect all declared `dependsOn` relationships. Tools MUST also treat runtime expression output references (e.g., `$steps.stepId.outputs.field`) as implicit dependencies and ensure the referenced step completes before the referencing step executes. + +Tools supporting only sequential execution MUST execute steps in an order that satisfies both explicit (`dependsOn`) and implicit (output reference) dependencies. + +###### Validation Recommendations + +Implementations SHOULD validate the following scenario: + +When no `dependsOn` is used in a workflow (sequential execution model), implementations SHOULD produce an error if a step references another step's outputs where the referenced step appears later in the steps array. This indicates a forward reference that cannot be satisfied in sequential execution. + +##### Defining Success for Asynchronous Steps + +For steps that reference AsyncAPI operations (via `operationId` or `channelPath`), tools will send or receive messages on the specified channel as defined by the referenced AsyncAPI description. For AsyncAPI send operations, the step completes immediately after the message is sent. Arazzo does not model broker acknowledgment or delivery confirmation. For AsyncAPI receive operations, step completion depends on message receipt as described below. + +Because AsyncAPI channels MAY define multiple message types, and because message payloads MAY represent either success or failure conditions, authors SHOULD define `successCriteria` for AsyncAPI receive steps to explicitly evaluate the received message payload (for example, via `$message.payload`) and determine whether the step succeeded. + +Authors MAY omit `successCriteria` only when both of the following conditions are met: + +- The channel defines a single message type that unambiguously represents successful completion +- The message payload does not contain fields indicating error states (e.g., status codes or error flags) + +When `successCriteria` is omitted, receiving any message matching the `correlationId` (if specified) within the `timeout` period is considered a successful step completion. + +If `correlationId` is specified, only messages matching the correlation identifier are considered. If no matching message is received within the `timeout` period, the step fails and triggers any defined `onFailure` actions. + ##### Step Object Examples A single step example: @@ -470,6 +547,33 @@ steps: availablePets: $response.body ``` +An async step example: + +```yaml +- stepId: placeOrder + description: This step demonstrates the action of sending a message payload to place an order + operationId: $sourceDescriptions.asyncOrderApi.placeOrder + action: send + parameters: + - name: requestId + in: header + value: $inputs.correlationId + requestBody: + payload: + productId: $inputs.productDetails.productId + quantity: $inputs.productDetails.quantity +- stepId: confirmOrder + description: This step demonstrates the action of receiving a message payload to confirm an order + operationId: $sourceDescriptions.asyncOrderApi.confirmOrder + correlationId: $inputs.correlationId + action: receive + dependsOn: + - placeOrder + timeout: 6000 + outputs: + orderId: $message.payload.orderId +``` + #### Parameter Object Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are several possible locations specified by the `in` field: @@ -482,10 +586,10 @@ Describes a single step parameter. A unique parameter is defined by the combinat ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. | -| in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"querystring"`, `"header"`, or `"cookie"`. When the step, success action, or failure action in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. | +| Field Name | Type | Description | +|-------------------------------------|:----------------------------------------------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. | +| in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"querystring"`, `"header"`, or `"cookie"`. When the step, success action, or failure action in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. | | value | Any \| {expression} \| [Selector Object](#selector-object) | **REQUIRED**. The value to pass in the parameter. The value can be a constant, a [Runtime Expression](#runtime-expressions), or a [Selector Object](#selector-object) to be evaluated and passed to the referenced operation or workflow. For `querystring` parameters, the value MUST resolve to a string representing the complete query string (e.g., `"key1=value1&key2=value2"`). Runtime expressions can be embedded within the string value using `{}` notation. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -528,14 +632,14 @@ A single success action which describes an action to take upon success of a work ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. | -| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. | -| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. | -| stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. | -| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to a workflow as referenced by `workflowId`. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. The `in` field MUST NOT be used. | -| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. | +| Field Name | Type | Description | +|---------------------------------------------|:------------------------------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. | +| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. | +| stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to a workflow as referenced by `workflowId`. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. The `in` field MUST NOT be used. | +| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -562,17 +666,16 @@ A single failure action which describes an action to take upon failure of a work ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. | -| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. | -| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. | -| stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. | -| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to a workflow as referenced by `workflowId`. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. The `in` field MUST NOT be used. | -| retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. | -| retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. | -| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). | - +| Field Name | Type | Description | +|---------------------------------------------|:------------------------------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. | +| type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. | +| workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. | +| stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. | +| parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to a workflow as referenced by `workflowId`. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. The `in` field MUST NOT be used. | +| retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. | +| retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. | +| criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -596,12 +699,12 @@ Components are scoped to the Arazzo document they are defined in. For example, i ##### Fixed Fields -| Field Name | Type | Description | -| --- | :--- | --- | -| inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. | -| parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects | -| successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. | -| failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. | +| Field Name | Type | Description | +|------------------------------------------------------|:---------------------------------------------------------------|---------------------------------------------------------------------------------------| +| inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. | +| parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects | +| successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. | +| failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -697,10 +800,10 @@ A simple object to allow referencing of objects contained within the [Components ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. | -| value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. | +| Field Name | Type | Description | +|-------------------------------------------------|:--------------:|----------------------------------------------------------------------------------------------------| +| reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. | +| value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. | This object cannot be extended with additional properties and any properties added MUST be ignored. @@ -743,39 +846,39 @@ There are four flavors of conditions supported: As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. -| Type | Literal value | -| --- | --- | -| `boolean` | `true` or `false` | -| `null` | `null` | -| `number` | Any number format supported in [Data Types](#data-types). | -| `string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). | +| Type | Literal value | +|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `boolean` | `true` or `false` | +| `null` | `null` | +| `number` | Any number format supported in [Data Types](#data-types). | +| `string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). | ##### Operators -| Operator | Description | -| --- | --- | -| `<` | Less than | -| `<=` | Less than or equal | -| `>` | Greater than | -| `>=` | Greater than or equal | -| `==` | Equal | -| `!=` | Not equal | -| `!` | Not | -| `&&` | And | -| \|\| | Or | -| `()` | Logical Grouping | -| `[]` | Index (0-based) | -| `.` | Property de-reference | +| Operator | Description | +|-------------------|-----------------------| +| `<` | Less than | +| `<=` | Less than or equal | +| `>` | Greater than | +| `>=` | Greater than or equal | +| `==` | Equal | +| `!=` | Not equal | +| `!` | Not | +| `&&` | And | +| \|\| | Or | +| `()` | Logical Grouping | +| `[]` | Index (0-based) | +| `.` | Property de-reference | String comparisons `MUST` be case insensitive. ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). | -| condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. | -| type | `string` \| [Expression Type Object](#expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Expression Type Object](#expression-type-object) MUST be specified. | +| Field Name | Type | Description | +|--------------------------------------------|:-------------------------------------------------------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). | +| condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. | +| type | `string` \| [Expression Type Object](#expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Expression Type Object](#expression-type-object) MUST be specified. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -811,18 +914,18 @@ Defining this object gives the ability to utilize tooling compatible with older ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| type | `string` | **REQUIRED**. The selector type. The options allowed are `jsonpath`, `xpath`, or `jsonpointer`. | +| Field Name | Type | Description | +|-----------------------------------------|:--------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | **REQUIRED**. The selector type. The options allowed are `jsonpath`, `xpath`, or `jsonpointer`. | | version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `rfc9535` or `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`. The allowed value for JSON Pointer is `rfc6901`. | The supported expression selector types and versions are as follows: -| Type | Allowed Versions | Default | -| ---- | --- | --- | -| `jsonpath` | `rfc9535`, `draft-goessner-dispatch-jsonpath-00` | `rfc9535` | -| `xpath` | `xpath-31`, `xpath-30`, `xpath-20`, `xpath-10` | `xpath-31` | -| `jsonpointer` | `rfc6901` (added for completeness) | `rfc6901` | +| Type | Allowed Versions | Default | +|---------------|--------------------------------------------------|------------| +| `jsonpath` | `rfc9535`, `draft-goessner-dispatch-jsonpath-00` | `rfc9535` | +| `xpath` | `xpath-31`, `xpath-30`, `xpath-20`, `xpath-10` | `xpath-31` | +| `jsonpointer` | `rfc6901` (added for completeness) | `rfc6901` | If this object is not defined, the default version for the selector type MUST be used. @@ -850,11 +953,11 @@ An object which enables fine-grained traversal and precise data selection from s ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| context | {expression} | **REQUIRED**. A [Runtime Expression](#runtime-expressions) which MUST evaluate to structured data (e.g., `$response.body`) and set the context for the selector to be applied on. | -| selector | `string` | **REQUIRED**.A selector expression (e.g., `$.items[0].id`, `/Envelope/Item`) in the form of JSONPath expression, XPath expression, or JSON Pointer expression. | -| type | `string` \| [Expression Type Object](#expression-type-object) | **REQUIRED**. The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Expression Type Object](#expression-type-object) MUST be specified. | +| Field Name | Type | Description | +|--------------------------------------------|:-------------------------------------------------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| context | {expression} | **REQUIRED**. A [Runtime Expression](#runtime-expressions) which MUST evaluate to structured data (e.g., `$response.body`) and set the context for the selector to be applied on. | +| selector | `string` | **REQUIRED**.A selector expression (e.g., `$.items[0].id`, `/Envelope/Item`) in the form of JSONPath expression, XPath expression, or JSON Pointer expression. | +| type | `string` \| [Expression Type Object](#expression-type-object) | **REQUIRED**. The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Expression Type Object](#expression-type-object) MUST be specified. | ##### Selector Object Examples @@ -889,11 +992,11 @@ A single request body describing the `Content-Type` and request body content to ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. | -| payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) or [Selector Objects](#selector-object) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. | -| replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. | +| Field Name | Type | Description | +|----------------------------------------------------|:-----------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. | +| payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) or [Selector Objects](#selector-object) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. | +| replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -975,11 +1078,11 @@ Describes a location within a payload (e.g., a request body) and a value to set ##### Fixed Fields -| Field Name | Type | Description | -| --- | :---: | --- | -| target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901), or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions), or [JSONPath](https://tools.ietf.org/html/rfc9535) which MUST be resolved against the request body. Used to identify the location to inject the `value`. | +| Field Name | Type | Description | +|-----------------------------------------------------------------------|:-------------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901), or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions), or [JSONPath](https://tools.ietf.org/html/rfc9535) which MUST be resolved against the request body. Used to identify the location to inject the `value`. | | targetSelectorType | `string` \| [Expression Type Object](#expression-type-object) | The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`). If `jsonpath`, then the `target` expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Expression Type Object](#expression-type-object) MUST be specified. | -| value | Any \| {expression} \| [Selector Object](#selector-object) | **REQUIRED**. The value set within the target location. The value can be a constant, a [Runtime Expression](#runtime-expressions), or [Selector Objects](#selector-object) to be evaluated and passed to the referenced operation or workflow. | +| value | Any \| {expression} \| [Selector Object](#selector-object) | **REQUIRED**. The value set within the target location. The value can be a constant, a [Runtime Expression](#runtime-expressions), or [Selector Objects](#selector-object) to be evaluated and passed to the referenced operation or workflow. | If `targetSelectorType` is omitted, then: @@ -1044,6 +1147,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org "$statusCode" / "$request." source / "$response." source / + "$message." source / "$inputs." inputs-reference / "$outputs." outputs-reference / "$steps." steps-reference / @@ -1054,11 +1158,12 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org ) ; Request/Response sources - source = ( header-reference / query-reference / path-reference / body-reference ) + source = ( header-reference / query-reference / path-reference / body-reference / payload-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" json-pointer ] + payload-reference = "payload" ["#" json-pointer ] ; Input/Output references inputs-reference = input-name [ "#" json-pointer ] @@ -1146,27 +1251,27 @@ The `name` identifier is case-sensitive, whereas `token` is not. #### Examples -| Source Location | example expression | notes | -| --- | :--- | :--- | -| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. | -| Requested media type | `$request.header.accept` | | -| Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. | -| Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. | -| Request URL | `$url` | | -| Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. | -| Response array element | `$response.body#/items/0/id` | Array elements can be accessed using numeric indices in JSON Pointer syntax. | -| Response header | `$response.header.Server` | Single header values only are available. | -| Self URI | `$self` | References the canonical URI of the current Arazzo Description as defined by the `$self` field. | -| Workflow input | `$inputs.username` | Single input values only are available. | -| Workflow input property | `$inputs.customer#/firstName` | To access nested properties within an input object, use JSON Pointer syntax. The input name is `customer`, and `#/firstName` is the JSON Pointer to the nested property. | -| Step output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body. | -| Step output deep nested | `$steps.fetchUser.outputs.data#/profile/address/postalCode` | JSON Pointers can traverse multiple levels to access deeply nested properties. | -| Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body. | -| Embedded expressions | `https://{$inputs.host}/api/{$steps.create.outputs.id}/status` | Multiple runtime expressions can be embedded within a single string value by wrapping each in curly braces. | -| Source description reference | `$sourceDescriptions.petstore.getPetById` | References an operationId or workflowId from the named source description. Resolution priority: (1) operationId/workflowId, (2) field names. | -| Source description field | `$sourceDescriptions.petstore.url` | References a field from the Source Description Object. Resolved when no matching operationId/workflowId is found. | -| Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. | -| Components action | `$components.successActions.bar` or `$components.failureActions.baz` | Accesses a success or failure action defined within the Components Object. | +| Source Location | example expression | notes | +|------------------------------|:---------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. | +| Requested media type | `$request.header.accept` | | +| Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. | +| Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. | +| Request URL | `$url` | | +| Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. | +| Response array element | `$response.body#/items/0/id` | Array elements can be accessed using numeric indices in JSON Pointer syntax. | +| Response header | `$response.header.Server` | Single header values only are available. | +| Message header | `$message.header.Server` | Single header values only are available. | +| Payload value | `$message.payload#/status` | In operations which return payloads, references may be made to portions of the payload or the entire payload. | +| Self URI | `$self` | References the canonical URI of the current Arazzo Description as defined by the `$self` field. | +| Workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available. | +| Step output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body. | +| Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body. | +| Embedded expressions | `https://{$inputs.host}/api/{$steps.create.outputs.id}/status` | Multiple runtime expressions can be embedded within a single string value by wrapping each in curly braces. | +| Source description reference | `$sourceDescriptions.petstore.getPetById` | References an operationId or workflowId from the named source description. Resolution priority: (1) operationId/workflowId, (2) field names. | +| Source description field | `$sourceDescriptions.petstore.url` | References a field from the Source Description Object. Resolved when no matching operationId/workflowId is found. | +| Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. | +| Components action | `$components.successActions.bar` or `$components.failureActions.baz` | Accesses a success or failure action defined within the Components Object. | Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. When a runtime expression is embedded in this manner, the following rules apply based on the value type: @@ -1184,7 +1289,7 @@ When using `$sourceDescriptions..`, the `` portion i - **operationId or workflowId** - If the referenced source description is an OpenAPI description, `` is first matched against operationIds. If the source description is an Arazzo document, `` is matched against workflowIds. - **Source description field** - If no operationId/workflowId match is found, `` is matched against field names of the Source Description Object (e.g., `url`, -`type`). + `type`). **Examples:** @@ -1211,9 +1316,9 @@ While the Arazzo Specification tries to accommodate most use cases, additional d The extension properties are implemented as patterned fields that are always prefixed by `"x-"`. -| Field Pattern | Type | Description | -| --- | :---: | --- | -| ^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. | +| Field Pattern | Type | Description | +|------------------------------------|:----:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. | The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). @@ -1287,10 +1392,11 @@ The proposed MIME media type for Arazzo documents (e.g. workflows) that require ## Appendix A: Revision History -| Version | Date | Notes | -| --- | --- | --- | -| 1.0.1 | 2025-01-16 | Patch release of the Arazzo Specification 1.0.1 | -| 1.0.0 | 2024-05-29 | First release of the Arazzo Specification | +| Version | Date | Notes | +|---------|------------|-------------------------------------------------| +| 1.1.0 | 2026-04-16 | Minor release of the Arazzo Specification 1.1.0 | +| 1.0.1 | 2025-01-16 | Patch release of the Arazzo Specification 1.0.1 | +| 1.0.0 | 2024-05-29 | First release of the Arazzo Specification | ## Appendix B: Examples of Base URI Determination and Reference Resolution diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index aa25f00..330dce0 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -82,6 +82,7 @@ $defs: enum: - arazzo - openapi + - asyncapi required: - name - url @@ -161,7 +162,12 @@ $defs: $comment: https://spec.openapis.org/arazzo/v1.1#step-object' description: |- Describes a single workflow step which MAY be a call to an - API operation (OpenAPI Operation Object or another Workflow Object) + API operation (OpenAPI Operation Object or AsyncAPI Operation Object or another Workflow Object) + oneOf: + - $ref: '#/$defs/openapi-step-object' + - $ref: '#/$defs/asyncapi-step-object' + - $ref: '#/$defs/workflow-step-object' + step-object-base: type: object properties: stepId: @@ -171,15 +177,22 @@ $defs: description: description: A description of the step. CommonMark syntax MAY be used for rich text representation type: string - operationId: - description: The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions - type: string - operationPath: - description: A reference to a Source combined with a JSON Pointer to reference an operation - type: string - workflowId: - description: The workflowId referencing an existing workflow within the Arazzo description - $ref: '#workflowId' + timeout: + description: The duration in milliseconds to wait before timing out the step + type: integer + dependsOn: + description: Specifies a list of step identifiers that must complete (or be waited for) before the current step can begin execution. `dependsOn` only establishes a prerequisite relationship for the current step and does not trigger execution of the referenced steps. Steps referred by dependsOn SHOULD be non-blocking/async steps. Steps in the current workflow MUST be referenced directly by stepId. Steps in another workflow in the same Arazzo document MUST use $workflows..steps.. Steps in another Arazzo document MUST use $sourceDescriptions...steps.. + type: array + uniqueItems: true + minItems: 1 + items: + oneOf: + - type: string + pattern: ^(?!\$).+$ + - type: string + pattern: ^\$workflows\.[^.]+\.steps\.[^.]+$ + - type: string + pattern: ^\$sourceDescriptions\.[^.]+\.[^.]+\.steps\.[^.]+$ parameters: description: A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId type: array @@ -222,44 +235,99 @@ $defs: - $ref: '#/$defs/selector-object' required: - stepId - oneOf: - - required: - - operationId - - required: - - operationPath - - required: - - workflowId + operation-step-parameters: + type: array + uniqueItems: true + items: + oneOf: + - $ref: '#/$defs/reusable-object' + - $ref: '#/$defs/parameter-object' + required: + - in + openapi-step-object: allOf: - - if: - oneOf: - - required: - - operationPath - - required: - - operationId - then: - properties: - parameters: - items: - oneOf: - - $ref: '#/$defs/reusable-object' - - $ref: '#/$defs/parameter-object' - required: - - in + - $ref: '#/$defs/step-object-base' + - type: object + properties: + operationId: + description: The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions + type: string + operationPath: + description: A reference to a Source combined with a JSON Pointer to reference an operation + type: string + parameters: + $ref: '#/$defs/operation-step-parameters' + - oneOf: + - required: + - operationId + - required: + - operationPath + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + asyncapi-step-object: + allOf: + - $ref: '#/$defs/step-object-base' + - type: object + properties: + operationId: + description: The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions + type: string + channelPath: + description: A reference to a Source combined with a JSON Pointer to reference an async channel + type: string + correlationId: + description: ID to correlate async responses with their requests, only specified for async receive steps + type: + - string + - number + - boolean + - object + - array + action: + description: Specifies the intended operation on the async channel, indicating whether the action is sending data to the channel or receiving data from the channel + enum: + - send + - receive + parameters: + $ref: '#/$defs/operation-step-parameters' + required: + - action - if: required: - - workflowId + - correlationId then: properties: - parameters: - items: - oneOf: - - $ref: '#/$defs/parameter-object' - - $ref: '#/$defs/reusable-object' + action: + const: receive + required: + - action + - oneOf: + - required: + - operationId + - required: + - channelPath + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + workflow-step-object: + allOf: + - $ref: '#/$defs/step-object-base' + - type: object + properties: + workflowId: + description: The workflowId referencing an existing workflow within the Arazzo description + $ref: '#workflowId' + parameters: + items: + oneOf: + - $ref: '#/$defs/parameter-object' + - $ref: '#/$defs/reusable-object' + required: + - workflowId $ref: '#/$defs/specification-extensions' unevaluatedProperties: false request-body-object: $comment: https://spec.openapis.org/arazzo/v1.1#request-body-object - description: The request body to pass to an operation as referenced by operationId or operationPath + description: The request body to pass to an operation as referenced by operationId or operationPath or channelPath type: object properties: contentType: @@ -292,7 +360,7 @@ $defs: description: The type of condition to be applied or a reference to an expression type object oneOf: - type: string - enum: + enum: - simple - regex - jsonpath @@ -335,10 +403,10 @@ $defs: then: properties: version: - enum: + enum: - rfc9535 - draft-goessner-dispatch-jsonpath-00 - + - if: required: - type @@ -361,7 +429,7 @@ $defs: then: properties: version: - const: rfc6901 + const: rfc6901 $ref: '#/$defs/specification-extensions' success-action-object: $comment: https://spec.openapis.org/arazzo/v1.1#success-action-object @@ -440,7 +508,7 @@ $defs: description: A list of parameters that MUST be passed to a workflow as referenced by workflowId type: array uniqueItems: true - items: true + items: true retryAfter: description: A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made type: number @@ -472,7 +540,7 @@ $defs: - parameters then: required: - - workflowId + - workflowId required: - name - type @@ -514,6 +582,7 @@ $defs: - querystring - header - cookie + - channel value: description: The value to pass in the parameter oneOf: @@ -523,7 +592,7 @@ $defs: - array - number - 'null' - - $ref: '#/$defs/selector-object' + - $ref: '#/$defs/selector-object' required: - name - value @@ -542,7 +611,7 @@ $defs: The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`). Should an alternate version be required, the Expression Type Object may be used instead. If omitted, defaults to JSON Pointer for `application/json` or XPath for XML-based media types. - $ref: '#/$defs/selector-type' + $ref: '#/$defs/selector-type' value: description: > The value to set at the location defined by the target. May be a literal, diff --git a/tests/schema/fail/channel-path-is-invalid-for-openapi.arazzo.yaml b/tests/schema/fail/channel-path-is-invalid-for-openapi.arazzo.yaml new file mode 100644 index 0000000..25bd0e5 --- /dev/null +++ b/tests/schema/fail/channel-path-is-invalid-for-openapi.arazzo.yaml @@ -0,0 +1,13 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/openapi.yaml + type: openapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + channelPath: createUser \ No newline at end of file diff --git a/tests/schema/fail/invalid-async-correlation-id-non-receive-action.arazzo.yaml b/tests/schema/fail/invalid-async-correlation-id-non-receive-action.arazzo.yaml new file mode 100644 index 0000000..2d69b4b --- /dev/null +++ b/tests/schema/fail/invalid-async-correlation-id-non-receive-action.arazzo.yaml @@ -0,0 +1,15 @@ +arazzo: 1.1.0 +info: + title: CorrelationId should only be present when action is receive + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + operationId: createUser + action: send + correlationId: invalid \ No newline at end of file diff --git a/tests/schema/fail/invalid-async-parameter-without-in.arazzo.yaml b/tests/schema/fail/invalid-async-parameter-without-in.arazzo.yaml new file mode 100644 index 0000000..0a12436 --- /dev/null +++ b/tests/schema/fail/invalid-async-parameter-without-in.arazzo.yaml @@ -0,0 +1,17 @@ +arazzo: 1.1.0 +info: + title: Async step parameter requires in + version: 1.0.0 +sourceDescriptions: + - name: eventAPI + url: https://events.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: asyncWorkflow + steps: + - stepId: sendEvent + operationId: $sourceDescriptions.eventAPI.orderCreated + action: send + parameters: + - name: correlationId + value: abc123 diff --git a/tests/schema/fail/invalid-async.arazzo.yaml b/tests/schema/fail/invalid-async.arazzo.yaml new file mode 100644 index 0000000..af42925 --- /dev/null +++ b/tests/schema/fail/invalid-async.arazzo.yaml @@ -0,0 +1,14 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + operationId: createUser + action: invalid diff --git a/tests/schema/fail/invalid-openapi-parameter-without-in.arazzo.yaml b/tests/schema/fail/invalid-openapi-parameter-without-in.arazzo.yaml new file mode 100644 index 0000000..2fae835 --- /dev/null +++ b/tests/schema/fail/invalid-openapi-parameter-without-in.arazzo.yaml @@ -0,0 +1,18 @@ +arazzo: 1.1.0 +info: + title: OpenAPI step parameter requires in + version: 1.0.0 +sourceDescriptions: + - name: userAPI + url: https://users.com/openapi.yaml + type: openapi +workflows: + - workflowId: openapiWorkflow + steps: + - stepId: getUsers + operationId: $sourceDescriptions.userAPI.listUsers + parameters: + - name: limit + value: 10 + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/fail/invalid-openapi-success-criteria.arazzo.yaml b/tests/schema/fail/invalid-openapi-success-criteria.arazzo.yaml new file mode 100644 index 0000000..0c2afaa --- /dev/null +++ b/tests/schema/fail/invalid-openapi-success-criteria.arazzo.yaml @@ -0,0 +1,14 @@ +arazzo: 1.1.0 +info: + title: Invalid OpenAPI step success criteria + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/openapi.yaml + type: openapi +workflows: + - workflowId: openapiWorkflow + steps: + - stepId: getUsers + operationId: listUsers + successCriteria: [] diff --git a/tests/schema/fail/invalid-workflow-step-with-operationId.arazzo.yaml b/tests/schema/fail/invalid-workflow-step-with-operationId.arazzo.yaml new file mode 100644 index 0000000..b7a6284 --- /dev/null +++ b/tests/schema/fail/invalid-workflow-step-with-operationId.arazzo.yaml @@ -0,0 +1,22 @@ +arazzo: 1.1.0 +info: + title: Workflow step cannot have operationId + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: parentWorkflow + steps: + - stepId: invalidStep + operationId: getUsers + workflowId: childWorkflow + successCriteria: + - condition: $statusCode == 200 + - workflowId: childWorkflow + steps: + - stepId: childStep + operationId: listUsers + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/fail/invalid-workflow-success-criteria.arazzo.yaml b/tests/schema/fail/invalid-workflow-success-criteria.arazzo.yaml new file mode 100644 index 0000000..5201af4 --- /dev/null +++ b/tests/schema/fail/invalid-workflow-success-criteria.arazzo.yaml @@ -0,0 +1,20 @@ +arazzo: 1.1.0 +info: + title: Invalid workflow step success criteria + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: parentWorkflow + steps: + - stepId: nestedWorkflow + workflowId: childWorkflow + successCriteria: [] + - workflowId: childWorkflow + steps: + - stepId: childStep + operationId: getUsers + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/pass/async-correlation-id-for-receive-action.arazzo.yaml b/tests/schema/pass/async-correlation-id-for-receive-action.arazzo.yaml new file mode 100644 index 0000000..a00b6df --- /dev/null +++ b/tests/schema/pass/async-correlation-id-for-receive-action.arazzo.yaml @@ -0,0 +1,15 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI with Correlation ID for Receive Action + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + operationId: createUser + action: receive + correlationId: id123 \ No newline at end of file diff --git a/tests/schema/pass/async-depends-on-across-document.arazzo.yaml b/tests/schema/pass/async-depends-on-across-document.arazzo.yaml new file mode 100644 index 0000000..950355c --- /dev/null +++ b/tests/schema/pass/async-depends-on-across-document.arazzo.yaml @@ -0,0 +1,29 @@ +arazzo: 1.1.0 +info: + title: Async dependsOn across documents + version: 1.0.0 +sourceDescriptions: + - name: localAsyncApi + url: https://example.com/local-asyncapi.yaml + type: asyncapi + - name: otherWorkflowDoc + url: https://example.com/other.arazzo.yaml + type: arazzo +workflows: + - workflowId: localWorkflow + steps: + - stepId: waitForLocalEvent + operationId: localReceive + action: receive + correlationId: id123 + timeout: 6000 + - stepId: useLocalDirectStepId + operationId: localSend + action: send + dependsOn: + - waitForLocalEvent + - stepId: useExternalWorkflowStep + operationId: localSend + action: send + dependsOn: + - $sourceDescriptions.otherWorkflowDoc.remoteWorkflow.steps.remoteReceive \ No newline at end of file diff --git a/tests/schema/pass/async-depends-on-cross-workflow.arazzo.yaml b/tests/schema/pass/async-depends-on-cross-workflow.arazzo.yaml new file mode 100644 index 0000000..29ac945 --- /dev/null +++ b/tests/schema/pass/async-depends-on-cross-workflow.arazzo.yaml @@ -0,0 +1,32 @@ +arazzo: 1.1.0 +info: + title: Async dependsOn across workflows in one document + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: producerWorkflow + steps: + - stepId: produceEvent + operationId: createUser + action: send + - stepId: waitForEvent + operationId: fetchUserId + action: receive + correlationId: id123 + timeout: 6000 + outputs: + userId: $message.payload.userId + - workflowId: consumerWorkflow + steps: + - stepId: processEvent + operationId: updateUser + action: send + dependsOn: + - $workflows.producerWorkflow.steps.waitForEvent + parameters: + - name: userId + in: header + value: $workflows.producerWorkflow.steps.waitForEvent.outputs.userId \ No newline at end of file diff --git a/tests/schema/pass/async-depends-on.arazzo.yaml b/tests/schema/pass/async-depends-on.arazzo.yaml new file mode 100644 index 0000000..8747abe --- /dev/null +++ b/tests/schema/pass/async-depends-on.arazzo.yaml @@ -0,0 +1,30 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI with Depends On + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: dependsOnWorkflow + steps: + - stepId: step1 + operationId: createUser + action: send + - stepId: step2 + operationId: fetchUserId + action: receive + correlationId: id123 + timeout: 6000 + outputs: + userId: $message.payload.userId + - stepId: step3 + operationId: updateUser + action: send + dependsOn: + - step2 + parameters: + - name: userId + in: header + value: $steps.step2.outputs.userId \ No newline at end of file diff --git a/tests/schema/pass/async-parameter-with-in.arazzo.yaml b/tests/schema/pass/async-parameter-with-in.arazzo.yaml new file mode 100644 index 0000000..fb15fd1 --- /dev/null +++ b/tests/schema/pass/async-parameter-with-in.arazzo.yaml @@ -0,0 +1,18 @@ +arazzo: 1.1.0 +info: + title: Async step parameter with in + version: 1.0.0 +sourceDescriptions: + - name: eventAPI + url: https://events.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: asyncWorkflow + steps: + - stepId: sendEvent + operationId: $sourceDescriptions.eventAPI.orderCreated + action: send + parameters: + - name: correlationId + in: header + value: abc123 diff --git a/tests/schema/pass/async-with-channel-path.arazzo.yaml b/tests/schema/pass/async-with-channel-path.arazzo.yaml new file mode 100644 index 0000000..161ae85 --- /dev/null +++ b/tests/schema/pass/async-with-channel-path.arazzo.yaml @@ -0,0 +1,15 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + channelPath: createUser + action: receive + correlationId: id123 \ No newline at end of file diff --git a/tests/schema/pass/asyncapi-success-criteria.arazzo.yaml b/tests/schema/pass/asyncapi-success-criteria.arazzo.yaml new file mode 100644 index 0000000..297eedf --- /dev/null +++ b/tests/schema/pass/asyncapi-success-criteria.arazzo.yaml @@ -0,0 +1,19 @@ +arazzo: 1.1.0 +info: + title: AsyncAPI step with success criteria + version: 1.0.0 +sourceDescriptions: + - name: UserAPI + url: https://user.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: asyncWorkflow + steps: + - stepId: receiveOrder + operationId: $sourceDescriptions.UserAPI.orderCreated + action: receive + correlationId: request-123 + successCriteria: + - context: $message.payload + condition: $.status == 'accepted' + type: jsonpath diff --git a/tests/schema/pass/minimal-async.arazzo.yaml b/tests/schema/pass/minimal-async.arazzo.yaml new file mode 100644 index 0000000..a9da527 --- /dev/null +++ b/tests/schema/pass/minimal-async.arazzo.yaml @@ -0,0 +1,14 @@ +arazzo: 1.1.0 +info: + title: Minimal Arazzo Example for AsyncAPI + version: 1.0.0 +sourceDescriptions: + - name: exampleAPI + url: https://example.com/asyncapi.yaml + type: asyncapi +workflows: + - workflowId: basicWorkflow + steps: + - stepId: step1 + operationId: createUser + action: send diff --git a/tests/schema/pass/openapi-and-asyncapi.arazzo.yaml b/tests/schema/pass/openapi-and-asyncapi.arazzo.yaml new file mode 100644 index 0000000..32c8a04 --- /dev/null +++ b/tests/schema/pass/openapi-and-asyncapi.arazzo.yaml @@ -0,0 +1,129 @@ +arazzo: 1.1.0 +info: + title: Arazzo Workflow + version: 1.1.0 +sourceDescriptions: +- name: LocationApi + url: ./workflow/openapi/location.yaml + type: openapi +- name: ProductApi + url: ./workflow/openapi/product.yaml + type: openapi +- name: AsyncOrderApi + url: ./workflow/asyncapi/order.yaml + type: asyncapi +- name: WarehouseApi + url: ./workflow/openapi/warehouse.yaml + type: openapi +- name: OrderApi + url: ./workflow/openapi/order.yaml + type: openapi +workflows: +- workflowId: OrderId + inputs: + required: + - createOrderSend + - getUserLocation + type: object + properties: + createOrderSend: + required: + - requestId + type: object + properties: + requestId: + type: string + getUserLocation: + required: + - userEmail + type: object + properties: + userEmail: + type: string + format: email + steps: + - stepId: getUserLocation + operationId: $sourceDescriptions.LocationApi.getUserLocation + parameters: + - name: userEmail + in: query + value: $inputs.getUserLocation.userEmail + successCriteria: + - condition: $statusCode == 200 + outputs: + userId: $response.body#/userId + locationCode: $response.body#/locationCode + - stepId: getProducts + operationId: $sourceDescriptions.ProductApi.getProducts + parameters: + - name: locationCode + in: query + value: $steps.getUserLocation.outputs.locationCode + successCriteria: + - condition: $statusCode == 200 + onSuccess: + - name: IsArrayEmpty + type: end + criteria: + - condition: $response.body#/0 == null + outputs: + productId: $response.body#/0/productId + inventory: $response.body#/0/inventory + - stepId: createOrderSend + operationId: $sourceDescriptions.AsyncOrderApi.createOrder + action: send + parameters: + - name: requestId + in: header + value: $inputs.createOrderSend.requestId + requestBody: + payload: + userId: $steps.getUserLocation.outputs.userId + productId: $steps.getProducts.outputs.productId + inventory: $steps.getProducts.outputs.inventory + outputs: + requestId: $message.header.requestId + - stepId: createOrderReceive + operationId: $sourceDescriptions.AsyncOrderApi.createOrder + action: receive + correlationId: $steps.createOrderSend.outputs.requestId + timeout: 6000 + outputs: + orderId: $message.payload.orderId + - stepId: reserveInventory + operationId: $sourceDescriptions.WarehouseApi.reserveInventory + dependsOn: + - createOrderReceive + parameters: + - name: orderId + in: query + value: $steps.createOrderReceive.outputs.orderId + successCriteria: + - condition: $statusCode == 200 + - stepId: orderAccepted + operationId: $sourceDescriptions.AsyncOrderApi.orderAccepted + action: receive + correlationId: $steps.createOrderSend.outputs.requestId + timeout: 6000 + - stepId: outForDelivery + operationId: $sourceDescriptions.AsyncOrderApi.outForDelivery + action: send + dependsOn: + - createOrderReceive + parameters: + - name: requestId + in: header + value: $steps.createOrderSend.outputs.requestId + requestBody: + payload: + orderId: $steps.createOrderReceive.outputs.orderId + - stepId: getOrderDetails + operationId: $sourceDescriptions.OrderApi.getOrderDetails + dependsOn: + - createOrderReceive + parameters: + - name: orderId + in: path + value: $steps.createOrderReceive.outputs.orderId + successCriteria: + - condition: $statusCode == 200 \ No newline at end of file diff --git a/tests/schema/pass/openapi-parameter-with-in.arazzo.yaml b/tests/schema/pass/openapi-parameter-with-in.arazzo.yaml new file mode 100644 index 0000000..3224b51 --- /dev/null +++ b/tests/schema/pass/openapi-parameter-with-in.arazzo.yaml @@ -0,0 +1,19 @@ +arazzo: 1.1.0 +info: + title: OpenAPI step parameter with in + version: 1.0.0 +sourceDescriptions: + - name: userAPI + url: https://users.com/openapi.yaml + type: openapi +workflows: + - workflowId: openapiWorkflow + steps: + - stepId: getUsers + operationId: $sourceDescriptions.userAPI.listUsers + parameters: + - name: limit + in: query + value: 10 + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/pass/openapi-success-criteria.arazzo.yaml b/tests/schema/pass/openapi-success-criteria.arazzo.yaml new file mode 100644 index 0000000..f388681 --- /dev/null +++ b/tests/schema/pass/openapi-success-criteria.arazzo.yaml @@ -0,0 +1,15 @@ +arazzo: 1.1.0 +info: + title: OpenAPI step with success criteria + version: 1.0.0 +sourceDescriptions: + - name: UserAPI + url: https://users.com/openapi.yaml + type: openapi +workflows: + - workflowId: openapiWorkflow + steps: + - stepId: getUsers + operationId: $sourceDescriptions.userAPI.listUsers + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/pass/workflow-parameter-without-in.arazzo.yaml b/tests/schema/pass/workflow-parameter-without-in.arazzo.yaml new file mode 100644 index 0000000..21749a8 --- /dev/null +++ b/tests/schema/pass/workflow-parameter-without-in.arazzo.yaml @@ -0,0 +1,27 @@ +arazzo: 1.1.0 +info: + title: Workflow step parameter does not require in + version: 1.0.0 +sourceDescriptions: + - name: userAPI + url: https://users.com/openapi.yaml + type: openapi +workflows: + - workflowId: parentWorkflow + steps: + - stepId: nestedWorkflow + workflowId: childWorkflow + parameters: + - name: userId + value: 10 + - workflowId: childWorkflow + inputs: + type: object + properties: + userId: + type: integer + steps: + - stepId: childStep + operationId: $sourceDescriptions.userAPI.listUsers + successCriteria: + - condition: $statusCode == 200 diff --git a/tests/schema/pass/workflow-success-criteria.arazzo.yaml b/tests/schema/pass/workflow-success-criteria.arazzo.yaml new file mode 100644 index 0000000..d496331 --- /dev/null +++ b/tests/schema/pass/workflow-success-criteria.arazzo.yaml @@ -0,0 +1,25 @@ +arazzo: 1.1.0 +info: + title: Valid workflow step success criteria + version: 1.0.0 +sourceDescriptions: + - name: UserAPI + url: https://users.com/openapi.yaml + type: openapi +workflows: + - workflowId: parentWorkflow + steps: + - stepId: nestedWorkflow + workflowId: childWorkflow + successCriteria: + - condition: $workflows.childWorkflow.outputs.userId > 0 + - workflowId: childWorkflow + steps: + - stepId: childStep + operationId: $sourceDescriptions.userAPI.listUsers + outputs: + userId: $response.body#/id + successCriteria: + - condition: $statusCode == 200 + outputs: + userId: $steps.childStep.outputs.userId