Merge pull request #59 from shaisachs/feature/disambiguate-workflow

Disambiguate workflows

examples/1.0.0/FAPI-PAR.workflow.yaml

@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: >-
     A workflow describing how to obtain a token from an OAuth2 and OpenID Connect Financial Grade authorization server which can be common for PSD2 API journeys
-sources:
+sourceDocuments:
   - name: auth-api
     url: ./FAPI-PAR.openapi.yaml
     type: openapi

examples/1.0.0/LoginAndRetrievePets.yaml

@@ -5,7 +5,7 @@ info:
     description: |
         This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
     version: 1.0.1
-sources:
+sourceDocuments:
 - name: petStoreDefinition
   url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
   type: openapi

examples/1.0.0/oauth.workflow.yaml

@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: >-
     APImetrics OAuth service
-sources:
+sourceDocuments:
   - name: apim-auth
     url: ./oauth.openapi.yaml
     type: openapi
@@ -37,9 +37,6 @@ workflows:
         #   # Or a previous refresh-token-flow.outputs.refresh_token
     steps:
       - stepId: do-the-auth-flow
-        # Open question: how do we reference a workflow from another file?
-        # e.g.: 
-        # workflowId: $sources.sample.workflows.authorization-code-flow
         workflowId: authorization-code-flow
         parameters:
         - name: client_id

examples/1.0.0/pet-coupons.workflow.yaml

@@ -6,7 +6,7 @@ info:
     Illustrates a workflow whereby a client a) finds a pet in the petstore, 
     b) finds coupons for that pet, and finally
     c) orders the pet while applying the coupons from step b.
-sources:
+sourceDocuments:
   - name: pet-coupons
     url: ./pet-coupons.openapi.yaml
     type: openapi

versions/1.0.0.md

@@ -34,9 +34,9 @@ The Workflows Specification can articulate these workflows in a human and machin
       - [Info Object](#info-object)
         - [Fixed Fields](#fixed-fields-1)
         - [Info Object Example](#info-object-example)
-      - [Source Object](#source-object)
+      - [Source Document Object](#source-document-object)
         - [Fixed Fields](#fixed-fields-2)
-        - [Source Object Example](#source-object-example)
+        - [Source Document Object Example](#source-document-object-example)
       - [Workflow Object](#workflow-object)
         - [Fixed Fields](#fixed-fields-3)
         - [Workflow Object Example](#workflow-object-example)
@@ -66,7 +66,7 @@ The Workflows Specification can articulate these workflows in a human and machin
 ## Definitions
 
 ##### Workflows Document
-A self-contained or composite resource which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). The workflows document `MUST` contain a valid Workflows Specification version field (`workflowsSpec`), an [Info](#info-object) field, a `sources` field with at least one defined [Source](#source-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the workflows fixed field. A Workflows document uses and conforms to the Workflows Specification.
+A self-contained or composite resource which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). The workflows document `MUST` contain a valid Workflows Specification version field (`workflowsSpec`), an [Info](#info-object) field, a `sourceDocuments` field with at least one defined [Source](#source-document-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the workflows fixed field. A Workflows document uses and conforms to the Workflows Specification.
 
 ## Specification
 
@@ -125,7 +125,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="workflowsVersion"></a>workflowsSpec | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Workflows Specification that the Workflows document uses. The `workflowsSpec` field SHOULD be used by tooling to interpret the Workflows document.
 <a name="workflowsInfo"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. The metadata MAY be used by tooling as required.
-<a name="workflowsSources"></a>sources | [[Source Object](#source-object)] | **REQUIRED**. A list of source documents (such as an OpenAPI document) this workflow SHALL apply to. The list MUST have at least one entry.
+<a name="workflowsSources"></a>sourceDocuments | [[Source Document Object](#source-document-object)] | **REQUIRED**. A list of source documents (such as an OpenAPI document) this workflow SHALL apply to. The list MUST have at least one entry.
 <a name="workflows"></a>workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry.
 <a name="components"></a>components | [Component Object](#component-object) | An element to hold various schemas for the document.
 
@@ -141,7 +141,7 @@ info:
   description: |
       This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
   version: 1.0.1
-sources:
+sourceDocuments:
 - name: petStoreDefinition
   url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
   type: openapi
@@ -224,7 +224,7 @@ description: |
 version: 1.0.1
 ```
 
-#### Source Object
+#### Source Document Object
 
 Describes a source document (such as an OpenAPI document) that will be referenced by one or more workflows described within a Workflows document.
 
@@ -234,14 +234,14 @@ An object storing a map between named document keys and location URLs to the sou
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source document.
+<a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression `[A-Za-z0-9_\-]+`.
 <a name="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source document to be used by a Workflow. MUST be in the form of a [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986).
 <a name="infoType"></a>type | `string` | The type of source document. Possible values are `"openapi"`, `"asyncapi"`, or `"workflowsSpec"`.
 
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
-##### Source Object Example
+##### Source Document Object Example
 
 ```yaml
 name: petStoreDefinition
@@ -314,7 +314,7 @@ Field Name | Type | Description
 <a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The id SHOULD 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.
 <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 `source` documents. The referenced operation will be invoked by this workflow step. If more than one `source` document is defined within a Workflows document, then the `operationId` specified MUST be prefixed with the source name 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. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used.
-<a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively.
+<a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. If more than one `source` document is defined within a Workflows document, then the `workflowId` specified MUST be prefixed with the source name 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](#component-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 | [{expression}] | A list of assertions to determine the success of the step