From 92f574ea0199eaee112fc8380d19c51e42dae04f Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 22 May 2024 17:03:43 +0100 Subject: [PATCH] update specification to take care of Arazzo (Tapestry) name change. (#189) * update specification to take care of Arazzo (Tapestry) name change. * chore: remove `prerelease` from examples --- ... => ExtendedParametersExample.arazzo.yaml} | 2 +- ...PAR.workflow.yaml => FAPI-PAR.arazzo.yaml} | 2 +- ....yaml => LoginAndRetrievePets.arazzo.yaml} | 2 +- ...{oauth.workflow.yaml => oauth.arazzo.yaml} | 6 +- ....workflow.yaml => pet-coupons.arazzo.yaml} | 2 +- versions/1.0.0.md | 153 +++++++++--------- 6 files changed, 79 insertions(+), 88 deletions(-) rename examples/1.0.0/{ExtendedParametersExample.workflow.yaml => ExtendedParametersExample.arazzo.yaml} (96%) rename examples/1.0.0/{FAPI-PAR.workflow.yaml => FAPI-PAR.arazzo.yaml} (96%) rename examples/1.0.0/{LoginAndRetrievePets.workflow.yaml => LoginAndRetrievePets.arazzo.yaml} (95%) rename examples/1.0.0/{oauth.workflow.yaml => oauth.arazzo.yaml} (98%) rename examples/1.0.0/{pet-coupons.workflow.yaml => pet-coupons.arazzo.yaml} (99%) diff --git a/examples/1.0.0/ExtendedParametersExample.workflow.yaml b/examples/1.0.0/ExtendedParametersExample.arazzo.yaml similarity index 96% rename from examples/1.0.0/ExtendedParametersExample.workflow.yaml rename to examples/1.0.0/ExtendedParametersExample.arazzo.yaml index f811c8f..b4b8ee0 100644 --- a/examples/1.0.0/ExtendedParametersExample.workflow.yaml +++ b/examples/1.0.0/ExtendedParametersExample.arazzo.yaml @@ -1,4 +1,4 @@ -workflowsSpec: 1.0.0 +arazzo: 1.0.0 info: title: Public Zoo API version: '1.0' diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.arazzo.yaml similarity index 96% rename from examples/1.0.0/FAPI-PAR.workflow.yaml rename to examples/1.0.0/FAPI-PAR.arazzo.yaml index 61c6c36..6dc87e9 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/examples/1.0.0/FAPI-PAR.arazzo.yaml @@ -1,4 +1,4 @@ -workflowsSpec: 1.0.0-prerelease +arazzo: 1.0.0 info: title: PAR, Authorization and Token workflow version: 1.0.0 diff --git a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml b/examples/1.0.0/LoginAndRetrievePets.arazzo.yaml similarity index 95% rename from examples/1.0.0/LoginAndRetrievePets.workflow.yaml rename to examples/1.0.0/LoginAndRetrievePets.arazzo.yaml index ffa459c..227d9bb 100644 --- a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.arazzo.yaml @@ -1,4 +1,4 @@ -workflowsSpec: 1.0.0-prerelease +arazzo: 1.0.0 info: title: A pet purchasing workflow summary: This workflow showcases how to purchase a pet through a sequence of API calls diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.arazzo.yaml similarity index 98% rename from examples/1.0.0/oauth.workflow.yaml rename to examples/1.0.0/oauth.arazzo.yaml index 4af50a8..a9e39e4 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.arazzo.yaml @@ -1,4 +1,4 @@ -workflowsSpec: 1.0.0-prerelease +arazzo: 1.0.0 info: title: Example OAuth service version: 1.0.0 @@ -10,8 +10,8 @@ sourceDescriptions: type: openapi # This is how you can reference another workflow file # - name: sample - # url: ./sample.workflows.yml - # type: workflowSpec + # url: ./sample.arazzo.yml + # type: arazzo workflows: - workflowId: refresh-token-flow diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.arazzo.yaml similarity index 99% rename from examples/1.0.0/pet-coupons.workflow.yaml rename to examples/1.0.0/pet-coupons.arazzo.yaml index 94dfb04..40ac72a 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.arazzo.yaml @@ -1,4 +1,4 @@ -workflowsSpec: 1.0.0-prerelease +arazzo: 1.0.0 info: title: Petstore - Apply Coupons version: 1.0.0 diff --git a/versions/1.0.0.md b/versions/1.0.0.md index fb265ef..4e24e86 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -1,8 +1,6 @@ -# Workflows Specification +# Arazzo Specification -## Version 1.0.0-prerelease - -> _Work is progressing well on this specification. Formally, we are still in a **prerelease** status_ +## Version 1.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -10,29 +8,29 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of API descriptions. The aim of the Workflows Specification is to provide a mechanism that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions). +Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of API descriptions. The aim of the Arazzo Specification is to provide a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions). -The Workflows Specification can articulate these workflows in a human-readable and machine-readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience. +The Arazzo Specification can articulate these workflows in a human-readable and machine-readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience. ## Table of Contents -- [Workflows Specification](#workflows-specification) - - [Version 1.0.0-prerelease](#version-100-prerelease) +- [Arazzo Specification](#arazzo-specification) + - [Version 1.0.0](#version-100) - [Introduction](#introduction) - [Table of Contents](#table-of-contents) - [Definitions](#definitions) - - [Workflows Description](#workflows-description) + - [Arazzo Description](#arazzo-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - - [Workflows Description Structure](#workflows-description-structure) + - [Arazzo Description Structure](#arazzo-description-structure) - [Data Types](#data-types) - [Relative References in URLs](#relative-references-in-urls) - [Schema](#schema) - - [Workflows Specification Object](#workflows-specification-object) + - [Arazzo Specification Object](#arazzo-specification-object) - [Fixed Fields](#fixed-fields) - - [Workflows Specification Object Example](#workflows-specification-object-example) + - [Arazzo Specification Object Example](#arazzo-specification-object-example) - [Info Object](#info-object) - [Fixed Fields](#fixed-fields-1) - [Info Object Example](#info-object-example) @@ -74,23 +72,22 @@ The Workflows Specification can articulate these workflows in a human-readable a - [Security Considerations](#security-considerations) - [IANA Considerations](#iana-considerations) - [Appendix A: Revision History](#appendix-a-revision-history) - - [Appendix B: Contextual Scope Overview](#appendix-b-contextual-scope--access-for-inputs-and-outputs) ## Definitions -### Workflows Description -A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). A Workflows Description (WD) uses and conforms to the Workflows Specification, and `MUST` contain a valid Workflows Specification version field (`workflowsSpec`), an [Info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. +### Arazzo Description +A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [Info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification ### Versions -The Workflows Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Workflows feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. +The Arazzo Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Arazzo feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. ### Format -A Workflows Description that conforms to the Workflows Specification is itself a JSON object, which may be represented either in JSON or YAML format. +An Arazzo Description that conforms to the Arazzo Specification is itself a JSON object, which may be represented either in JSON or YAML format. All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. @@ -100,17 +97,17 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). -### Workflows Description Structure +### Arazzo Description Structure -It is RECOMMENDED that the entry Workflows document be named: `workflows.json` or `workflows.yaml`. +It is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`. -A Workflows Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they must by included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Workflows Specification Object](#workflows-specification-object) is known as the **entry Workflows document**. +An Arazzo Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they must by included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Arazzo Specification Object](#arazzo-specification-object) is known as the **entry Arazzo document**. ### Data Types -Data types in the Workflows Specification are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. +Data types in the Arazzo Specification are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. -As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7), data types can have an optional modifier property: `format`. Workflows additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types. +As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7), data types can have an optional modifier property: `format`. Arazzo additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types. The formats defined are: [`type`](#data-types) | `format` | Comments @@ -131,31 +128,31 @@ Unless specified otherwise, relative references are resolved using the URL of th In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. -#### Workflows Specification Object +#### Arazzo Specification Object -This is the root object of the [Workflows Description](#workflows-description). +This is the root object of the [Arazzo Description](#arazzo-description). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -workflowsSpec | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Workflows Specification that the Workflows Description uses. The `workflowsSpec` field MUST be used by tooling to interpret the Workflows Description. -info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. 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 workflow SHALL apply to. The list MUST have at least one entry. +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. +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 Workflows Description. +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). -##### Workflows Specification Object Example +##### Arazzo Specification Object Example ```yaml -workflowsSpec: 1.0.0-prerelease +arazzo: 1.0.0 info: title: A pet purchasing workflow - summary: This workflow showcases how to purchase a pet through a sequence of API calls + summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls description: | - This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. + This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sourceDescriptions: - name: petStoreDescription @@ -214,17 +211,17 @@ workflows: #### Info Object -The object provides metadata about the API Workflows defined in this document. +The object provides metadata about API workflows defined in this Arazzo document. 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 Workflows Description. -summary | `string` | A short summary of the Workflows 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 Workflows document (which is distinct from the [Workflows 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). @@ -241,17 +238,17 @@ version: 1.0.1 #### Source Description Object -Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within a Workflows Description. +Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description. -An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this workflow SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986 section 4.1](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1). +An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986 section 4.1](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1). ##### Fixed Fields 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 section 4.2](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2). -type | `string` | The type of source description. Possible values are `"openapi"` or `"workflowsSpec"`. +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 section 4.2](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2). +type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -272,16 +269,16 @@ Describes the steps to be taken across one or more APIs to achieve an objective. Field Name | Type | Description ---|:---:|--- -workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows 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_\-]+`. +workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe 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. The values 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 Workflows 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. +dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values 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 Workflows 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 Workflows document. The list MUST NOT include duplicate failure actions. +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}] | A map between a friendly name and a dynamic output value. 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 Workflows document. The list MUST NOT include duplicate parameters. +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). @@ -332,14 +329,14 @@ 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 `workflowsSpec` 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. +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](#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 Workflows Description. If multiple `workflowsSpec` type `sourceDescriptions` are defined, 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 Workflows document. The list MUST NOT include duplicate parameters. +workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, 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 [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and 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 Workflows 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 Workflows document. The list MUST NOT include duplicate failure actions. +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}] | A map between a friendly name and a dynamic output value defined using a [runtime expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -454,7 +451,7 @@ 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 Workflows Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `workflowsSpec` type `sourceDescriptions` are defined, 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`. + 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 multiple `arazzo` type `sourceDescriptions` are defined, 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`. 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. @@ -487,7 +484,7 @@ 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 Workflows Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `workflowsSpec` type `sourceDescriptions` are defined, 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. + 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 multiple `arazzo` type `sourceDescriptions` are defined, 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. 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://www.rfc-editor.org/rfc/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"` or `"function"`. 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. @@ -510,9 +507,9 @@ criteria: #### Components Object -Holds a set of reusable objects for different aspects of the Workflows Specification. All objects defined within the components object will have no effect on the workflow unless they are explicitly referenced from properties outside the components object. +Holds a set of reusable objects for different aspects of the Arazzo Specification. All objects defined within the components object will have no effect on the Arazzo Description unless they are explicitly referenced from properties outside the components object. -Components are scoped to the Workflows document they are defined in. For example, if a step defined in Workflows document "A" references a workflow defined in Workflows document "B", the components in "A" are not considered when evaluating the workflow referenced in "B". +Components are scoped to the Arazzo document they are defined in. For example, if a step defined in Arazzo document "A" references a workflow defined in Arazzo document "B", the components in "A" are not considered when evaluating the workflow referenced in "B". ##### Fixed Fields @@ -612,7 +609,7 @@ components: #### Reusable Object -A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Workflows Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism. +A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Arazzo Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism. ##### Fixed Fields @@ -650,10 +647,11 @@ This object cannot be extended with additional properties and any properties add An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`. -There are three flavors of conditions supported: +There are four flavors of conditions supported: - simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions). - regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions). -- JSONPath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). +- jsonpath - where a JSON Path expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). +- xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). ##### Literals As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. @@ -721,7 +719,7 @@ An object used to describe the type and version of an expression used within a [ - JSON Path as described by [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html) - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31) -Defining this object gives the ability to utilize tooling compatible with older versions of either JSON Path or XPath. +Defining this object gives the ability to utilize tooling compatible with older versions of either JSON Path or XPath. ##### Fixed Fields Field Name | Type | Description @@ -851,7 +849,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ### Runtime Expressions -A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Workflows document such as [workflows](#workflow-object) or [steps](#step-object). +A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: @@ -897,31 +895,31 @@ Expressions can be embedded into string values by surrounding the expression wit ### Specification Extensions -While the Workflows Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. +While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extension properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- -^x- | Any | Allows extensions to the Workflows Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` 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. +^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). ## Security Considerations -The Workflows Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows. +The Arazzo Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows. -Workflows can be JSON or YAML values. As such, all security considerations defined in [RFC 8259](https://www.rfc-editor.org/info/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply. +Arazzo Descriptions can be JSON or YAML values. As such, all security considerations defined in [RFC 8259](https://www.rfc-editor.org/info/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply. -Workflows are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing a workflow description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful. +Arazzo Descriptions are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing an Arazzo Description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful. ## IANA Considerations -The proposed MIME media types for Workflows are described below. +The proposed MIME media types for the Arazzo Specification are described below. ### application/vnd.oai.workflows -The default (or general) MIME type for Workflows is defined as follows: +The default (or general) MIME type for Arazzo documents (e.g. workflows) is defined as follows:   Media type name: application @@ -929,7 +927,7 @@ The default (or general) MIME type for Workflows is defined as follows:   Required parameters: N/A -  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification). +  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` and `application/yaml` media types, respectively. @@ -941,7 +939,7 @@ The default (or general) MIME type for Workflows is defined as follows: ### application/vnd.oai.workflows+json -The proposed MIME media type for Workflows that require a JSON-specific media type is defined as follows: +The proposed MIME media type for Arazzo documents (e.g. workflows) that require a JSON-specific media type is defined as follows:   Media type name: application @@ -949,7 +947,7 @@ The proposed MIME media type for Workflows that require a JSON-specific media ty   Required parameters: N/A -  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification). +  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` media type. @@ -959,7 +957,7 @@ The proposed MIME media type for Workflows that require a JSON-specific media ty ### application/vnd.oai.workflows+yaml -The proposed MIME media type for Workflows that require a YAML-specific media type is defined as follows: +The proposed MIME media type for Arazzo documents (e.g. workflows) that require a YAML-specific media type is defined as follows:   Media type name: application @@ -967,7 +965,7 @@ The proposed MIME media type for Workflows that require a YAML-specific media ty   Required parameters: N/A -  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification). +  Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/yaml` media type. @@ -977,13 +975,6 @@ The proposed MIME media type for Workflows that require a YAML-specific media ty ## Appendix A: Revision History -Version | Date | Notes ---- | --- | --- -1.0.0 | TBD | **Not yet released** - - -## Appendix B: Contextual scope / access for inputs and outputs - -This quick image is to add some context / scope access overview for `inputs`, `step parameters`, `step outputs` and `workflow outputs` - -![Contextual Access Scope](./SupportingImages/Workflows-Access-Scope-for-Inputs-and-Outputs.png) +Version | Date | Notes +--- | --- | --- +1.0.0 | 2024-05-29 | First release of the Arazzo Specification \ No newline at end of file