fix: pass workflow inputs to success and failure actions

.changeset/swift-otters-wander.md

@@ -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`.

.changeset/thin-aliens-accept.md

@@ -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.

docs/@v2/rules/arazzo/spec-parameters-in-by-context.md

@@ -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)

docs/@v2/rules/built-in-rules.md

@@ -135,6 +135,7 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica
 - [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md): the `replacements` of the `requestBody` object must be unique
 - [sourceDescription-name-unique](./arazzo/sourceDescription-name-unique.md): the `name` property of the `sourceDescription` object must be unique across all source descriptions
 - [sourceDescription-type](./arazzo/sourceDescription-type.md): the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`
+- [spec-parameters-in-by-context](./arazzo/spec-parameters-in-by-context.md): the parameter `in` field must be specified or omitted based on whether the parent step or action references a `workflowId`
 - [stepId-unique](./arazzo/stepId-unique.md): the `stepId` must be unique amongst all steps described in the workflow
 - [step-onFailure-unique](./arazzo/step-onFailure-unique.md): the `onFailure` actions of the `step` object must be unique
 - [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md): the `onSuccess` actions of the `step` object must be unique

docs/@v2/v2.sidebars.yaml

@@ -168,6 +168,7 @@
             - page: rules/arazzo/requestBody-replacements-unique.md
             - page: rules/arazzo/sourceDescription-name-unique.md
             - page: rules/arazzo/sourceDescription-type.md
+            - page: rules/arazzo/spec-parameters-in-by-context.md
             - page: rules/arazzo/stepId-unique.md
             - page: rules/arazzo/step-onFailure-unique.md
             - page: rules/arazzo/step-onSuccess-unique.md

packages/core/src/__tests__/__snapshots__/redocly-yaml.test.ts.snap

@@ -1324,6 +1324,8 @@ exports[`createConfigTypes > matches snapshot for the default config schema 1`]
           "OpenAPISourceDescription",
           "ArazzoSourceDescription",
           "Parameters",
+          "ActionParameters",
+          "ActionParameter",
           "ReusableObject",
           "Workflows",
           "Workflow",

packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap

@@ -20,6 +20,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "sourceDescription-name-unique": "error",
     "sourceDescription-type": "error",
     "sourceDescriptions-not-empty": "error",
+    "spec-parameters-in-by-context": "warn",
     "step-onFailure-unique": "warn",
     "step-onSuccess-unique": "warn",
     "stepId-unique": "error",
@@ -407,6 +408,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "sourceDescription-name-unique": "error",
     "sourceDescription-type": "error",
     "sourceDescriptions-not-empty": "error",
+    "spec-parameters-in-by-context": "warn",
     "step-onFailure-unique": "warn",
     "step-onSuccess-unique": "warn",
     "stepId-unique": "error",

packages/core/src/config/__tests__/load.test.ts

@@ -143,6 +143,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "off",
               "sourceDescription-type": "off",
               "sourceDescriptions-not-empty": "off",
+              "spec-parameters-in-by-context": "off",
               "step-onFailure-unique": "off",
               "step-onSuccess-unique": "off",
               "stepId-unique": "error",
@@ -467,6 +468,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "error",
               "sourceDescription-type": "error",
               "sourceDescriptions-not-empty": "error",
+              "spec-parameters-in-by-context": "warn",
               "step-onFailure-unique": "warn",
               "step-onSuccess-unique": "warn",
               "stepId-unique": "error",
@@ -796,6 +798,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "off",
               "sourceDescription-type": "off",
               "sourceDescriptions-not-empty": "off",
+              "spec-parameters-in-by-context": "off",
               "step-onFailure-unique": "off",
               "step-onSuccess-unique": "off",
               "stepId-unique": "error",
@@ -1209,6 +1212,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "off",
               "sourceDescription-type": "off",
               "sourceDescriptions-not-empty": "off",
+              "spec-parameters-in-by-context": "off",
               "step-onFailure-unique": "off",
               "step-onSuccess-unique": "off",
               "stepId-unique": "error",
@@ -1533,6 +1537,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "error",
               "sourceDescription-type": "error",
               "sourceDescriptions-not-empty": "error",
+              "spec-parameters-in-by-context": "warn",
               "step-onFailure-unique": "warn",
               "step-onSuccess-unique": "warn",
               "stepId-unique": "error",
@@ -1862,6 +1867,7 @@ describe('loadConfig', () => {
               "sourceDescription-name-unique": "off",
               "sourceDescription-type": "off",
               "sourceDescriptions-not-empty": "off",
+              "spec-parameters-in-by-context": "off",
               "step-onFailure-unique": "off",
               "step-onSuccess-unique": "off",
               "stepId-unique": "error",

packages/core/src/config/all.ts

@@ -294,6 +294,7 @@ const all: RawGovernanceConfig<'built-in'> = {
     'sourceDescription-name-unique': 'error',
     'sourceDescription-type': 'error',
     'sourceDescriptions-not-empty': 'error',
+    'spec-parameters-in-by-context': 'error',
     'step-onFailure-unique': 'error',
     'step-onSuccess-unique': 'error',
     'stepId-unique': 'error',

packages/core/src/config/minimal.ts

@@ -273,6 +273,7 @@ const minimal: RawGovernanceConfig<'built-in'> = {
     'sourceDescription-name-unique': 'off',
     'sourceDescription-type': 'off',
     'sourceDescriptions-not-empty': 'off',
+    'spec-parameters-in-by-context': 'off',
     'step-onFailure-unique': 'off',
     'step-onSuccess-unique': 'off',
     'stepId-unique': 'error',

packages/core/src/config/recommended-strict.ts

@@ -273,6 +273,7 @@ const recommendedStrict: RawGovernanceConfig<'built-in'> = {
     'sourceDescription-name-unique': 'error',
     'sourceDescription-type': 'error',
     'sourceDescriptions-not-empty': 'error',
+    'spec-parameters-in-by-context': 'error',
     'step-onFailure-unique': 'error',
     'step-onSuccess-unique': 'error',
     'stepId-unique': 'error',

packages/core/src/config/recommended.ts

@@ -273,6 +273,7 @@ const recommended: RawGovernanceConfig<'built-in'> = {
     'sourceDescription-name-unique': 'error',
     'sourceDescription-type': 'error',
     'sourceDescriptions-not-empty': 'error',
+    'spec-parameters-in-by-context': 'warn',
     'step-onFailure-unique': 'warn',
     'step-onSuccess-unique': 'warn',
     'stepId-unique': 'error',

packages/core/src/config/spec.ts

@@ -273,6 +273,7 @@ const spec: RawGovernanceConfig<'built-in'> = {
     'sourceDescription-name-unique': 'error',
     'sourceDescription-type': 'error',
     'sourceDescriptions-not-empty': 'error',
+    'spec-parameters-in-by-context': 'error',
     'step-onFailure-unique': 'error',
     'step-onSuccess-unique': 'error',
     'stepId-unique': 'error',

packages/core/src/rules/arazzo/__tests__/parameters-unique.test.ts

@@ -112,4 +112,87 @@ describe('Arazzo parameters-unique', () => {
       ]
     `);
   });
+
+  it('should report on duplicated `parameters` defined on success/failure actions', async () => {
+    const actionDocument = parseYamlToDocument(
+      outdent`
+        arazzo: '1.0.1'
+        info:
+          title: Cool API
+          version: 1.0.0
+          description: A cool API
+        sourceDescriptions:
+          - name: museum-api
+            type: openapi
+            url: openapi.yaml
+        workflows:
+          - workflowId: outer
+            steps:
+              - stepId: step-1
+                operationId: museum-api.getMuseumHours
+                onSuccess:
+                  - name: go-next
+                    type: goto
+                    workflowId: inner
+                    parameters:
+                      - name: token
+                        value: a
+                      - name: token
+                        value: b
+                onFailure:
+                  - name: recover
+                    type: goto
+                    workflowId: inner
+                    parameters:
+                      - name: retryToken
+                        value: a
+                      - name: retryToken
+                        value: b
+          - workflowId: inner
+            steps:
+              - stepId: noop
+                operationId: museum-api.getMuseumHours
+      `,
+      'arazzo.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document: actionDocument,
+      config: await createConfig({
+        rules: { 'parameters-unique': 'error' },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/workflows/0/steps/0/onSuccess/0/parameters/1",
+              "reportOnKey": false,
+              "source": "arazzo.yaml",
+            },
+          ],
+          "message": "The parameter \`name\` must be unique amongst listed parameters.",
+          "ruleId": "parameters-unique",
+          "severity": "error",
+          "suggest": [],
+        },
+        {
+          "location": [
+            {
+              "pointer": "#/workflows/0/steps/0/onFailure/0/parameters/1",
+              "reportOnKey": false,
+              "source": "arazzo.yaml",
+            },
+          ],
+          "message": "The parameter \`name\` must be unique amongst listed parameters.",
+          "ruleId": "parameters-unique",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
 });