Merge branch 'main' into requestBody-enhancement

examples/1.0.0/ExtendedParametersExample.workflow.yaml

@@ -0,0 +1,26 @@
+workflowsSpec: 1.0.0
+info:
+  title: Public Zoo API
+  version: '1.0'
+sourceDescriptions:
+  - name: animals
+    type: openapi
+    url: ./animals.yaml
+workflows:
+  - workflowId: animal-workflow
+    parameters:
+      - in: cookie
+        name: workflowLevelParamOne
+        value: someValue
+      - in: header
+        name: workflowLevelParamTwo
+        value: someValue
+    steps:
+      - stepId: post-step
+        parameters:
+          - in: cookie
+            name: authentication
+            value: SUPER_SECRET
+        operationId: animals.postAnimal
+      - stepId: get-step
+        operationId: animals.getRandomAnimal

examples/1.0.0/LoginAndRetrievePets.workflow.yaml

@@ -44,7 +44,6 @@ workflows:
   - stepId: getPetStep
     description: retrieve a pet by status from the GET pets endpoint
     operationPath: $sourceDescriptions.petStoreDescription#/paths/~1pet~1findByStatus
-    dependsOn: loginStep
     parameters:
       - name: status
         in: query

examples/1.0.0/README.md

@@ -0,0 +1,23 @@
+# Workflows Specification Examples
+
+## Purpose
+
+This README will provide details on the examples found in this directory as well as examples to be added to cover a
+variety of use case scenarios.
+
+## Examples
+
+### FAPI
+*needs description*
+
+### OAuth
+*needs description*
+
+### Pet Coupons
+*needs description*
+
+## Examples to be added
+
+* An example where a workflow imports another workflow both of which have components defined to show that the entry/root
+  workflow can not reference components defined in the imported workflow. Components are scoped to the workflow they
+  are defined in.

examples/1.0.0/pet-coupons.workflow.yaml

@@ -146,10 +146,10 @@ components:
       description: Indicates the domain name of the store where the customer is browsing or buying pets, e.g. "pets.example.com" or "pets.example.co.uk".
   parameters:
     page:
+      name: page
       in: query
-      type: integer
-      format: int32
+      value: 1
     pageSize:
+      name: pageSize
       in: query
-      type: integer
-      format: int32
+      value: 100

versions/1.0.0.md

@@ -190,7 +190,6 @@ workflows:
   - stepId: getPetStep
     description: retrieve a pet by status from the GET pets endpoint
     operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get'
-    dependsOn: loginStep
     parameters:
       - name: status
         in: query
@@ -238,14 +237,14 @@ version: 1.0.1
 
 Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within a Workflows Description.
 
-An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this workflow SHALL apply to. Each source location `string` 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).
+An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this workflow SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986 section 4.1](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1).
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
 <a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
-<a name="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source description 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="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source description to be used by a Workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986 section 4.2](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2).
 <a name="infoType"></a>type | `string` | The type of source description. Possible values are `"openapi"` or `"workflowsSpec"`.
 
 
@@ -271,8 +270,11 @@ Field Name | Type | Description
 <a name="workflowSummary"></a>summary | `string` | A summary of the purpose or objective of the workflow.
 <a name="workflowDescription"></a>description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
+<a name="dependsOn"></a>dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Workflows Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes.
 <a name="workflowSteps"></a>steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow.
 <a name="workflowOutputs"></a>outputs | Map[`string`, {expression}] |  A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+<a name="workflowParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters.
+
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -325,9 +327,8 @@ 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 `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="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters.
 <a name="stepRequestBody"></a>requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
-<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.
 <a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.