Disambiguate workflows #59
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Shai Sachs <[email protected]>
Signed-off-by: Shai Sachs <[email protected]>
shaisachs
commented
Jul 19, 2023
Signed-off-by: Shai Sachs <[email protected]>
versions/1.0.0.md
Outdated
| @@ -314,7 +314,8 @@ Field Name | Type | Description | |||
| <a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The id SHOULD be unique amongst all steps described in the workflow. The stepId value is **case-sensitive**. Tools and libraries MAY use the stepId to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. | |||
| <a name="stepOperationId"></a>operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `source` documents. The referenced operation will be invoked by this workflow step. If more than one `source` document is defined within a Workflows document, then the `operationId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively. | |||
| <a name="stepOperationRef"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used. | |||
| <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively. | |||
| <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. 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 | |||
There was a problem hiding this comment.
The description here seems incomplete (e.g. finishes with MUST contain the).
I was thinking we'd follow on from how we clarified the operationId and just modify with workflowId:
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.
versions/1.0.0.md
Outdated
| @@ -234,7 +234,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. | |||
| <a name="sourceId"></a>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. | |||
There was a problem hiding this comment.
Is there a need to revamp the source object?
versions/1.0.0.md
Outdated
| @@ -314,7 +314,8 @@ Field Name | Type | Description | |||
| <a name="stepId"></a>stepId | `string` | **REQUIRED**. Unique string to represent the step. The id SHOULD be unique amongst all steps described in the workflow. The stepId value is **case-sensitive**. Tools and libraries MAY use the stepId to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. | |||
| <a name="stepOperationId"></a>operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `source` documents. The referenced operation will be invoked by this workflow step. If more than one `source` document is defined within a Workflows document, then the `operationId` specified MUST be prefixed with the source name to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively. | |||
| <a name="stepOperationRef"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. Relative `operationRef` values MAY be used to locate an existing. See [OpenAPI relative reference resolution rules](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI) for guidance. A complete [URI Template](https://www.rfc-editor.org/rfc/rfc6570) can also be used. | |||
| <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively. | |||
| <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows document. 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 | |||
| <a name="stepWorkflowIdSourceId"></a>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`. | |||
There was a problem hiding this comment.
Is this needed if we follow the <sourceName>.workflowId approach as we have done for operationId?
Signed-off-by: Shai Sachs <[email protected]>
Signed-off-by: Shai Sachs <[email protected]>
Signed-off-by: Shai Sachs <[email protected]>
Signed-off-by: Shai Sachs <[email protected]>
Signed-off-by: Shai Sachs <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Addresses cases where two Sources define different workflows with colliding ids by allowing Steps which reference workflow ids to identify the originating source.
Fixes #54