From 22d160ad910feba0a554a101ac2b02a41d3c973b Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Sat, 16 Mar 2024 17:26:12 +0000 Subject: [PATCH] Remove Reference Object to avoid clash with JSON Schema keyword. Replace with expression based referencing --- examples/1.0.0/pet-coupons.workflow.yaml | 4 +-- versions/1.0.0.md | 31 ++++++++++-------------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 8a23e11..7f19fa3 100644 --- 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 index 4367957..69c5dfc 100644 --- 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 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..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively. 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. 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..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively. -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. +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. 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. 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. 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 ---|:---:|--- -$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI. -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. +name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired parameter. +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