Remove Reference Object to avoid clash with JSON Schema keyword. Repl…

…ace with expression based referencing
OAI · Mar 16, 2024 · 22d160a · 22d160a
1 parent 49e0050
commit 22d160a
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 20 deletions.
diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml
@@ -72,9 +72,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)
+      - [Parameter Reference Object](#parameter-reference-object)
         - [Fixed Fields](#fixed-fields-9)
-        - [Reference Object Example](#reference-object-example)      
+        - [Parameter Reference Object Example](#parameter-reference-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
 
@@ -325,7 +325,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 `operationRef` and `workflowId` fields respectively.
 <a name="stepOperationRef"></a>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.
 <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 `operationRef` fields respectively.
-<a name="stepParameters"></a>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) defined in the current Workflows document.
+<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Parameter Reference Object](#parameter-reference-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a Parameter Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object) defined in the current Workflows document.
 <a name="dependsOn"></a>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.
 <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.
@@ -594,34 +594,28 @@ components:
 }
 ```
 
-#### Reference Object
+#### Parameter 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.
-
-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="parameterReferenceName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired parameter.
+<a name="referenceValue"></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
+##### Parameter Reference Object Example
 
 ```yaml
-  $ref: "#/components/parameters/page"
+  name: $components.parameters.page
   value: 1
 ```
 
 ```json
   {
-    "$ref": "#/components/parameters/page",
+    name: "{$components.parameters.page}",
     "value": 1
   }
 ```
@@ -701,7 +695,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