diff --git a/examples/1.0.0/LoginAndRetrievePets.yaml b/examples/1.0.0/LoginAndRetrievePets.workflow.yaml similarity index 100% rename from examples/1.0.0/LoginAndRetrievePets.yaml rename to examples/1.0.0/LoginAndRetrievePets.workflow.yaml diff --git a/versions/1.0.0.md b/versions/1.0.0.md index abf7f08..97ab434 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -312,9 +312,9 @@ Field Name | Type | Description ---|:---:|--- description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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. +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 (non `workflowsSpec` type) `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. 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. +workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. If more than one `workflowsSpec` type `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 @@ -456,7 +456,7 @@ A single success action which describes an action to take upon success of a work 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_. + 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 and robustness, 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. @@ -479,7 +479,7 @@ A single failure action which describes an action to take upon success of a work 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_. + 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 and robustness, 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. @@ -525,6 +525,25 @@ my.org.User ##### Component Object Example +```yaml +components: + inputs: + storeId: + name: storeId + in: header + value: $inputs.x-store-id + parameters: + pagination: + type: object + properties: + page: + type: integer + format: int32 + pageSize: + type: integer + format: int32 +``` + ```json "components": { "inputs": { @@ -572,18 +591,18 @@ This object cannot be extended with additional properties and any properties add ##### Reference Object Example -```json -{ - "$ref": "#/components/parameters/page", - "value": 1 -} -``` - ```yaml $ref: "#/components/parameters/page" value: 1 ``` +```json + { + "$ref": "#/components/parameters/page", + "value": 1 + } +``` + ### 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).