diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index b3f19da..5d9fd78 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.workflow.yaml @@ -40,13 +40,10 @@ workflows: workflowId: authorization-code-flow parameters: - name: client_id - in: workflow value: $inputs.my_client_id - name: redirect_uri - in: workflow value: $inputs.my_redirect_uri - name: client_secret - in: workflow value: $inputs.my_client_secret outputs: my_refresh_token: $outputs.refresh_token diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 7e3cc9f..cb80652 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -133,7 +133,7 @@ This is the root object of the [Workflows Description](#workflows-description). 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 SHOULD be used by tooling to interpret the Workflows 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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. @@ -321,15 +321,15 @@ 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. 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` 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. +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 `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 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 `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](#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. -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. +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. 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). @@ -407,14 +407,13 @@ Describes a single step parameter. A unique parameter is defined by the combinat - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. - cookie - Used to pass a specific cookie value to the source API. - body - The request, message or form body to be sent to the referenced operation. - - workflow - Parameters to be passed into a referenced workflow ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. - in | `string` | **REQUIRED**. The name location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, `"body"`, or `"workflow"`. - style | `string` | Describes how the parameter value will be serialized depending on the location of parameter value. This fixed field is predominately used to express how a _request body_ is to be serialized. For example, when request data (`in` with value `"body"`) is to be serialized as `x-www-form-urlencoded`, the style SHOULD be `"form"`. `in` parameters with values of `"query"`, `"header"`, or `"cookie"` MUST derive their style from the referenced `source` when applicable. + in | `string` | The name location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. + style | `string` | Describes how the parameter value will be serialized depending on the location of parameter value. This fixed field is predominately used to express how a _request body_ is to be serialized. For example, when request data (`in` with value `"body"`) is to be serialized as `x-www-form-urlencoded`, the style SHOULD be `"form"`. `in` parameters with values of `"query"`, `"header"`, or `"cookie"` MUST derive their style from the referenced `sourceDescriptions` operation when applicable. target | `string` | A [JSON Pointer](https://tools.ietf.org/html/rfc6901) identifying locations to inject the value. Useful for targeting specific request body parts. value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or an [expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. @@ -468,12 +467,11 @@ 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 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`. + 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`. 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. -**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -500,13 +498,12 @@ 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 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. + 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. 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 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"`. + 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. 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. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -514,7 +511,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten ```yaml type: retry -retryAfter: 1000 +retryAfter: 1 retryLimit: 5 criteria: # assertions to determine if this action should be executed @@ -609,7 +606,7 @@ See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI. -value | `string` | A value by default SHOULD override that of the referenced component. If the referenced object-type does not have a `value` field, then it has no effect. +value | `string` | A value by default MUST override that of the referenced component. If the referenced object-type does not have a `value` field, then it has no effect. This object cannot be extended with additional properties and any properties added SHALL be ignored. @@ -702,7 +699,7 @@ A runtime expression allows values to be defined based on information that will The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf - expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name) + expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name) source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name