Skip to content

Commit

Permalink
Improve verbiage for criteria and unique fields
Browse files Browse the repository at this point in the history
  • Loading branch information
@frankkilcommins
frankkilcommins committed Oct 26, 2023
1 parent f8f34dc commit 63e9d67
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions versions/1.0.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ An object storing a map between named document keys and location URLs to the sou

Field Name | Type | Description
---|:---:|---
<a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source document. MUST conform to the regular expression `[A-Za-z0-9_\-]+`.
<a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source document. Tools and libraries MAY use the `name` to uniquely identify a source document, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
<a name="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source document to be used by a Workflow. MUST be in the form of a [URL](https://url.spec.whatwg.org/). MAY be defined using relative references as defined by [RFC3986](https://spec.openapis.org/oas/latest.html#bib-RFC3986).
<a name="infoType"></a>type | `string` | The type of source document. Possible values are `"openapi"` or `"workflowsSpec"`.

Expand All @@ -260,7 +260,7 @@ Describes the steps to be taken across one or more APIs to achieve an objective.

Field Name | Type | Description
---|:---:|---
<a name="workflowId"></a>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.
<a name="workflowId"></a>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. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
<a name="workflowSummary"></a>summary | `string` | A summary of the purpose or objective of the workflow.
<a name="workflowDescription"></a>description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
Expand Down Expand Up @@ -314,13 +314,13 @@ Describes a single workflow step which MAY be a call to an API operation ([OpenA
Field Name | Type | Description
---|:---:|---
<a name="stepDescription"></a>description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The id SHOULD be unique amongst all steps described in the workflow. The stepId value is **case-sensitive**. Tools and libraries MAY use the stepId to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions.
<a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The id SHOULD be unique amongst all steps described in the workflow. The stepId value is **case-sensitive**. Tools and libraries MAY use the stepId to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
<a name="stepOperationId"></a>operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `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.
<a name="stepOperationRef"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used.
<a name="stepOperationRef"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used. The operation being referenced MUST be described within one of the `source` documents.
<a name="stepWorkflowId"></a>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.
<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#component-object).
<a name="dependsOn"></a>dependsOn | [`string`] | A list of steps that MUST be completed before this step can be processed. This helps to ensure workflow steps are executed in the correct order and that dependent steps are not processed in parallel. The values provided MUST be the be the `stepId` which uniquely references a step.
<a name="stepSuccessCriteria"></a>successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object).
<a name="stepSuccessCriteria"></a>successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful.
<a name="stepOnSuccess"></a>onSuccess | [[Success Action Object](#success-action-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior.
<a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return.
<a name="stepOutputs"></a>outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [runtime expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
Expand Down Expand Up @@ -463,7 +463,7 @@ Field Name | Type | Description
<a name="successActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`.
<a name="successWorkflowId"></a> workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document to transfer to upon success of the step. This field is only relevant when the `type` field value is `goto`. 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. This field is mutually exclusive to `stepId`.
<a name="successStepId"></a> stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `goto`. The referenced `stepId` SHOULD be within the current workflow. This field is mutually exclusive to `workflowId`.
<a name="successCriteria"></a> criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object).
<a name="successCriteria"></a> criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed.


**Note -** should multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.
Expand Down

0 comments on commit 63e9d67

Please sign in to comment.