Clarity on referencing Components Parameters (#149)

frankkilcommins · web-flow · commit aa470920d130 · 2024-03-28T22:00:38.000Z
* Clarity on referencing Components Parameters

* Remove Reference Object to avoid clash with JSON Schema keyword. Replace with expression based referencing

* chore: keep fixed field link names consistent

* chore: Name component parameters as type Reusable Parameter Object

* chore: adjust Workflow level parameters to use Reusable Parameter Objects
diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml
@@ -70,9 +70,9 @@ workflows:
           - name: status
             in: query
             value: "available"
-          - $ref: '#/components/parameters/page'
+          - name: $components.parameters.page
             value: 1
-          - $ref: '#/components/parameters/pageSize'
+          - name: $components.parameters.pageSize
             value: 10
         successCriteria:
           - condition: $statusCode == 200
diff --git a/versions/1.0.0.md b/versions/1.0.0.md
@@ -57,9 +57,9 @@ 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)
-      - [Reference Object](#reference-object)
+      - [Reusable Parameter Object](#reusable-parameter-object)
         - [Fixed Fields](#fixed-fields-9)
-        - [Reference Object Example](#reference-object-example)      
+        - [Reusable Parameter Object Example](#reusable-parameter-object-example)      
       - [Criterion Object](#criterion-object)
         - [Fixed Fields](#fixed-fields-10)
         - [Criterion Object Example](#criterion-object-example)          
@@ -98,7 +98,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 It is RECOMMENDED that the entry Workflows document be named: `workflows.json` or `workflows.yaml`.
 
-A Workflows Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Objects](#reference-object) are used.  In a multi-document description, the document containing the [Workflows Specification Object](#workflows-specification-object) is known as the **entry Workflows document**.
+A Workflows Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they must by included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Workflows Specification Object](#workflows-specification-object) is known as the **entry Workflows document**. 
 
 ### Data Types
 
@@ -273,7 +273,7 @@ Field Name | Type | Description
 <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="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) \| [Reference Object](#reference-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 Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters.
+<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.
 
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -327,7 +327,7 @@ 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) \| [Reference Object](#reference-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 Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). 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 parameters 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.
@@ -500,6 +500,8 @@ criteria:
 
 Holds a set of reusable objects for different aspects of the Workflows Specification. All objects defined within the components object will have no effect on the workflow unless they are explicitly referenced from properties outside the components object.
 
+Components are scoped to the Workflows document they are defined in. For example, if a step defined in Workflows document "A" references a workflow defined in Workflows document "B", the components in "A" are not considered when evaluating the workflow referenced in "B".
+
 ##### Fixed Fields
 
 Field Name | Type | Description
@@ -570,34 +572,28 @@ components:
 }
 ```
 
-#### Reference Object
-
-A simple object to allow referencing other components in the Workflows Description.
-
-**Note -** This section is derived from the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object), and is intended to be implemented in similar fashion.
-
-The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the location of the value being referenced.
+#### Reusable Parameter Object
 
-See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relative-references-in-uris).
+A simple object to allow reusable parameters from multiple steps in the Workflows Description.
 
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="referenceRef"></a>$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI.
-<a name="referenceValue"></a>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.
+<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.
 
-##### Reference Object Example
+##### Reusable Parameter Object Example
 
 ```yaml
-  $ref: "#/components/parameters/page"
+  name: $components.parameters.page
   value: 1
 ```
 
 ```json
   {
-    "$ref": "#/components/parameters/page",
+    name: "{$components.parameters.page}",
     "value": 1
   }
 ```
@@ -781,7 +777,8 @@ 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)
+      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." 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
       query-reference = "query." name
