First cut of Specification Path expressions

OAI · Feb 7, 2024 · b8a3497 · b8a3497
1 parent e021569
commit b8a3497
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 7 deletions.
diff --git a/examples/1.0.0/LoginAndRetrievePets.workflow.yaml b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml
@@ -43,7 +43,7 @@ workflows:
       sessionToken: $response.body
   - stepId: getPetStep
     description: retrieve a pet by status from the GET pets endpoint
-    operationRef: https://petstore3.swagger.io/api/v3/openapi.json#/paths/users/~findbystatus~1{status}/get
+    operationPath: $sourceDescriptions.petStoreDescription#/paths/~1pet~1findByStatus
     dependsOn: loginStep
     parameters:
       - name: status

diff --git a/versions/1.0.0.md b/versions/1.0.0.md
@@ -64,6 +64,7 @@ The Workflows Specification can articulate these workflows in a human-readable a
         - [Fixed Fields](#fixed-fields-10)
         - [Criterion Object Example](#criterion-object-example)          
     - [Runtime Expressions](#runtime-expressions)
+    - [Specification Path Expressions](#spec-path-expressions)
     - [Specification Extensions](#specification-extensions)
     - [Security Considerations](#security-considerations)
     - [IANA Considerations](#iana-considerations)
@@ -189,7 +190,7 @@ workflows:
       sessionToken: $response.body
   - stepId: getPetStep
     description: retrieve a pet by status from the GET pets endpoint
-    operationRef: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml#/paths/~1pet~1findByStatus/get
+    operationPath: $sourceDescriptions.petstoreDescription#/paths/~1pet~1findByStatus/get
     dependsOn: loginStep
     parameters:
       - name: status
@@ -322,10 +323,10 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="stepDescription"></a>description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
-<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).
+<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 source reference combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to identify the operation within that source file. 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. The [Specification Path Expression](#spec-path-expressions) syntax MUST be used.
+<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 to pass to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object).
 <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.
@@ -384,7 +385,7 @@ steps:
         sessionToken: $response.body
   - stepId: getPetStep
     description: retrieve a pet by status from the GET pets endpoint
-    operationRef: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml#/paths/~1pet~1findByStatus/get
+    operationPath: $sourceDescriptions.petStoreDescription#/paths/~1pet~1findByStatus/get
     parameters:
       - name: status
         in: query
@@ -717,6 +718,26 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org
         "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
 ```
 
+### <a name="specPathExpressions"></a>Specification Path Expressions
+A specification path expression allows an operation in an OpenAPI specification that does not have an operationId defined to be referenced as part of a [steps](#step-object).
+
+The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax:
+
+```abnf
+      reference = source "#" json-pointer
+      source = "$sourceDescriptions." name
+      json-pointer    = *( "/" reference-token )
+      reference-token = *( unescaped / escaped )
+      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
+         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+      escaped         = "~" ( "0" / "1" )
+        ; representing '~' and '/', respectively
+      name = *( CHAR )
+      token = 1*tchar
+      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
+        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+```
+
 ##### Examples
 
 Source Location | example expression  | notes