From e662f63863e9cdf9cbafaef272b1618bc1774b2f Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Fri, 13 Oct 2023 17:18:59 +0100 Subject: [PATCH 1/6] Add Criterion Object --- versions/1.0.0.md | 92 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 83 insertions(+), 9 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index c01bf37..3712f0a 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -55,8 +55,11 @@ The Workflows Specification can articulate these workflows in a human and machin - [Component Object](#component-object) - [Fixed Fields](#fixed-fields-8) - [Component Object Example](#component-object-example) - - [Reference Object](#reference-object) + - [Criterion Object](#criterion-object) - [Fixed Fields](#fixed-fields-9) + - [Criterion Object Example](#criterion-object-example) + - [Reference Object](#reference-object) + - [Fixed Fields](#fixed-fields-10) - [Reference Object Example](#reference-object-example) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) @@ -317,7 +320,7 @@ Field Name | Type | Description 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. 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 | [{expression}] | A list of assertions to determine the success of the 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). 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. 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. 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\.\-_]+$`. @@ -342,7 +345,7 @@ parameters: value: $inputs.password successCriteria: # assertions to determine step was successful - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After @@ -366,7 +369,7 @@ steps: value: $inputs.password successCriteria: # assertions to determine step was successful - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After @@ -383,7 +386,7 @@ steps: in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body @@ -460,7 +463,8 @@ 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`. 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 | [{expression}] | A list of assertions to determine if this action SHALL be executed. + 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). + **Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. @@ -471,7 +475,9 @@ type: goto stepId: joinWaitingListStep criteria: # assertions to determine if this success action should be executed - - $response.body.Pets.length() > 0 + - context: $response.body + condition: $.Pets.length() > 0 + type: JSONPath ``` This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -491,7 +497,7 @@ Field Name | Type | Description 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. - criteria | [{expression}] | A list of assertions to determine if this action SHALL be executed. + 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). **Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. @@ -503,7 +509,7 @@ retryAfter: 1000 retryLimit: 5 criteria: # assertions to determine if this action should be executed - - $statusCode == 503 + - condition: $statusCode == 503 ``` This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -614,6 +620,74 @@ This object cannot be extended with additional properties and any properties add } ``` +#### Criterion Object + +An object used to specify the context, conditions, and condition types that can be used to prove or satisfy criteria specified in Step Object `successCriteria`, Success Action Object `criteria`, and Failure Action Object `criteria`. + +There are three flavors of conditions supported: +- simple - where use of 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 (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) + +##### Literals +As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. + +Type | Literal value +---|--- +`boolean` | `true` or `false` +`null` | `null` +`number` | Any number format supported in [Data Types](#data-types) + +##### Operators +Operator | Description +---|--- +`<`| Less than +`<=`| Less than or equal +`>`| Greater than +`>=`| Greater than or equal +`==`| Equal +`!=`| Not equal +`!`| Not +`&&`| And +`\|\|`| Or +`()`| Logical Grouping +`[]`| Index (0-based) +`.`| Property de-reference + +String comparisons `SHOULD` be case insensitive. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query could be applied to). +condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` must be specified. +type | `string` | The type of condition to be applied. If specified, the options allowed are `regex` or `JSONPath`. If omitted, then the condition is assumed to be a simple condition which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). + + +This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). + +##### Criterion Object Example + +**Simple Condition Example** + +```yaml +- condition: $statusCode == 200 +``` + +**Regex Condition Example** +```yaml +- context: $statusCode + condition: '^200$' + type: regex +``` + +**JSONPath Condition Example** +```yaml +- context: $response.body + condition: $.pets.length() > 0 + type: JSONPath +``` + ### 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). From b662332529e123e96e127691f3b1b4c7289d2157 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Fri, 13 Oct 2023 17:25:35 +0100 Subject: [PATCH 2/6] Update examples in spec --- versions/1.0.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 3712f0a..c68a75f 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -174,7 +174,7 @@ workflows: value: $inputs.password successCriteria: # assertions to determine step was successful - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After @@ -192,7 +192,7 @@ workflows: in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body @@ -296,7 +296,7 @@ steps: value: $inputs.password successCriteria: # assertions to determine step was successful - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After From 6088579c1053841d9a1be4472bedefb49fe8dfb7 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Fri, 13 Oct 2023 17:31:17 +0100 Subject: [PATCH 3/6] Typo fixes --- versions/1.0.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index c68a75f..d6fb1f8 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -622,12 +622,12 @@ This object cannot be extended with additional properties and any properties add #### Criterion Object -An object used to specify the context, conditions, and condition types that can be used to prove or satisfy criteria specified in Step Object `successCriteria`, Success Action Object `criteria`, and Failure Action Object `criteria`. +An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object `successCriteria`, Success Action Object `criteria`, and Failure Action Object `criteria`. There are three flavors of conditions supported: -- simple - where use of 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 (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) +- 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). ##### Literals As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. @@ -660,8 +660,8 @@ String comparisons `SHOULD` be case insensitive. Field Name | Type | Description ---|:---:|--- context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query could be applied to). -condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` must be specified. -type | `string` | The type of condition to be applied. If specified, the options allowed are `regex` or `JSONPath`. If omitted, then the condition is assumed to be a simple condition which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). +condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` MUST be specified. +type | `string` | The type of condition to be applied. If specified, the options allowed are `regex` or `JSONPath`. If omitted, then the condition is assumed to be simple, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). From 8e25bd5c13d30a1828ae4978798b861d2e40cb21 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Sat, 14 Oct 2023 11:11:08 +0100 Subject: [PATCH 4/6] Update examples based on Criterion Object addition --- examples/1.0.0/FAPI-PAR.workflow.yaml | 6 ++--- .../1.0.0/LoginAndRetrievePets.workflow.yaml | 4 ++-- examples/1.0.0/oauth.workflow.yaml | 24 ++++++++++++------- examples/1.0.0/pet-coupons.workflow.yaml | 12 +++++----- versions/1.0.0.md | 6 ++--- 5 files changed, 30 insertions(+), 22 deletions(-) diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.workflow.yaml index 2ba3651..20d0c3c 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/examples/1.0.0/FAPI-PAR.workflow.yaml @@ -115,7 +115,7 @@ workflows: value: $inputs.PARrequestBody successCriteria: # assertions to determine step was successful - - $statusCode == 200 + - condition: $statusCode == 200 outputs: request_uri: $response.body.request_uri @@ -131,7 +131,7 @@ workflows: value: $inputs.client_id successCriteria: # assertions to determine step was successful - - $statusCode == 302 + - condition: $statusCode == 302 outputs: code: $response.body.code # Not really, this is a query parameter (need a way to represent out-of-band props) @@ -166,7 +166,7 @@ workflows: value: $inputs.code_verifier successCriteria: # assertions to determine step was successful - - $statusCode == 200 + - condition: $statusCode == 200 outputs: tokenResponse: $response.body diff --git a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml index de05138..7ae0e3c 100644 --- a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml @@ -35,7 +35,7 @@ workflows: value: $inputs.password successCriteria: # assertions to determine step was successful - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After @@ -53,7 +53,7 @@ workflows: in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index aff9f0c..4308582 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.workflow.yaml @@ -59,8 +59,10 @@ workflows: grant_type: refresh_token refresh_token: $steps.do-the-auth-flow.outputs.my_refresh_token successCriteria: - - $statusCode == 200 - - $response.body.access_token != null + - condition: $statusCode == 200 + - context: $response.body + condition: $.access_token != null + type: JSONPath outputs: access_token: $response.body.access_token refresh_token: $response.body.refresh_token @@ -105,8 +107,10 @@ workflows: value: 'client_credentials' successCriteria: - - $statusCode == 200 - - $response.body.access_token != null + - condition: $statusCode == 200 + - context: $response.body + condition: $.access_token != null + type: JSONPath outputs: access_token: $response.body.access_token @@ -153,8 +157,10 @@ workflows: in: query value: '12345' successCriteria: - - $statusCode == 200 - - $response.body.access_token != null + - condition: $statusCode == 200 + - context: $response.body + condition: $.access_token != null + type: JSONPath outputs: code: $response.body.code # Not really, this is a query parameter @@ -185,8 +191,10 @@ workflows: value: $steps.browser-authorize.outputs.code successCriteria: - - $statusCode == 200 - - $response.body.access_token != null + - condition: $statusCode == 200 + - context: $response.body + condition: $.access_token != null + type: JSONPath outputs: access_token: $response.body.access_token refresh_token: $response.body.refresh_token diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 4668e90..4650907 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -26,7 +26,7 @@ workflows: in: query value: $inputs.my_pet_tags successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_pet_id: $outputs[0].id # there is some implied selection here - findPetsByTags responds with a list of pets, @@ -40,7 +40,7 @@ workflows: in: path value: $steps.find-pet.outputs.my_pet_id successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_coupon_code: $response.body.couponCode - stepId: place-order @@ -53,7 +53,7 @@ workflows: in: body value: $steps.find-coupons.outputs.my_coupon_code successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_order_id: $response.body.id - workflowId: buy-available-pet @@ -75,7 +75,7 @@ workflows: - $ref: '#/components/parameters/pageSize' value: 10 successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_pet_id: $outputs[0].id - stepId: place-order @@ -85,7 +85,7 @@ workflows: in: body value: $steps.find-pet.outputs.my_pet_id successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_order_id: $response.body.id - workflowId: place-order @@ -130,7 +130,7 @@ workflows: target: $request.body#/complete value: false successCriteria: - - $statusCode == 200 + - condition: $statusCode == 200 outputs: my_order_id: $response.body.id components: diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d6fb1f8..593d93b 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -625,7 +625,7 @@ 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 `successCriteria`, Success Action Object `criteria`, and Failure Action Object `criteria`. There are three flavors of conditions supported: -- simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions) +- 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). @@ -659,7 +659,7 @@ String comparisons `SHOULD` be case insensitive. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query could be applied to). +context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` MUST be specified. type | `string` | The type of condition to be applied. If specified, the options allowed are `regex` or `JSONPath`. If omitted, then the condition is assumed to be simple, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). @@ -684,7 +684,7 @@ This object _MAY_ be extended with [Specification Extensions](#specificationExte **JSONPath Condition Example** ```yaml - context: $response.body - condition: $.pets.length() > 0 + condition: $[?length(@.pets) > 0] type: JSONPath ``` From f8f34dcbe6a319b54d595080ef28e6fdfdf69839 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 18 Oct 2023 16:25:12 +0100 Subject: [PATCH 5/6] Add `simple` as allowed type value --- 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 593d93b..903c1c3 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -661,7 +661,7 @@ Field Name | Type | Description ---|:---:|--- context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` MUST be specified. -type | `string` | The type of condition to be applied. If specified, the options allowed are `regex` or `JSONPath`. If omitted, then the condition is assumed to be simple, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). +type | `string` | The type of condition to be applied. If specified, the options allowed are `simple`, `regex` or `JSONPath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). From 63e9d67991d1f8d2fd27a42d877aeeeaaa89cbc4 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Thu, 26 Oct 2023 15:16:21 +0100 Subject: [PATCH 6/6] Improve verbiage for criteria and unique fields --- versions/1.0.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 903c1c3..10cc93a 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -237,7 +237,7 @@ An object storing a map between named document keys and location URLs to the sou Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression `[A-Za-z0-9_\-]+`. +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"`. @@ -260,7 +260,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. +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_\-]+`. 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. @@ -314,13 +314,13 @@ Describes a single workflow step which MAY be a call to an API operation ([OpenA 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. +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. +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. 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). +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. 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. 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\.\-_]+$`. @@ -463,7 +463,7 @@ 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`. 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). + 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. **Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.