Skip to content

Commit cd256ae

Browse files
frankkilcomminsfrankkilcommins
authored
Consolidate reusable parameters and reusable objects. (#182)
* Consolidate reusable parameters and reusable objects. * chore: align parameter reference wording * chore: apply PR suggestions to improve verbiage * chore: fix merge issue * chore: fix JSON examples for Reusable Object
1 parent ca9d9f1 commit cd256ae

File tree

2 files changed

+22
-38
lines changed

2 files changed

+22
-38
lines changed

‎examples/1.0.0/pet-coupons.workflow.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,9 @@ workflows:
7070
- name: status
7171
in: query
7272
value: "available"
73-
- name: $components.parameters.page
73+
- reference: $components.parameters.page
7474
value: 1
75-
- name: $components.parameters.pageSize
75+
- reference: $components.parameters.pageSize
7676
value: 10
7777
successCriteria:
7878
- condition: $statusCode == 200

‎versions/1.0.0.md

Lines changed: 20 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -57,20 +57,17 @@ The Workflows Specification can articulate these workflows in a human-readable a
5757
- [Components Object](#components-object)
5858
- [Fixed Fields](#fixed-fields-8)
5959
- [Components Object Example](#components-object-example)
60-
- [Reusable Parameter Object](#reusable-parameter-object)
61-
- [Fixed Fields](#fixed-fields-9)
62-
- [Reusable Parameter Object Example](#reusable-parameter-object-example)
6360
- [Reusable Object](#reusable-object)
64-
- [Fixed Fields](#fixed-fields-10)
61+
- [Fixed Fields](#fixed-fields-9)
6562
- [Reusable Object Example](#reusable-object-example)
6663
- [Criterion Object](#criterion-object)
67-
- [Fixed Fields](#fixed-fields-11)
64+
- [Fixed Fields](#fixed-fields-10)
6865
- [Criterion Object Example](#criterion-object-example)
6966
- [Request Body Object](#request-body-object)
70-
- [Fixed Fields](#fixed-fields-12)
67+
- [Fixed Fields](#fixed-fields-11)
7168
- [Request Body Object Example](#requestbody-object-example)
7269
- [Payload Replacement Object](#payload-replacement-object)
73-
- [Fixed Fields](#fixed-fields-13)
70+
- [Fixed Fields](#fixed-fields-12)
7471
- [Payload Replacement Object Example](#payload-replacement-object-example)
7572
- [Runtime Expressions](#runtime-expressions)
7673
- [Specification Extensions](#specification-extensions)
@@ -281,10 +278,10 @@ Field Name | Type | Description
281278
<a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
282279
<a name="dependsOn"></a>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.<name>.<workflowId>`) to avoid ambiguity or potential clashes.
283280
<a name="workflowSteps"></a>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.
284-
<a name="workflowSuccessActions"></a>successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. The list MUST NOT include duplicate success actions.
285-
<a name="workflowFailureActions"></a>failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. The list MUST NOT include duplicate failure actions.
281+
<a name="workflowSuccessActions"></a>successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Workflows document. The list MUST NOT include duplicate success actions.
282+
<a name="workflowFailureActions"></a>failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Workflows document. The list MUST NOT include duplicate failure actions.
286283
<a name="workflowOutputs"></a>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\.\-_]+$`.
287-
<a name="workflowParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-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 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.
284+
<a name="workflowParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-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 Reusable 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.
288285

289286

290287
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -338,10 +335,10 @@ Field Name | Type | Description
338335
<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.
339336
<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`.
340337
<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.
341-
<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.
338+
<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-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 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.
342339
<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.
343340
<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.
344-
<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.
341+
<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.
345342
<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.
346343
<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\.\-_]+$`.
347344

@@ -613,52 +610,39 @@ components:
613610
}
614611
```
615612

616-
#### Reusable Parameter Object
613+
#### Reusable Object
614+
615+
A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Workflows Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism.
617616

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

620618
##### Fixed Fields
621619
Field Name | Type | Description
622620
---|:---:|---
623-
<a name="reusableParameterName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired parameter.
624-
<a name="reusableParameterValue"></a>value | `string` | A value by default MUST override that of the referenced parameter.
621+
<a name="reusableObjectValue"></a>value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references.
625622

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

628-
##### Reusable Parameter Object Example
625+
##### Reusable Object Example
629626

630627
```yaml
631-
name: $components.parameters.page
632-
value: 1
628+
reference: $components.successActions.notify
633629
```
634630

635631
```json
636632
{
637-
"name": "{$components.parameters.page}",
638-
"value": 1
633+
"reference": "$components.successActions.notify"
639634
}
640635
```
641636

642-
#### Reusable Object
643-
644-
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.
645-
646-
##### Fixed Fields
647-
Field Name | Type | Description
648-
---|:---:|---
649-
<a name="reusableObjectName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object.
650-
651-
This object cannot be extended with additional properties and any properties added MUST be ignored.
652-
653-
##### Reusable Object Example
654-
655637
```yaml
656-
name: $components.successActions.notify
638+
reference: $components.parameters.page
639+
value: 1
657640
```
658641

659642
```json
660643
{
661-
"name": "{$components.successActions.notify}"
644+
"reference": "$components.parameters.page",
645+
"value": 1
662646
}
663647
```
664648

0 commit comments

Comments
 (0)