fix: pass workflow inputs to success and failure actions #2796
There are no files selected for viewing
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| --- | ||
| '@redocly/openapi-core': minor | ||
| '@redocly/cli': minor | ||
| --- | ||
|
|
||
| Added the `spec-parameters-in-by-context` Arazzo rule, which validates that a parameter's `in` field is specified when the parent workflow, step, success action, or failure action does not reference a `workflowId`. |
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| '@redocly/openapi-core': minor | ||
| '@redocly/respect-core': minor | ||
| '@redocly/cli': minor | ||
| --- | ||
|
|
||
| Extended success and failure action objects to accept a `parameters` property that maps to workflow inputs. |
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # spec-parameters-in-by-context | ||
|
|
||
| Validates how the `in` field is used on parameters based on the parent context. | ||
|
|
||
| | Arazzo | Compatibility | | ||
| | ------ | ------------- | | ||
| | 1.x | ✅ | | ||
|
|
||
| ## Design principles | ||
|
|
||
| The `in` field on an Arazzo parameter is not a required property — omitting it carries semantics. | ||
| When a step references a `workflowId`, a parameter with no `in` field is mapped to the referenced workflow's inputs. | ||
| When `in` is specified, the parameter is sent at that request location (`header`, `query`, `path`, or `cookie`) against the targeted operation. | ||
|
|
||
| This rule enforces the following: | ||
|
|
||
| - For a step that does not reference a `workflowId` (for example, one using `operationId`, `operationPath`, or `x-operation`), and for parameters defined at the workflow level, `in` must be specified on each inline parameter. | ||
| - Parameters on success and failure actions are only valid when the action references a `workflowId` — these parameters map to the referenced workflow's inputs and the spec states that `in` MUST NOT be used on them (see the [Success Action Object](https://spec.openapis.org/arazzo/latest.html#success-action-object) and [Failure Action Object](https://spec.openapis.org/arazzo/latest.html#failure-action-object)). | ||
|
|
||
| ## Configuration | ||
|
|
||
| | Option | Type | Description | | ||
| | -------- | ------ | ------------------------------------------------------- | | ||
| | severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | | ||
|
|
||
| An example configuration: | ||
|
|
||
| ```yaml | ||
| rules: | ||
| spec-parameters-in-by-context: error | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| Given the following configuration: | ||
|
|
||
| ```yaml | ||
| rules: | ||
| spec-parameters-in-by-context: error | ||
| ``` | ||
|
|
||
| Example of a **correct** step referencing an `operationId` (each parameter declares `in`): | ||
|
|
||
| ```yaml | ||
| # Correct example - operationId | ||
| workflows: | ||
| - workflowId: get-museum-hours | ||
| steps: | ||
| - stepId: list-hours | ||
| operationId: listMuseumHours | ||
| parameters: | ||
| - in: query | ||
| name: startDate | ||
| value: '2024-01-01' | ||
| ``` | ||
|
|
||
| Example of a **correct** step referencing a `workflowId` (parameters omit `in` and are mapped to the referenced workflow's inputs): | ||
|
|
||
| ```yaml | ||
| # Correct example - workflowId | ||
| workflows: | ||
| - workflowId: buy-tickets | ||
| steps: | ||
| - stepId: reuse-hours-workflow | ||
| workflowId: get-museum-hours | ||
| parameters: | ||
| - name: startDate | ||
| value: '2024-01-01' | ||
| ``` | ||
|
|
||
| Example of a **correct** success action transferring to another workflow with mapped parameters: | ||
|
|
||
| ```yaml | ||
| # Correct example - success action | ||
| workflows: | ||
| - workflowId: buy-tickets | ||
| steps: | ||
| - stepId: purchase | ||
| operationId: createTicket | ||
| onSuccess: | ||
| - name: continue-to-hours | ||
| type: goto | ||
| workflowId: get-museum-hours | ||
| parameters: | ||
| - name: startDate | ||
| value: '2024-01-01' | ||
| ``` | ||
|
|
||
| Example of an **incorrect** step referencing an `operationId` while omitting `in`: | ||
|
|
||
| ```yaml | ||
| # Incorrect example - operationId without `in` | ||
| workflows: | ||
| - workflowId: get-museum-hours | ||
| steps: | ||
| - stepId: list-hours | ||
| operationId: listMuseumHours | ||
| parameters: | ||
| - name: startDate | ||
| value: '2024-01-01' | ||
| ``` | ||
|
|
||
| Example of an **incorrect** success action defining `parameters` without referencing a `workflowId`: | ||
|
|
||
| ```yaml | ||
| # Incorrect example - action without workflowId | ||
| workflows: | ||
| - workflowId: buy-tickets | ||
| steps: | ||
| - stepId: purchase | ||
| operationId: createTicket | ||
| onSuccess: | ||
| - name: end-with-params | ||
| type: end | ||
| parameters: | ||
| - name: startDate | ||
| value: '2024-01-01' | ||
| ``` | ||
|
|
||
| ## Resources | ||
|
|
||
| - [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/spec-parameters-in-by-context.ts) | ||
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -278,6 +278,7 @@ const minimal: RawGovernanceConfig<'built-in'> = { | |
| 'sourceDescription-name-unique': 'off', | ||
| 'sourceDescription-type': 'off', | ||
| 'sourceDescriptions-not-empty': 'off', | ||
| 'spec-parameters-in-by-context': 'off', | ||
| 'spec-step-mutually-exclusive-fields': 'warn', | ||
| 'step-onFailure-unique': 'off', | ||
| 'step-onSuccess-unique': 'off', | ||
|
|
@@ -290,6 +291,7 @@ const minimal: RawGovernanceConfig<'built-in'> = { | |
| arazzo1_1Rules: { | ||
| 'criteria-unique': 'off', | ||
| 'no-criteria-xpath': 'off', | ||
| 'spec-parameters-in-by-context': 'error', | ||
|
There was a problem hiding this comment. Wrong minimal rule severity for 1.1Medium Severity In the minimal preset, Additional Locations (1)  Reviewed by Cursor Bugbot for commit 3192f86. Configure here. |
||
| 'no-enum-type-mismatch': 'warn', | ||
| 'no-mixed-number-range-constraints': 'off', | ||
| 'no-required-schema-properties-undefined': 'warn', | ||
|
|
||
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems like parameters also won't make sense when action type is
end.What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes I agree, I'll remove it. it is redundant to have it.