Skip to content

Commit

Permalink
Add Reusable Object and referencing ability
Browse files Browse the repository at this point in the history
  • Loading branch information
@frankkilcommins
frankkilcommins committed Mar 29, 2024
1 parent 063d5e5 commit d061253
Showing 1 changed file with 68 additions and 11 deletions.
79 changes: 68 additions & 11 deletions versions/1.0.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,19 @@ The Workflows Specification can articulate these workflows in a human-readable a
- [Components Object Example](#components-object-example)
- [Reusable Parameter Object](#reusable-parameter-object)
- [Fixed Fields](#fixed-fields-9)
- [Reusable Parameter Object Example](#reusable-parameter-object-example)
- [Criterion Object](#criterion-object)
- [Reusable Parameter Object Example](#reusable-parameter-object-example)
- [Reusable Object](#reusable-object)
- [Fixed Fields](#fixed-fields-10)
- [Criterion Object Example](#criterion-object-example)
- [Reusable Object Example](#reusable-object-example)
- [Criterion Object](#criterion-object)
- [Fixed Fields](#fixed-fields-11)
- [Criterion Object Example](#criterion-object-example)
- [Request Body Object](#request-body-object)
- [Fixed Fields](#fixed-fields-12)
- [Request Body Object Example](#requestbody-object-example)
- [Payload Pointer Object](#payload-pointer-object)
- [Fixed Fields](#fixed-fields-13)
- [Payload Pointer Object Example](#payload-pointer-object-example)
- [Runtime Expressions](#runtime-expressions)
- [Specification Extensions](#specification-extensions)
- [Security Considerations](#security-considerations)
Expand Down Expand Up @@ -329,11 +338,11 @@ Field Name | Type | Description
<a name="stepOperationId"></a>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.<name>.<operationId>`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively.
<a name="stepOperationPath"></a>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`.
<a name="stepWorkflowId"></a>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.<name>.<workflowId>`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively.
<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Parameter Object is provided, it MUST link to parameters defined in the [components/parameters](#components-object) of the current Workflows document. The list MUST NOT include duplicate parameters.
<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Parameter Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Workflows document. The list MUST NOT include duplicate parameters.
<a name="stepRequestBody"></a>requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
<a name="stepSuccessCriteria"></a>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.
<a name="stepOnSuccess"></a>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.
<a name="stepOnFailure"></a>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.
<a name="stepOnSuccess"></a>onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Workflows document. The list MUST NOT include duplicate success actions.
<a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Workflows document. The list MUST NOT include duplicate failure actions.
<a name="stepOutputs"></a>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).
Expand Down Expand Up @@ -446,7 +455,7 @@ A single success action which describes an action to take upon success of a work
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="successActionName"></a> name | `string` | **REQUIRED**. The name of the success action. Parameter names are _case sensitive_.
<a name="successActionName"></a> name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_.
<a name="successActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`.
<a name="successWorkflowId"></a> 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.<name>.<workflowId>`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`.
<a name="successStepId"></a> 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`.
Expand Down Expand Up @@ -479,7 +488,7 @@ A single failure action which describes an action to take upon failure of a work
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="failureActionName"></a> name | `string` | **REQUIRED**. The name of the failure action. Parameter names are _case sensitive_.
<a name="failureActionName"></a> name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_.
<a name="failureActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`.
<a name="failureWorkflowId"></a> 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.<name>.<workflowId>`) 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.
<a name="failureStepId"></a> 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.
Expand Down Expand Up @@ -551,6 +560,16 @@ components:
pageSize:
type: integer
format: int32
failureActions:
refreshToken:
name: refreshExpiredToken
type: retry
retryAfter: 1
retryLimit: 5
workflowId: refreshTokenWorkflowId
criteria:
# assertions to determine if this action should be executed
- condition: $statusCode == 401
```

```json
Expand All @@ -576,21 +595,35 @@ components:
}
}
}
},
"failureActions": {
"refreshToken": {
"name": "refreshExpiredToken",
"type": "retry",
"retryAfter": 1,
"retryLimit": 5,
"workflowId": "refreshTokenWorkflowId",
"criteria": [
{
"condition": "{$statusCode == 401}"
}
]
}
}
}
```

#### Reusable Parameter Object

A simple object to allow reusable parameters from multiple steps in the Workflows Description.
A simple object to allow reusable parameters from multiple steps or workflows in the Workflows Description.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="reusableParameterName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired parameter.
<a name="reusableParameterValue"></a>value | `string` | A value by default MUST override that of the referenced parameter.

This object cannot be extended with additional properties and any properties added SHALL be ignored.
This object cannot be extended with additional properties and any properties added MUST be ignored.

##### Reusable Parameter Object Example

Expand All @@ -606,6 +639,29 @@ This object cannot be extended with additional properties and any properties add
}
```

#### Reusable Object

A simple object to allow referencing of objects contained within the [Components Object](#components-object) from locations within steps or workflows in the Workflows Description. This excludes parameters and inputs defined in the [components/parameters](#components-object). **Note** - parameters should be referenced using the [Reusable Parameter Object](#reusable-parameter-object) and inputs should use standard JSON Schema referencing using the `$ref` keyword.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="reusableObjectName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object.

This object cannot be extended with additional properties and any properties added MUST be ignored.

##### Reusable Object Example

```yaml
name: $components.successActions.notify
```

```json
{
name: "{$components.successActions.notify}"
}
```

#### Criterion Object

An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`.
Expand Down Expand Up @@ -785,7 +841,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 / "$sourceDescriptions." name / "$components.parameters." parameter-name)
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name)
parameter-name = name ; Reuses 'name' rule for parameter names
source = ( header-reference / query-reference / path-reference / body-reference )
header-reference = "header." token
Expand Down Expand Up @@ -818,6 +874,7 @@ Response header | `$response.header.Server` | Single header values only
workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available
Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body.
Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available
Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.

Runtime expressions preserve the type of the referenced value.
Expressions can be embedded into string values by surrounding the expression with `{}` curly braces.
Expand Down

0 comments on commit d061253

Please sign in to comment.