Consolidate reusable parameters and reusable objects.

examples/1.0.0/pet-coupons.workflow.yaml

@@ -70,9 +70,9 @@ workflows:
           - name: status
             in: query
             value: "available"
-          - name: $components.parameters.page
+          - reference: $components.parameters.page
             value: 1
-          - name: $components.parameters.pageSize
+          - reference: $components.parameters.pageSize
             value: 10
         successCriteria:
           - condition: $statusCode == 200

versions/1.0.0.md

@@ -57,20 +57,17 @@ The Workflows Specification can articulate these workflows in a human-readable a
       - [Components Object](#components-object)
         - [Fixed Fields](#fixed-fields-8)
         - [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) 
       - [Reusable Object](#reusable-object)
-        - [Fixed Fields](#fixed-fields-10)
+        - [Fixed Fields](#fixed-fields-9)
         - [Reusable Object Example](#reusable-object-example)                
       - [Criterion Object](#criterion-object)
-        - [Fixed Fields](#fixed-fields-11)
+        - [Fixed Fields](#fixed-fields-10)
         - [Criterion Object Example](#criterion-object-example)
       - [Request Body Object](#request-body-object)
-        - [Fixed Fields](#fixed-fields-12)
+        - [Fixed Fields](#fixed-fields-11)
         - [Request Body Object Example](#requestbody-object-example)
       - [Payload Replacement Object](#payload-replacement-object)
-        - [Fixed Fields](#fixed-fields-13)
+        - [Fixed Fields](#fixed-fields-12)
         - [Payload Replacement Object Example](#payload-replacement-object-example)        
     - [Runtime Expressions](#runtime-expressions)
     - [Specification Extensions](#specification-extensions)
@@ -281,10 +278,10 @@ Field Name | Type | Description
 <a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
 <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.
 <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.
-<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.
-<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.
+<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.
+<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.
 <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\.\-_]+$`.
-<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.
+<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.
 
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -338,10 +335,10 @@ 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 a parameter 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 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.
 <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) \| [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="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\.\-_]+$`.
 
@@ -613,52 +610,39 @@ components:
 }
 ```
 
-#### Reusable Parameter Object
+#### Reusable Object
+
+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.
 
-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. 
+<a name="reusableObjectValue"></a>value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references.
 
 This object cannot be extended with additional properties and any properties added MUST be ignored.
 
-##### Reusable Parameter Object Example
+##### Reusable Object Example
 
 ```yaml
-  name: $components.parameters.page
-  value: 1
+  reference: $components.successActions.notify
 ```
 
 ```json
   {
-    "name": "{$components.parameters.page}",
-    "value": 1
+    "reference": "$components.successActions.notify"
   }
 ```
 
-#### 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
+  reference: $components.parameters.page
+  value: 1
 ```
 
 ```json
   {
-    "name": "{$components.successActions.notify}"
+    "reference": "$components.parameters.page",
+    "value": 1
   }
 ```