Specification Path expressions for operations with no OperationI ID (#…

…144)

* First cut of Specification Path expressions

* Make example use $sourceDescriptions

* Clarify wording

* Clarifying wording

* Fix Markdown

* Tidy up operationPath

examples/1.0.0/FAPI-PAR.workflow.yaml

@@ -99,7 +99,7 @@ workflows:
     steps:
       - stepId: PARStep
         description: Pushed Authorization Request
-        operationId: auth-api.PAR
+        operationId: $sourceDescriptions.auth-api.PAR
         parameters:        
           - name: client_id
             in: query
@@ -121,7 +121,7 @@ workflows:
 
       - stepId: AuthzCodeStep
         description: OIDC Authorization code request
-        operationId: auth-api.Authorization
+        operationId: $sourceDescriptions.auth-api.Authorization
         parameters:
           - name: request_uri
             in: query
@@ -137,7 +137,7 @@ workflows:
 
       - stepId: TokenStep
         description: Get token from the OIDC Token endpoint
-        operationId: auth-api.Token
+        operationId: $sourceDescriptions.auth-api.Token
         parameters:
           - name: client_id
             in: query

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

versions/1.0.0.md

@@ -189,7 +189,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.url}#/paths/~1pet~1findByStatus/get'
     dependsOn: loginStep
     parameters:
       - name: status
@@ -322,10 +322,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 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 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 +384,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.url}#/paths/~1pet~1findByStatus/get'
     parameters:
       - name: status
         in: query