From a408a36bd48f2cf007b8205561c9f44074a8429d Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 26 Apr 2023 10:00:04 -0400 Subject: [PATCH 01/25] Add components facility (#43) Signed-off-by: Shai Sachs --- versions/1.0.0.md | 82 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 4 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d0d096d..1937aab 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -45,8 +45,11 @@ The Workflows Specification can articulate these workflows in a human and machin - [Parameter Object](#parameter-object) - [Fixed Fields](#fixed-fields-5) - [Parameter Object Example](#parameter-object-example) - - [Success Action Object](#success-action-object) + - [Component Object](#component-object) - [Fixed Fields](#fixed-fields-6) + - [Parameter Object Example](#component-object-example) + - [Success Action Object](#success-action-object) + - [Fixed Fields](#fixed-fields-7) - [Success Action Object Example](#success-action-object-example) - [Failure Action Object](#failure-action-object) - [Fixed Fields](#fixed-fields-7) @@ -250,8 +253,8 @@ Field Name | Type | Description workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows document. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -inputs | `JSON Schema` | A JSON Schema object representing the input parameters used by this workflow -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 +inputs | `JSON Schema` or `string` | A JSON Schema object representing the input parameters used by this workflow. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `inputs` field. +steps | [[Step Object](#step-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `steps` field. 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\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -305,7 +308,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 `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. 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. 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. -parameters | [[Parameter Object](#parameter-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. +parameters | [[Parameter Object](#parameter-object)] or `string` | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `parameters` field. 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 | [{expression}] | A list of assertions to determine the success of the step 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. @@ -433,6 +436,77 @@ Field Name | Type | Description ``` This object MAY be extended with [Specification Extensions](#specification-extensions). +#### Component Object + +Holds a set of reusable objects for different aspects of the Workflows Specification. All objects defined within the components object will have no effect on the workflow unless they are explicitly referenced from properties outside the components object. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- + inputs | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. + steps | Map[string, [Step Object](#step-object)] | An object to hold a reusable Step Objects. +parameters | Map[string, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects + +This object MAY NOT be extended with [Specification Extensions](#specificationExtensions). + +All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input, step, or parameter in other parts of the Workflow document. + +Field Name Examples: + +``` +User +User_1 +User_Name +user-name +my.org.User +``` + +##### Components Object Example + +```json +"components": { + "inputs": { + "paginationInputs": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + } + } + } + }, + "steps": { + "addItemToCart": { + "description": "This step adds an item to the cart, and may be reused by many other steps - e.g., upon successful search for a Pet.", + "operationId": "postCartItems", + "parameters": { + "name": "sku", + "in": "query" + }, + "successCriteria": { + "$statusCode": "201" + }, + "outputs": { + "cartTotal": "$response.body.cartTotal" + } + } + }, + "parameters": { + "storeId": { + "name": "storeId", + "in": "header", + "value": "$inputs.x-store-id" + } + } +} +``` + #### Success Action Object A single success action which describes an action to take upon success of a workflow step. From 6a42a02252f0025849280b45e64058f570eab75a Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 26 Apr 2023 10:01:37 -0400 Subject: [PATCH 02/25] add credit Signed-off-by: Shai Sachs --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ed8f15f..851a0b5 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ The current SIG is made up of the following individuals, and feel free to submit - Mark Haine ([Founder, Considrd Consulting](https://www.linkedin.com/in/mark-haine/)) - Phil Sturgeon ([Dev Rel, Stoplight](https://www.linkedin.com/in/philipsturgeon/)) - Kevin Duffey ([Tech Lead, Postman](https://www.linkedin.com/in/kmd/)) +- Shai Sachs ([Staff Engineer, Chewy](https://linkedin.com/in/shaisachs/)) ## The Workflows Specification From 254b277b2ff40d879d3013d9de4cf320e1373414 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Fri, 28 Apr 2023 15:18:43 -0400 Subject: [PATCH 03/25] pagination is a better example of an operation param; store is a better example of a workflow input Signed-off-by: Shai Sachs --- versions/1.0.0.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 1937aab..6877f49 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -47,7 +47,7 @@ The Workflows Specification can articulate these workflows in a human and machin - [Parameter Object Example](#parameter-object-example) - [Component Object](#component-object) - [Fixed Fields](#fixed-fields-6) - - [Parameter Object Example](#component-object-example) + - [Component Object Example](#component-object-example) - [Success Action Object](#success-action-object) - [Fixed Fields](#fixed-fields-7) - [Success Action Object Example](#success-action-object-example) @@ -467,18 +467,10 @@ my.org.User ```json "components": { "inputs": { - "paginationInputs": { - "type": "object", - "properties": { - "page": { - "type": "integer", - "format": "int32" - }, - "pageSize": { - "type": "integer", - "format": "int32" - } - } + "storeId": { + "name": "storeId", + "in": "header", + "value": "$inputs.x-store-id" } }, "steps": { @@ -498,10 +490,18 @@ my.org.User } }, "parameters": { - "storeId": { - "name": "storeId", - "in": "header", - "value": "$inputs.x-store-id" + "pagination": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + } + } } } } From b7844a09cd14865547f6ede669d7c6d92238d62a Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Fri, 28 Apr 2023 15:36:21 -0400 Subject: [PATCH 04/25] add and consume reference object Signed-off-by: Shai Sachs --- versions/1.0.0.md | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 6877f49..5753a48 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -48,11 +48,14 @@ The Workflows Specification can articulate these workflows in a human and machin - [Component Object](#component-object) - [Fixed Fields](#fixed-fields-6) - [Component Object Example](#component-object-example) - - [Success Action Object](#success-action-object) + - [Reference Object](#reference-object) - [Fixed Fields](#fixed-fields-7) + - [Reference Object Example](#reference-object-example) + - [Success Action Object](#success-action-object) + - [Fixed Fields](#fixed-fields-8) - [Success Action Object Example](#success-action-object-example) - [Failure Action Object](#failure-action-object) - - [Fixed Fields](#fixed-fields-7) + - [Fixed Fields](#fixed-fields-9) - [Failure Action Object Example](#failure-action-object-example) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) @@ -254,7 +257,7 @@ Field Name | Type | Description summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` or `string` | A JSON Schema object representing the input parameters used by this workflow. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `inputs` field. -steps | [[Step Object](#step-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `steps` field. +steps | [[Step Object](#step-object) | [Reference Object](#reference-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. 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\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -308,7 +311,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 `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. 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. 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. -parameters | [[Parameter Object](#parameter-object)] or `string` | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `parameters` field. +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 refer to a Parameter. 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 | [{expression}] | A list of assertions to determine the success of the step 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. @@ -507,6 +510,37 @@ my.org.User } ``` +#### Reference Object + +**Note -** This section is copied from the [OpenAPI Specification, v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion. + +A simple object to allow referencing other components in the OpenAPI document, internally and externally. + +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#relativeReferencesURI). + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI, with a prefix of `#/components/inputs`, `#/components/steps`, or `#/components/parameters`. +summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not allow a `summary` field, then this field has no effect. +description | `string` | A description which by default SHOULD override that of the referenced component. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does not allow a `description` field, then this field has no effect. + +This object cannot be extended with additional properties and any properties added SHALL be ignored. + +##### Reference Object Example + +```json +{ + "$ref": "#/components/inputs/storeId" +} +``` + +```yaml +$ref: '#/components/inputs/storeId' +``` + #### Success Action Object A single success action which describes an action to take upon success of a workflow step. From 9fbf292f4a279ee069ae8d009e8694157d04e506 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Fri, 28 Apr 2023 16:21:24 -0400 Subject: [PATCH 05/25] add example of reusing steps and parameters Signed-off-by: Shai Sachs --- examples/1.0.0/pet-coupons.openapi.yaml | 13 +++ examples/1.0.0/pet-coupons.workflow.yaml | 81 ++++++++++------ versions/1.0.0.md | 112 ++++++++++++----------- 3 files changed, 124 insertions(+), 82 deletions(-) diff --git a/examples/1.0.0/pet-coupons.openapi.yaml b/examples/1.0.0/pet-coupons.openapi.yaml index b8cc131..a11f5ba 100644 --- a/examples/1.0.0/pet-coupons.openapi.yaml +++ b/examples/1.0.0/pet-coupons.openapi.yaml @@ -113,6 +113,19 @@ paths: - available - pending - sold + - name: page + in: query + description: Which page of results to display. First page is 1. + required: true + schema: + type: int32 + - name: pageSize + in: query + description: Number of results to display per page. + required: false + schema: + type: int32 + default: 10 responses: '200': description: successful operation diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index ed099a5..485048e 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -49,35 +49,62 @@ workflows: - $statusCode == 200 outputs: my_coupon_code: $response.body.couponCode - - stepId: place-order - description: Use the coupon to get a discount on the desired pet. - operationId: placeOrder + - $ref: '#/components/steps/placeOrder' + - workflowId: buy-available-pet + summary: Buy an available pet if one is available. + description: + This workflow demonstrates a workflow very similar to `apply-coupon`, by intention. + It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`). + steps: + - stepId: find-pet + operationId: findPetsByStatus parameters: - - name: pet_id - in: body - target: $request.body#/petId - value: $steps.find-pet.outputs.my_pet_id - - name: coupon_code - in: body - target: $request.body#/couponCode - value: $steps.find-pet.outputs.my_coupon_code - - name: quantity - in: body - target: $request.body#/quantity - value: 1 - name: status - in: body - target: $request.body#/status - value: "placed" - - name: complete - in: body - target: $request.body#/complete - value: false + in: query + value: "available" + - $ref: '#/components/parameters/page' + value: 1 + - $ref: '#/components/parameters/pageSize' + value: 1 successCriteria: - $statusCode == 200 outputs: - my_order_id: $response.body.id - - - outputs: - order_id: $steps.place-order.my_order_id + my_pet_id: $outputs[0].id + - $ref: '#/components/steps/placeOrder' +components: + steps: + placeOrder: + description: This step places an order, and may be reused by many other steps - e.g., upon successful search for a Pet. + operationId: postCartItems + parameters: + - name: pet_id + in: body + target: $request.body#/petId + value: $steps.find-pet.outputs.my_pet_id + - name: coupon_code + in: body + target: $request.body#/couponCode + value: $steps.find-pet.outputs.my_coupon_code + - name: quantity + in: body + target: $request.body#/quantity + value: 1 + - name: status + in: body + target: $request.body#/status + value: "placed" + - name: complete + in: body + target: $request.body#/complete + value: false + successCriteria: + - $statusCode == 200 + outputs: + my_order_id: $response.body.id + parameters: + page: + type: integer + format: int32 + pageSize: + type: integer + format: int32 diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 5753a48..d16205c 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -45,18 +45,18 @@ The Workflows Specification can articulate these workflows in a human and machin - [Parameter Object](#parameter-object) - [Fixed Fields](#fixed-fields-5) - [Parameter Object Example](#parameter-object-example) - - [Component Object](#component-object) - - [Fixed Fields](#fixed-fields-6) - - [Component Object Example](#component-object-example) - - [Reference Object](#reference-object) - - [Fixed Fields](#fixed-fields-7) - - [Reference Object Example](#reference-object-example) - [Success Action Object](#success-action-object) - - [Fixed Fields](#fixed-fields-8) + - [Fixed Fields](#fixed-fields-6) - [Success Action Object Example](#success-action-object-example) - [Failure Action Object](#failure-action-object) - - [Fixed Fields](#fixed-fields-9) + - [Fixed Fields](#fixed-fields-7) - [Failure Action Object Example](#failure-action-object-example) + - [Component Object](#component-object) + - [Fixed Fields](#fixed-fields-8) + - [Component Object Example](#component-object-example) + - [Reference Object](#reference-object) + - [Fixed Fields](#fixed-fields-9) + - [Reference Object Example](#reference-object-example) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) - [Appendix A: Revision History](#appendix-a-revision-history) @@ -127,6 +127,7 @@ Field Name | Type | Description info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. The metadata MAY be used by tooling as required. 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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. +workflows | [Component Object](#component-object) | An object containing 0 or more components. This object MAY be extended with [Specification Extensions](#specification-extensionsxtensions). @@ -439,6 +440,53 @@ Field Name | Type | Description ``` This object MAY be extended with [Specification Extensions](#specification-extensions). +#### Success Action Object + +A single success action which describes an action to take upon success of a workflow step. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- + type | string | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"` + stepId | string | The `stepId` to jump to based on the success of the step. This field is only relevant when the `type` field value is `goto`. The value of the `stepId` MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as _workflowId.stepId_. + criteria | [{expression}] | A list of assertions to determine if this action SHALL be executed. + +**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. + +##### Success Action Object Example +``` +type: goto +stepId: joinWaitingListStep +criteria: + # assertions to determine if this success action should be executed + - $response.body.Pets.length() > 0 +``` + +#### Failure Action Object + +A single failure action which describes an action to take upon success of a workflow step. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- + type | string | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"goto"` or `"retry"` + stepId | string | The `stepId` to jump to based on the failure of the step. This field is only relevant when the `type` field value is `goto`. The value of the `stepId` MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as _workflowId.stepId_. + retryAfter | number | A non-negative decimal indicating the milliseconds delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `retry`. + retryLimit | integer | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `retry`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. + criteria | [{expression}] | A list of assertions to determine if this action SHALL be executed. + +**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. + +##### Failure Action Object Example +``` +type: retry +retryAfter: 1000 +retryLimit: 5 +criteria: + # assertions to determine if this action should be executed + - $statusCode == 503 +``` + #### Component Object Holds a set of reusable objects for different aspects of the Workflows Specification. All objects defined within the components object will have no effect on the workflow unless they are explicitly referenced from properties outside the components object. @@ -465,7 +513,7 @@ user-name my.org.User ``` -##### Components Object Example +##### Component Object Example ```json "components": { @@ -541,52 +589,6 @@ This object cannot be extended with additional properties and any properties add $ref: '#/components/inputs/storeId' ``` -#### Success Action Object - -A single success action which describes an action to take upon success of a workflow step. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- - type | string | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"` - stepId | string | The `stepId` to jump to based on the success of the step. This field is only relevant when the `type` field value is `goto`. The value of the `stepId` MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as _workflowId.stepId_. - criteria | [{expression}] | A list of assertions to determine if this action SHALL be executed. - -**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. - -##### Success Action Object Example -``` -type: goto -stepId: joinWaitingListStep -criteria: - # assertions to determine if this success action should be executed - - $response.body.Pets.length() > 0 -``` - -#### Failure Action Object - -A single failure action which describes an action to take upon success of a workflow step. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- - type | string | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"goto"` or `"retry"` - stepId | string | The `stepId` to jump to based on the failure of the step. This field is only relevant when the `type` field value is `goto`. The value of the `stepId` MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as _workflowId.stepId_. - retryAfter | number | A non-negative decimal indicating the milliseconds delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `retry`. - retryLimit | integer | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `retry`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. - criteria | [{expression}] | A list of assertions to determine if this action SHALL be executed. - -**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. - -##### Failure Action Object Example -``` -type: retry -retryAfter: 1000 -retryLimit: 5 -criteria: - # assertions to determine if this action should be executed - - $statusCode == 503 -``` ### Runtime Expressions A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Workflows document such as [workflows](#workflow-object) or [steps](#step-object). From dd367b9989d25e68c28f62d1dc0e94fc530ba2c8 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 10 May 2023 13:02:25 -0400 Subject: [PATCH 06/25] fix components row Signed-off-by: Shai Sachs --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d16205c..ff4bd0b 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. The metadata MAY be used by tooling as required. 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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. -workflows | [Component Object](#component-object) | An object containing 0 or more components. +components | [Component Object](#component-object) | An object containing 0 or more components. This object MAY be extended with [Specification Extensions](#specification-extensionsxtensions). From d556b2b55a058ea85f5b71660881888955add2a1 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Thu, 18 May 2023 06:16:59 -0400 Subject: [PATCH 07/25] add overridable value property (OAI#43) Signed-off-by: Shai Sachs --- versions/1.0.0.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index ff4bd0b..dca8a4c 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -560,7 +560,7 @@ my.org.User #### Reference Object -**Note -** This section is copied from the [OpenAPI Specification, v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion. +**Note -** This section is derived from the [OpenAPI Specification, v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion. A simple object to allow referencing other components in the OpenAPI document, internally and externally. @@ -571,22 +571,21 @@ See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI, with a prefix of `#/components/inputs`, `#/components/steps`, or `#/components/parameters`. -summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not allow a `summary` field, then this field has no effect. -description | `string` | A description which by default SHOULD override that of the referenced component. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does not allow a `description` field, then this field has no effect. - -This object cannot be extended with additional properties and any properties added SHALL be ignored. +$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI, with a prefix of `#/components/inputs` or `#/components/parameters`. +value | `string` | The value of the Input or Parameter which by default SHOULD override that of the referenced component. ##### Reference Object Example ```json { - "$ref": "#/components/inputs/storeId" + "$ref": "#/components/parameters/page", + "value": 1 } ``` ```yaml -$ref: '#/components/inputs/storeId' +"$ref": "#/components/parameters/page" +value: 1 ``` From 5946142facca9413d43d0557f3e4c7d6fd1af0e3 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Fri, 19 May 2023 06:40:21 -0400 Subject: [PATCH 08/25] allow input refs (OAI#43) Signed-off-by: Shai Sachs --- examples/1.0.0/pet-coupons.workflow.yaml | 11 +++++++++++ versions/1.0.0.md | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 485048e..c8a13e6 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -24,6 +24,8 @@ workflows: items: type: string description: Desired tags to use when searching for a pet, in CSV format: e.g. "puppy, dalmation" + store_id: + $ref: "#/components/inputs/store_id" steps: - stepId: find-pet operationId: findPetsByTags @@ -55,6 +57,11 @@ workflows: description: This workflow demonstrates a workflow very similar to `apply-coupon`, by intention. It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`). + inputs: + type: object + properties: + store_id: + $ref: "#/components/inputs/store_id" steps: - stepId: find-pet operationId: findPetsByStatus @@ -72,6 +79,10 @@ workflows: my_pet_id: $outputs[0].id - $ref: '#/components/steps/placeOrder' components: + inputs: + store_id: + type: string + 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". steps: placeOrder: description: This step places an order, and may be reused by many other steps - e.g., upon successful search for a Pet. diff --git a/versions/1.0.0.md b/versions/1.0.0.md index dca8a4c..134ee93 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -257,7 +257,7 @@ Field Name | Type | Description workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows document. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -inputs | `JSON Schema` or `string` | A JSON Schema object representing the input parameters used by this workflow. If a `string` is provided, it must correspond to the key of the [[Component Object]](#component-object)'s `inputs` field. +inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. Some of the input parameters may be [References](#reference-object) to the [[Component Object]](#component-object)'s `inputs` field. steps | [[Step Object](#step-object) | [Reference Object](#reference-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. 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\.\-_]+$`. From c627f16a5183416f186d574e765db6f8c80a2eab Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Sat, 20 May 2023 06:36:04 -0400 Subject: [PATCH 09/25] remove mention of references in workflowinputs (OAI#43) Signed-off-by: Shai Sachs --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 134ee93..ddd3c14 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -257,7 +257,7 @@ Field Name | Type | Description workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows document. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. Some of the input parameters may be [References](#reference-object) to the [[Component Object]](#component-object)'s `inputs` field. +inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. steps | [[Step Object](#step-object) | [Reference Object](#reference-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. 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\.\-_]+$`. From 9d458228a7a6a5eaf10c437a568950c6c7c88cdc Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Sat, 20 May 2023 06:59:39 -0400 Subject: [PATCH 10/25] unwind components in steps; use reusable workflows Signed-off-by: Shai Sachs --- examples/1.0.0/pet-coupons.workflow.yaml | 100 ++++++++++++++++------- versions/1.0.0.md | 19 +---- 2 files changed, 70 insertions(+), 49 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index c8a13e6..d3b5132 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -51,7 +51,19 @@ workflows: - $statusCode == 200 outputs: my_coupon_code: $response.body.couponCode - - $ref: '#/components/steps/placeOrder' + - stepId: place-order + workflowId: place-order + parameters: + - name: pet_id + in: body + value: $steps.find-pet.outputs.my_pet_id + - name: coupon_code + in: body + value: $steps.find-coupons.outputs.my_coupon_code + successCriteria: + - $statusCode == 200 + outputs: + my_order_id: $response.body.id - workflowId: buy-available-pet summary: Buy an available pet if one is available. description: @@ -77,41 +89,67 @@ workflows: - $statusCode == 200 outputs: my_pet_id: $outputs[0].id - - $ref: '#/components/steps/placeOrder' + - stepId: place-order + workflowId: place-order + parameters: + - name: pet_id + in: body + value: $steps.find-pet.outputs.my_pet_id + successCriteria: + - $statusCode == 200 + outputs: + my_order_id: $response.body.id + - workflowId: place-order + summary: Place an order for a pet. + description: + This workflow places an order for a pet. It may be reused by other workflows as the "final step" in a purchase. + inputs: + type: object + properties: + pet_id: + type: integer + format: int64 + description: The ID of the pet to place in the order. + quantity: + type: integer + format: int32 + description: The number of pets to place in the order. + value: 1 + coupon_code: + type: string + description: The coupon code to apply to the order. + steps: + - stepId: place-order + operationId: placeOrder + parameters: + - name: pet_id + in: body + target: $request.body#/petId + value: $inputs.pet_id + - name: coupon_code + in: body + target: $request.body#/couponCode + value: $inputs.coupon_code + - name: quantity + in: body + value: $inputs.quantity + - name: status + in: body + target: $request.body#/status + value: "placed" + - name: complete + in: body + target: $request.body#/complete + value: false + successCriteria: + - $statusCode == 200 + outputs: + my_order_id: $response.body.id components: inputs: store_id: type: string 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". - steps: - placeOrder: - description: This step places an order, and may be reused by many other steps - e.g., upon successful search for a Pet. - operationId: postCartItems - parameters: - - name: pet_id - in: body - target: $request.body#/petId - value: $steps.find-pet.outputs.my_pet_id - - name: coupon_code - in: body - target: $request.body#/couponCode - value: $steps.find-pet.outputs.my_coupon_code - - name: quantity - in: body - target: $request.body#/quantity - value: 1 - - name: status - in: body - target: $request.body#/status - value: "placed" - - name: complete - in: body - target: $request.body#/complete - value: false - successCriteria: - - $statusCode == 200 - outputs: - my_order_id: $response.body.id parameters: page: type: integer diff --git a/versions/1.0.0.md b/versions/1.0.0.md index ddd3c14..6ec6338 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -496,12 +496,11 @@ Holds a set of reusable objects for different aspects of the Workflows Specifica Field Name | Type | Description ---|:---|--- inputs | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. - steps | Map[string, [Step Object](#step-object)] | An object to hold a reusable Step Objects. parameters | Map[string, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects This object MAY NOT be extended with [Specification Extensions](#specificationExtensions). -All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input, step, or parameter in other parts of the Workflow document. +All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow document. Field Name Examples: @@ -524,22 +523,6 @@ my.org.User "value": "$inputs.x-store-id" } }, - "steps": { - "addItemToCart": { - "description": "This step adds an item to the cart, and may be reused by many other steps - e.g., upon successful search for a Pet.", - "operationId": "postCartItems", - "parameters": { - "name": "sku", - "in": "query" - }, - "successCriteria": { - "$statusCode": "201" - }, - "outputs": { - "cartTotal": "$response.body.cartTotal" - } - } - }, "parameters": { "pagination": { "type": "object", From 9f553c88b08596751e3bef991f131064da1138dd Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Fri, 26 May 2023 17:00:31 -0400 Subject: [PATCH 11/25] update example to use JSON Schema more correctly Signed-off-by: Shai Sachs --- examples/1.0.0/pet-coupons.workflow.yaml | 30 ++++++++++++++---------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index d3b5132..4c4235c 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -17,15 +17,7 @@ workflows: This is how you can find a pet, find an applicable coupon, and apply that coupon in your order. The workflow concludes by outputting the ID of the placed order. inputs: - type: object - properties: - my_pet_tags: - type: array - items: - type: string - description: Desired tags to use when searching for a pet, in CSV format: e.g. "puppy, dalmation" - store_id: - $ref: "#/components/inputs/store_id" + $ref: "#/components/inputs/apply_coupon_input" steps: - stepId: find-pet operationId: findPetsByTags @@ -70,10 +62,7 @@ workflows: This workflow demonstrates a workflow very similar to `apply-coupon`, by intention. It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`). inputs: - type: object - properties: - store_id: - $ref: "#/components/inputs/store_id" + $ref: "#/components/inputs/buy_available_pet_input" steps: - stepId: find-pet operationId: findPetsByStatus @@ -147,6 +136,21 @@ workflows: my_order_id: $response.body.id components: inputs: + apply_coupon_input: + type: object + properties: + my_pet_tags: + type: array + items: + type: string + description: Desired tags to use when searching for a pet, in CSV format: e.g. "puppy, dalmation" + store_id: + $ref: "#/components/inputs/store_id" + buy_available_pet_input: + type: object + properties: + store_id: + $ref: "#/components/inputs/store_id" store_id: type: string 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". From 27b3bfadc1836b9810cd7296bed691b73fbcc913 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 7 Jun 2023 22:19:48 -0400 Subject: [PATCH 12/25] fix formatting, more standard component description Signed-off-by: Shai Sachs --- examples/1.0.0/pet-coupons.workflow.yaml | 2 +- versions/1.0.0.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 4c4235c..1482cd3 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -73,7 +73,7 @@ workflows: - $ref: '#/components/parameters/page' value: 1 - $ref: '#/components/parameters/pageSize' - value: 1 + value: 10 successCriteria: - $statusCode == 200 outputs: diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 6ec6338..f71d01b 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -127,7 +127,7 @@ Field Name | Type | Description info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. The metadata MAY be used by tooling as required. 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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. -components | [Component Object](#component-object) | An object containing 0 or more components. +components | [Component Object](#component-object) | An element to hold various schemas for the document. This object MAY be extended with [Specification Extensions](#specification-extensionsxtensions). @@ -258,7 +258,7 @@ Field Name | Type | Description summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. -steps | [[Step Object](#step-object) | [Reference Object](#reference-object)] or `string` | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. +steps | [[Step Object](#step-object) \| [Reference Object](#reference-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. 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\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -495,8 +495,8 @@ Holds a set of reusable objects for different aspects of the Workflows Specifica Field Name | Type | Description ---|:---|--- - inputs | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. -parameters | Map[string, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects + inputs | Map[`string`, JSON Schema Object] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. +parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects This object MAY NOT be extended with [Specification Extensions](#specificationExtensions). From d965fbb5286956d90e1f9638d6daa0a931115f7e Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 5 Jul 2023 10:04:04 +0100 Subject: [PATCH 13/25] Update versions/1.0.0.md reverting steps back to original description --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index f71d01b..b3c00a9 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -258,7 +258,7 @@ Field Name | Type | Description summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. -steps | [[Step Object](#step-object) \| [Reference Object](#reference-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. If a Reference Object is provided, it MUST refer to a Step. +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. 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\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). From f81036386c558db664c5171c4e7d5843585f79c7 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 5 Jul 2023 10:08:07 +0100 Subject: [PATCH 14/25] Update versions/1.0.0.md I do not see why we would not allow extensibility here if so desired by authors. --- versions/1.0.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index b3c00a9..78abe76 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -498,7 +498,8 @@ Field Name | Type | Description inputs | Map[`string`, JSON Schema Object] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects -This object MAY NOT be extended with [Specification Extensions](#specificationExtensions). +This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). + All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow document. From d0d9015ccfd48eddad33f2eb69cb64785e0fb2ca Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 5 Jul 2023 10:31:39 +0100 Subject: [PATCH 15/25] typo in reference object section --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 78abe76..37bc362 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -546,7 +546,7 @@ my.org.User **Note -** This section is derived from the [OpenAPI Specification, v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion. -A simple object to allow referencing other components in the OpenAPI document, internally and externally. +A simple object to allow referencing other components in the Workflows document. The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the location of the value being referenced. From 4bfb132119781b18816aa4cea8b19fe0c2cc2772 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 5 Jul 2023 11:23:35 +0100 Subject: [PATCH 16/25] tidy up components and reference object additions --- examples/1.0.0/pet-coupons.workflow.yaml | 3 +-- versions/1.0.0.md | 31 ++++++++++-------------- 2 files changed, 14 insertions(+), 20 deletions(-) diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 1482cd3..4712350 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -103,7 +103,6 @@ workflows: type: integer format: int32 description: The number of pets to place in the order. - value: 1 coupon_code: type: string description: The coupon code to apply to the order. @@ -143,7 +142,7 @@ components: type: array items: type: string - description: Desired tags to use when searching for a pet, in CSV format: e.g. "puppy, dalmation" + description: Desired tags to use when searching for a pet, in CSV format (e.g. "puppy, dalmatian") store_id: $ref: "#/components/inputs/store_id" buy_available_pet_input: diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 47b6d38..b628650 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -61,7 +61,6 @@ The Workflows Specification can articulate these workflows in a human and machin - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) - [Appendix A: Revision History](#appendix-a-revision-history) - - [Appendix B: Questions and Ideas](#appendix-b-open-questions-and-ideas) ## Definitions @@ -293,7 +292,7 @@ steps: in: query value: $inputs.password successCriteria: - # assertions to determine step was successful (see open question 3 in Appendix B) + # assertions to determine step was successful $statusCode == 200 outputs: # outputs from this step @@ -316,7 +315,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 `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. 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. 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. -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 refer to a Parameter. +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). 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 | [{expression}] | A list of assertions to determine the success of the step 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. @@ -506,8 +505,8 @@ Holds a set of reusable objects for different aspects of the Workflows Specifica Field Name | Type | Description ---|:---|--- - inputs | Map[`string`, JSON Schema Object] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. -parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects + inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. +parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects This object _MAY_ be extended with [Specification Extensions](#specificationExtensions). @@ -555,10 +554,10 @@ my.org.User #### Reference Object -**Note -** This section is derived from the [OpenAPI Specification, v3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), and is intended to be implemented in similar fashion. - A simple object to allow referencing other components in the Workflows document. +**Note -** This section is derived from the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject), 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#relativeReferencesURI). @@ -566,20 +565,22 @@ See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI, with a prefix of `#/components/inputs` or `#/components/parameters`. -value | `string` | The value of the Input or Parameter which by default SHOULD override that of the referenced component. +$ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI. +value | `string` | A value by default SHOULD override that of the referenced component. If the referenced object-type does not have a `value` field, then it has no effect. + +This object cannot be extended with additional properties and any properties added SHALL be ignored. ##### Reference Object Example ```json { "$ref": "#/components/parameters/page", - "value": 1 + "value": 1 } ``` ```yaml - "$ref": "#/components/parameters/page" + $ref: "#/components/parameters/page" value: 1 ``` @@ -648,13 +649,7 @@ Version | Date | Notes 1.0.0 | TBD | First release of the Workflows Specification -## Appendix B: Open Questions and Ideas - -1. What Expression syntax should be used? Initial framing leverages OpenAPI expression syntax as used by Link Object and extend to cover also AsyncAPI needs as well as workflow specific needs. -2. For success criteria, JSONPath or JSON Pointer and/or custom evaluation rules (similar to GitHub action expressions)? Should we combine with runtime expressions or handle separately? - - -## Appendix C: Contextual scope / access for inputs and outputs +## Appendix B: Contextual scope / access for inputs and outputs This quick image is to add some context / scope access overview for `inputs`, `step parameters`, `step outputs` and `workflow outputs` From 8c26d397d1aa20a0e9998661b5f8cf67da49014a Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Tue, 18 Jul 2023 22:32:51 -0400 Subject: [PATCH 17/25] replace source name with sourceId Signed-off-by: Shai Sachs --- examples/1.0.0/FAPI-PAR.workflow.yaml | 2 +- examples/1.0.0/LoginAndRetrievePets.yaml | 2 +- examples/1.0.0/oauth.workflow.yaml | 4 ++-- examples/1.0.0/pet-coupons.workflow.yaml | 2 +- versions/1.0.0.md | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.workflow.yaml index 3c5b5bb..1801023 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/examples/1.0.0/FAPI-PAR.workflow.yaml @@ -5,7 +5,7 @@ info: 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: - - name: auth-api + - sourceId: auth-api url: ./FAPI-PAR.openapi.yaml type: openapi diff --git a/examples/1.0.0/LoginAndRetrievePets.yaml b/examples/1.0.0/LoginAndRetrievePets.yaml index 0f245d0..1e750d2 100644 --- a/examples/1.0.0/LoginAndRetrievePets.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.yaml @@ -6,7 +6,7 @@ info: This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sources: -- name: petStoreDefinition +- sourceId: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index 6e45d28..3a094e2 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.workflow.yaml @@ -5,11 +5,11 @@ info: description: >- APImetrics OAuth service sources: - - name: apim-auth + - sourceId: apim-auth url: ./oauth.openapi.yaml type: openapi # This is how you can reference another workflow file - # - name: sample + # - sourceId: sample # url: ./sample.workflows.yml # type: workflowSpec diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 4712350..b7c39dc 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -7,7 +7,7 @@ info: b) finds coupons for that pet, and finally c) orders the pet while applying the coupons from step b. sources: - - name: pet-coupons + - sourceId: pet-coupons url: ./pet-coupons.openapi.yaml type: openapi workflows: diff --git a/versions/1.0.0.md b/versions/1.0.0.md index b628650..5fa53b4 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -142,7 +142,7 @@ info: This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sources: -- name: petStoreDefinition +- id: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi @@ -234,7 +234,7 @@ An object storing a map between named document keys and location URLs to the sou Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. A unique name for the source document. +sourceId | `string` | **REQUIRED**. Unique string to represent the source. The id MUST be unique amongst all sources describe in the Workflows document. The `sourceId` value is **case-sensitive**. Tools and libraries MAY use the `sourceId` to uniquely identify a source, therefore, it is RECOMMENDED to follow common programming naming conventions. 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). type | `string` | The type of source document. Possible values are `"openapi"`, `"asyncapi"`, or `"workflowsSpec"`. @@ -244,7 +244,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten ##### Source Object Example ```yaml -name: petStoreDefinition +id: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` From 65e0c21622ab3fd49e66820020e7329126e8d281 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Tue, 18 Jul 2023 22:37:26 -0400 Subject: [PATCH 18/25] add workflowIdSourceId to disambiguate workflowId collisions Signed-off-by: Shai Sachs --- versions/1.0.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 5fa53b4..1df7740 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -314,7 +314,8 @@ Field Name | Type | Description 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. 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. 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. -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. +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. In the event that two workflows with the same `workflowId` are available, because they are both defined in separate [Sources](#source-object), then the provided value MUST contain the +workflowIdSourceId | `string` | Optional. The `sourceId` of the [Source](#source-object) where the Workflow identified by `workflowId` is defined. Required in cases where multiple [Sources](#source-object) define different workflows with colliding values of `workflowId`. 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). 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 | [{expression}] | A list of assertions to determine the success of the step From 5b8e4e5ff994bfdad08c02851e4f85a08b7fc25b Mon Sep 17 00:00:00 2001 From: Shai Sachs <910582+shaisachs@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:41:49 -0400 Subject: [PATCH 19/25] Correct id/sourceId --- versions/1.0.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 1df7740..e003e3f 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -142,7 +142,8 @@ info: This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sources: -- id: petStoreDefinition +- sourceId: petStoreDefinition + url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi From 532e99ca373b7febb5b7f568c9140dd6f7fc6d3e Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Tue, 18 Jul 2023 22:42:49 -0400 Subject: [PATCH 20/25] fix source object example Signed-off-by: Shai Sachs --- versions/1.0.0.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index e003e3f..9910a69 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -143,7 +143,6 @@ info: version: 1.0.1 sources: - sourceId: petStoreDefinition - url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi @@ -245,7 +244,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten ##### Source Object Example ```yaml -id: petStoreDefinition +sourceId: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` From 4f1d7ff51da0f7c75da0821bfe8a735f1fcabd13 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 19 Jul 2023 12:17:33 -0400 Subject: [PATCH 21/25] better disambiguation language as used in operationid. Signed-off-by: Shai Sachs --- versions/1.0.0.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 9910a69..94011dc 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -314,8 +314,7 @@ Field Name | Type | Description 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. 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. 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. -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. In the event that two workflows with the same `workflowId` are available, because they are both defined in separate [Sources](#source-object), then the provided value MUST contain the -workflowIdSourceId | `string` | Optional. The `sourceId` of the [Source](#source-object) where the Workflow identified by `workflowId` is defined. Required in cases where multiple [Sources](#source-object) define different workflows with colliding values of `workflowId`. +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. 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). 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 | [{expression}] | A list of assertions to determine the success of the step From 06211ec54fa471284c6a9946a4a793ed4dae9d04 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 19 Jul 2023 12:34:39 -0400 Subject: [PATCH 22/25] revert to name and add regex Signed-off-by: Shai Sachs --- examples/1.0.0/FAPI-PAR.workflow.yaml | 2 +- examples/1.0.0/LoginAndRetrievePets.yaml | 2 +- examples/1.0.0/oauth.workflow.yaml | 4 ++-- examples/1.0.0/pet-coupons.workflow.yaml | 2 +- versions/1.0.0.md | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.workflow.yaml index 1801023..3c5b5bb 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/examples/1.0.0/FAPI-PAR.workflow.yaml @@ -5,7 +5,7 @@ info: 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: - - sourceId: auth-api + - name: auth-api url: ./FAPI-PAR.openapi.yaml type: openapi diff --git a/examples/1.0.0/LoginAndRetrievePets.yaml b/examples/1.0.0/LoginAndRetrievePets.yaml index 1e750d2..0f245d0 100644 --- a/examples/1.0.0/LoginAndRetrievePets.yaml +++ b/examples/1.0.0/LoginAndRetrievePets.yaml @@ -6,7 +6,7 @@ info: This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sources: -- sourceId: petStoreDefinition +- name: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index 3a094e2..6e45d28 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/examples/1.0.0/oauth.workflow.yaml @@ -5,11 +5,11 @@ info: description: >- APImetrics OAuth service sources: - - sourceId: apim-auth + - name: apim-auth url: ./oauth.openapi.yaml type: openapi # This is how you can reference another workflow file - # - sourceId: sample + # - name: sample # url: ./sample.workflows.yml # type: workflowSpec diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index b7c39dc..4712350 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/examples/1.0.0/pet-coupons.workflow.yaml @@ -7,7 +7,7 @@ info: b) finds coupons for that pet, and finally c) orders the pet while applying the coupons from step b. sources: - - sourceId: pet-coupons + - name: pet-coupons url: ./pet-coupons.openapi.yaml type: openapi workflows: diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 94011dc..46210b4 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -142,7 +142,7 @@ info: This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sources: -- sourceId: petStoreDefinition +- name: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi @@ -234,7 +234,7 @@ An object storing a map between named document keys and location URLs to the sou Field Name | Type | Description ---|:---:|--- -sourceId | `string` | **REQUIRED**. Unique string to represent the source. The id MUST be unique amongst all sources describe in the Workflows document. The `sourceId` value is **case-sensitive**. Tools and libraries MAY use the `sourceId` to uniquely identify a source, therefore, it is RECOMMENDED to follow common programming naming conventions. +name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression [A-Za-z0-9_\-]+. 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). type | `string` | The type of source document. Possible values are `"openapi"`, `"asyncapi"`, or `"workflowsSpec"`. @@ -244,7 +244,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten ##### Source Object Example ```yaml -sourceId: petStoreDefinition +name: petStoreDefinition url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` From ab337869f98111fca2b9a41f017f0065e8987913 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 19 Jul 2023 12:41:43 -0400 Subject: [PATCH 23/25] rename sources to sourceDocuments Signed-off-by: Shai Sachs --- examples/1.0.0/FAPI-PAR.workflow.yaml | 2 +- examples/1.0.0/LoginAndRetrievePets.yaml | 2 +- examples/1.0.0/oauth.workflow.yaml | 5 +---- examples/1.0.0/pet-coupons.workflow.yaml | 2 +- versions/1.0.0.md | 14 +++++++------- 5 files changed, 11 insertions(+), 14 deletions(-) diff --git a/examples/1.0.0/FAPI-PAR.workflow.yaml b/examples/1.0.0/FAPI-PAR.workflow.yaml index 3c5b5bb..2ba3651 100644 --- a/examples/1.0.0/FAPI-PAR.workflow.yaml +++ b/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 diff --git a/examples/1.0.0/LoginAndRetrievePets.yaml b/examples/1.0.0/LoginAndRetrievePets.yaml index 0f245d0..de05138 100644 --- a/examples/1.0.0/LoginAndRetrievePets.yaml +++ b/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 diff --git a/examples/1.0.0/oauth.workflow.yaml b/examples/1.0.0/oauth.workflow.yaml index 6e45d28..aff9f0c 100644 --- a/examples/1.0.0/oauth.workflow.yaml +++ b/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 diff --git a/examples/1.0.0/pet-coupons.workflow.yaml b/examples/1.0.0/pet-coupons.workflow.yaml index 4712350..4668e90 100644 --- a/examples/1.0.0/pet-coupons.workflow.yaml +++ b/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 diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 46210b4..642b45b 100644 --- a/versions/1.0.0.md +++ b/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-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 ---|:---:|--- 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. info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Workflows. The metadata MAY be used by tooling as required. -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. +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. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. 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. @@ -241,7 +241,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specification-extensions). -##### Source Object Example +##### Source Document Object Example ```yaml name: petStoreDefinition From 05dc5d03e8d7e6fab875fe89cfd0df46156d2f99 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 19 Jul 2023 12:45:57 -0400 Subject: [PATCH 24/25] fix markdown Signed-off-by: Shai Sachs --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 642b45b..a51304d 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -234,7 +234,7 @@ An object storing a map between named document keys and location URLs to the sou Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression [A-Za-z0-9_\-]+. +name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression `[A-Za-z0-9_\-]+`. 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). type | `string` | The type of source document. Possible values are `"openapi"`, `"asyncapi"`, or `"workflowsSpec"`. From 6852e00522811e1428c9b97e843191bcd792e735 Mon Sep 17 00:00:00 2001 From: Shai Sachs Date: Wed, 19 Jul 2023 14:09:17 -0400 Subject: [PATCH 25/25] fix link Signed-off-by: Shai Sachs --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index a51304d..abf7f08 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -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 `sourceDocuments` 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