diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..94085bc --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json index dfda620..5de4be9 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,5 +1,6 @@ { "cSpell.words": [ - "ruleset" + "ruleset", + "Templating" ] } \ No newline at end of file diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.workflow.yaml index 20d0c3c..59949dc 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/examples/1.0.0/FAPI-PAR.workflow.yaml @@ -4,7 +4,7 @@ info: version: 1.0.0 description: >- A workflow describing how to obtain a token from an OAuth2 and OpenID Connect Financial Grade authorization server which can be common for PSD2 API journeys -sourceDocuments: +sourceDescriptions: - name: auth-api url: ./FAPI-PAR.openapi.yaml type: openapi diff --git a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml index 7ae0e3c..738352e 100644 --- a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml @@ -5,8 +5,8 @@ info: description: | This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 -sourceDocuments: -- name: petStoreDefinition +sourceDescriptions: +- name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi @@ -24,7 +24,7 @@ workflows: steps: - stepId: loginStep description: This step demonstrates the user login step - operationId: petStoreDefinition.loginUser + operationId: 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 diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index 4308582..79fb7ca 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.workflow.yaml @@ -4,7 +4,7 @@ info: version: 1.0.0 description: >- APImetrics OAuth service -sourceDocuments: +sourceDescriptions: - name: apim-auth url: ./oauth.openapi.yaml type: openapi diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 4650907..12dbef7 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -6,7 +6,7 @@ info: Illustrates a workflow whereby a client a) finds a pet in the petstore, b) finds coupons for that pet, and finally c) orders the pet while applying the coupons from step b. -sourceDocuments: +sourceDescriptions: - name: pet-coupons url: ./pet-coupons.openapi.yaml type: openapi diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 10cc93a..7ef924d 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -8,9 +8,9 @@ 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 an API definition(s). 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 definitions (such as OpenAPI documents). +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 an 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). -The Workflows Specification can articulate these workflows in a human and machine-readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improved the consuming developer experience. +The Workflows Specification can articulate these workflows in a human 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 @@ -20,11 +20,11 @@ The Workflows Specification can articulate these workflows in a human and machin - [Introduction](#introduction) - [Table of Contents](#table-of-contents) - [Definitions](#definitions) - - [Workflows Document](#workflows-document) + - [Workflows Description](#workflows-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - - [Document Structure](#document-structure) + - [Workflows Description Structure](#workflows-description-structure) - [Data Types](#data-types) - [Relative References in URLs](#relative-references-in-urls) - [Schema](#schema) @@ -34,9 +34,9 @@ The Workflows Specification can articulate these workflows in a human and machin - [Info Object](#info-object) - [Fixed Fields](#fixed-fields-1) - [Info Object Example](#info-object-example) - - [Source Document Object](#source-document-object) + - [Source Description Object](#source-description-object) - [Fixed Fields](#fixed-fields-2) - - [Source Document Object Example](#source-document-object-example) + - [Source Description Object Example](#source-description-object-example) - [Workflow Object](#workflow-object) - [Fixed Fields](#fixed-fields-3) - [Workflow Object Example](#workflow-object-example) @@ -68,8 +68,8 @@ The Workflows Specification can articulate these workflows in a human and machin ## Definitions -##### Workflows Document -A self-contained or composite resource which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). The workflows document `MUST` contain a valid Workflows Specification version field (`workflowsSpec`), an [Info](#info-object) field, a `sourceDocuments` field with at least one defined [Source](#source-document-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the workflows fixed field. A Workflows document uses and conforms to the Workflows Specification. +##### 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. ## Specification @@ -79,7 +79,7 @@ The Workflows Specification is versioned using a `major`.`minor`.`patch` version ### Format -A Workflows document that conforms to the Workflows Specification is itself a JSON object, which may be represented either in JSON or YAML 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. 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**. @@ -89,9 +89,11 @@ 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). -### Document Structure +### Workflows Description Structure -It is RECOMMENDED that the root Workflows document be named: `workflows.json` or `workflows.yaml`. +It is RECOMMENDED that the entry Workflows document be named: `workflows.json` or `workflows.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. In the latter case, [`Reference Objects`](#reference-object) `$ref` keywords are used. In a multi-document description, the document containing the [Workflows Specification Object](#workflows-specification-object) is known as the **entry Workflows document**. ### Data Types @@ -120,17 +122,17 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### Workflows Specification Object -This is the root object of the [Workflows document](#workflows-document). +This is the root object of the [Workflows Description](#workflows-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 document uses. The `workflowsSpec` field SHOULD be used by tooling to interpret the Workflows document. +workflowsSpec | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Workflows Specification that the Workflows Description uses. The `workflowsSpec` field SHOULD 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. -sourceDocuments | [[Source Document Object](#source-document-object)] | **REQUIRED**. A list of source documents (such as an OpenAPI document) this workflow SHALL apply to. The list MUST have at least one entry. +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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. -components | [Component Object](#component-object) | An element to hold various schemas for the document. +components | [Component Object](#component-object) | An element to hold various schemas for the Workflows Description. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -144,8 +146,8 @@ info: description: | This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 -sourceDocuments: -- name: petStoreDefinition +sourceDescriptions: +- name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi @@ -209,10 +211,10 @@ The metadata MAY be used by the clients if needed. Field Name | Type | Description ---|:---:|--- -title | `string` | **REQUIRED**. A human readable title of the Workflows document. -summary | `string` | A short summary of the Workflows document. -description | `string` | A description of the purpose of the Workflows document. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -version | `string` | **REQUIRED**. A version identifier for indicating changes to the Workflows document (which is distinct from the [Workflows Specification version](#versions). +title | `string` | **REQUIRED**. A human readable title of the Workflows Description. +summary | `string` | A short summary of the Workflows 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**. A version identifier for indicating changes to the Workflows Description (which is distinct from the [Workflows Specification version](#versions). This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -227,27 +229,27 @@ description: | version: 1.0.1 ``` -#### Source Document Object +#### Source Description Object -Describes a source document (such as an OpenAPI document) that will be referenced by one or more workflows described within a Workflows document. +Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within a Workflows Description. -An object storing a map between named document keys and location URLs to the source documents (such as an OpenAPI document) this workflow SHALL apply to. Each source location `string` MUST be in the form of a [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986). +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 [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. A unique name for the source document. Tools and libraries MAY use the `name` to uniquely identify a source document, 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 document to be used by a Workflow. MUST be in the form of a [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986). -type | `string` | The type of source document. Possible values are `"openapi"` or `"workflowsSpec"`. +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. MUST be in the form of a [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986). +type | `string` | The type of source description. Possible values are `"openapi"` or `"workflowsSpec"`. This object MAY be extended with [Specification Extensions](#specification-extensions). -##### Source Document Object Example +##### Source Description Object Example ```yaml -name: petStoreDefinition +name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` @@ -260,7 +262,7 @@ 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 document. 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 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_\-]+`. 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. @@ -315,9 +317,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 id SHOULD 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 `source` documents. The referenced operation will be invoked by this workflow step. If more than one (non `workflowsSpec` type) `source` document is defined within a Workflows document, then the `operationId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively. -operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used. The operation being referenced MUST be described within one of the `source` documents. -workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. If more than one `workflowsSpec` type `source` document is defined within a Workflows document, then the `workflowId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively. +operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `source` descriptions. The referenced operation will be invoked by this workflow step. If more than one (non `workflowsSpec` type) `source` description is defined within a Workflows Description, then the `operationId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively. +operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) SHOULD be used. The operation being referenced MUST be described within one of the `source` descriptions. +workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows Description. If more than one `workflowsSpec` type `source` description is defined within a Workflows Description, then the `workflowId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively. parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#component-object). dependsOn | [`string`] | A list of steps that MUST be completed before this step can be processed. This helps to ensure workflow steps are executed in the correct order and that dependent steps are not processed in parallel. The values provided MUST be the be the `stepId` which uniquely references a step. 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. @@ -461,7 +463,7 @@ A single success action which describes an action to take upon success of a work Field Name | Type | Description ---|:---:|--- 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 document to transfer to upon success of the step. This field is only relevant when the `type` field value is `goto`. If more than one `workflowsSpec` type `source` document is defined within a Workflows document, then the `workflowId` specified MUST be prefixed with the source name 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 Workflows Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `goto`. If more than one `workflowsSpec` type `source` description is defined within a Workflows Description, then the `workflowId` specified MUST be prefixed with the source name 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` SHOULD 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. @@ -493,7 +495,7 @@ A single failure action which describes an action to take upon failure of a work Field Name | Type | Description ---|:---:|--- 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 document to transfer to upon failure of the step. This field is only relevant when the `type` field value is `goto` or `retry`. If more than one `workflowsSpec` type `source` document is defined within a Workflows document, then the `workflowId` specified MUST be prefixed with the source name 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 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 more than one `workflowsSpec` type `source` description is defined within a Workflows Description, then the `workflowId` specified MUST be prefixed with the source name 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` SHOULD 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 milliseconds 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. @@ -528,7 +530,7 @@ Field Name | Type | Description This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). -All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow document. +All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow Description. Field Name Examples: @@ -590,7 +592,7 @@ components: #### Reference Object -A simple object to allow referencing other components in the Workflows document. +A simple object to allow referencing other components in the Workflows Description. **Note -** This section is derived from the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion.