From 1e74716b3c137765f1c8b987ef547dd36981c0a0 Mon Sep 17 00:00:00 2001 From: kevinduffey Date: Fri, 1 Mar 2024 14:13:31 -0800 Subject: [PATCH 1/7] Added README to provide details on existing examples and provide additional example ideas to be added (#151) Co-authored-by: Kevin Duffey --- examples/1.0.0/README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 examples/1.0.0/README.md diff --git a/examples/1.0.0/README.md b/examples/1.0.0/README.md new file mode 100644 index 0000000..3b3a138 --- /dev/null +++ b/examples/1.0.0/README.md @@ -0,0 +1,23 @@ +# Workflows Specification Examples + +## Purpose + +This README will provide details on the examples found in this directory as well as examples to be added to cover a +variety of use case scenarios. + +## Examples + +### FAPI +*needs description* + +### OAuth +*needs description* + +### Pet Coupons +*needs description* + +## Examples to be added + +* An example where a workflow imports another workflow both of which have components defined to show that the entry/root + workflow can not reference components defined in the imported workflow. Components are scoped to the workflow they + are defined in. From fcaae482f95d35258444965e4a19716024caa6be Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 13 Mar 2024 16:23:06 +0000 Subject: [PATCH 2/7] Chore: fix `pet-coupons.workflow.yaml` example (#158) --- examples/1.0.0/pet-coupons.workflow.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 8a23e11..1fed0cd 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -161,10 +161,10 @@ components: description: Indicates the domain name of the store where the customer is browsing or buying pets, e.g. "pets.example.com" or "pets.example.co.uk". parameters: page: + name: page in: query - type: integer - format: int32 + value: 1 pageSize: + name: pageSize in: query - type: integer - format: int32 + value: 100 From 3ec4dc0dc0d0aa9993a81f1d70fe78ea74c330a6 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 13 Mar 2024 16:24:47 +0000 Subject: [PATCH 3/7] feat: remove support for `dependsOn` for v1.0.0 (#159) --- examples/1.0.0/LoginAndRetrievePets.workflow.yaml | 1 - versions/1.0.0.md | 2 -- 2 files changed, 3 deletions(-) diff --git a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml index e3e59f7..ffa459c 100644 --- a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml @@ -44,7 +44,6 @@ workflows: - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: $sourceDescriptions.petStoreDescription#/paths/~1pet~1findByStatus - dependsOn: loginStep parameters: - name: status in: query diff --git a/versions/1.0.0.md b/versions/1.0.0.md index a8a7683..be57c15 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -190,7 +190,6 @@ workflows: - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get' - dependsOn: loginStep parameters: - name: status in: query @@ -326,7 +325,6 @@ Field Name | Type | Description 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) \| [Reference Object](#reference-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-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. onSuccess | [[Success Action Object](#success-action-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. onFailure | [[Failure Action Object](#failure-action-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. From 6e2769f44b9f51ad77797f5ea5c0507a5e2644a9 Mon Sep 17 00:00:00 2001 From: Dmytro Anansky Date: Wed, 27 Mar 2024 18:42:13 +0200 Subject: [PATCH 4/7] chore: suggest multilevel parameters (#155) * chore: suggest multilevel parameters * Update versions/1.0.0.md Co-authored-by: Frank Kilcommins * Update examples/1.0.0/ExtendedParametersExample.workflow.yaml Co-authored-by: Frank Kilcommins * Update versions/1.0.0.md Co-authored-by: Frank Kilcommins --------- Co-authored-by: Frank Kilcommins --- .../ExtendedParametersExample.workflow.yaml | 26 +++++++++++++++++++ versions/1.0.0.md | 2 ++ 2 files changed, 28 insertions(+) create mode 100644 examples/1.0.0/ExtendedParametersExample.workflow.yaml diff --git a/examples/1.0.0/ExtendedParametersExample.workflow.yaml b/examples/1.0.0/ExtendedParametersExample.workflow.yaml new file mode 100644 index 0000000..f811c8f --- /dev/null +++ b/examples/1.0.0/ExtendedParametersExample.workflow.yaml @@ -0,0 +1,26 @@ +workflowsSpec: 1.0.0 +info: + title: Public Zoo API + version: '1.0' +sourceDescriptions: + - name: animals + type: openapi + url: ./animals.yaml +workflows: + - workflowId: animal-workflow + parameters: + - in: cookie + name: workflowLevelParamOne + value: someValue + - in: header + name: workflowLevelParamTwo + value: someValue + steps: + - stepId: post-step + parameters: + - in: cookie + name: authentication + value: SUPER_SECRET + operationId: animals.postAnimal + - stepId: get-step + operationId: animals.getRandomAnimal \ No newline at end of file diff --git a/versions/1.0.0.md b/versions/1.0.0.md index be57c15..1b04022 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -272,6 +272,8 @@ Field Name | Type | Description inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. 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. 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) \| [Reference Object](#reference-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 Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters. + This object MAY be extended with [Specification Extensions](#specification-extensions). From 450ca6e8f4a8cdf4fc81ed33a51ddc56f3490e5f Mon Sep 17 00:00:00 2001 From: Nick Denny Date: Thu, 28 Mar 2024 14:09:52 -0700 Subject: [PATCH 5/7] Remove references to WHATWG to avoid confusion (#145) * Remove references to WHATWG to avoid confusion * Correct relative reference wording * Section 4.2 not 4.1! * Simplify URI wording --- versions/1.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 1b04022..0f71c44 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -237,14 +237,14 @@ version: 1.0.1 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 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). +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). ##### 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. 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). +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"`. From f1babd766578ca1f281ecd4276ea7a332d739109 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Thu, 28 Mar 2024 21:27:34 +0000 Subject: [PATCH 6/7] Adjust Step Parameters desc to cater for Workflow parameters addition (#169) --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 0f71c44..03f283a 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -326,7 +326,7 @@ Field Name | Type | Description 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. 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) \| [Reference Object](#reference-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). +parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-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 Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters. 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)] | 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. onFailure | [[Failure Action Object](#failure-action-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. From b6620bc1d073f4aa7ac7bf82ef9e848212e2a8ea Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Thu, 28 Mar 2024 21:28:08 +0000 Subject: [PATCH 7/7] feat: add `dependsOn` capability for workflow level (#164) * feat: add `dependsOn` capability for workflow level * chore: typo fix * chore: grammer fix --- versions/1.0.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 03f283a..b1de243 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -270,6 +270,7 @@ Field Name | Type | Description 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. 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. 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) \| [Reference Object](#reference-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 Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters.