Skip to content

Commit 2367722

Browse files
vadyvasvadyvas
authored
feat: support x-security schemeName at workflow; add lint rules (#2370)
1 parent 60b3e78 commit 2367722

27 files changed

+666
-159
lines changed

‎.changeset/neat-numbers-knock.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@redocly/respect-core": minor
3+
"@redocly/openapi-core": minor
4+
---
5+
6+
Added support for `schemeName` in `x-security` at the workflow level (Arazzo). Added new lint rules: `arazzo/no-x-security-both-scheme-and-scheme-name` and `arazzo/x-security-scheme-name-link`. Updated core configs to include new rules.

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,10 +142,11 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica
142142
The below rules are being migrated to Respect:
143143

144144
- [no-criteria-xpath](./respect/no-criteria-xpath.md): the `xpath` type criteria is not supported by Respect.
145-
- [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values.
145+
- [no-x-security-both-scheme-and-scheme-name](./respect/no-x-security-both-scheme-and-scheme-name.md): forbids using both `scheme` and `schemeName` in the same `x-security` item
146146
- [no-x-security-scheme-name-without-openapi](./respect/no-x-security-scheme-name-without-openapi.md): the `x-security` can't use `schemeName` when Step request is described with `x-operation`.
147+
- [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values.
148+
- [x-security-scheme-name-reference](./respect/x-security-scheme-name-reference.md): when multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must reference a source description (for example, `$sourceDescriptions.{name}.schemeName`)
147149
- [x-security-scheme-required-values](./respect/x-security-scheme-required-values.md) validate that `x-security` have all required `values` described according to the used `scheme`.
148-
- [no-x-security-scheme-name-in-workflow](./respect/no-x-security-scheme-name-in-workflow.md) the `x-security` can't use `schemeName` when described in Workflow.
149150

150151
## Resources
151152

‎docs/@v2/rules/respect/no-x-security-both-scheme-and-scheme-name.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# no-x-security-both-scheme-and-scheme-name
2+
3+
Forbids using both `scheme` and `schemeName` in the same `x-security` item.
4+
5+
| Arazzo | Compatibility |
6+
| ------ | ------------- |
7+
| 1.x | ✅ |
8+
9+
## Rationale
10+
11+
Each `x-security` entry must reference a security scheme in exactly one way—either embed the `scheme` object or reference it via `schemeName`.
12+
You can include multiple `x-security` entries in a workflow; this rule applies to each entry individually. Using both `scheme` and `schemeName` in the same entry is ambiguous and is rejected by the runtime.
13+
14+
## Configuration
15+
16+
| Option | Type | Description |
17+
| -------- | ------ | ------------------------------------------------------- |
18+
| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
19+
20+
Example:
21+
22+
```yaml
23+
rules:
24+
no-x-security-both-scheme-and-scheme-name: error
25+
```
26+
27+
## Examples
28+
29+
Incorrect — both present:
30+
31+
```yaml
32+
workflows:
33+
- workflowId: get-museum-hours
34+
x-security:
35+
- scheme:
36+
type: http
37+
scheme: bearer
38+
schemeName: BearerAuth
39+
values:
40+
token: some-token
41+
```
42+
43+
Correct — only `scheme`:
44+
45+
```yaml
46+
workflows:
47+
- workflowId: get-museum-hours
48+
x-security:
49+
- scheme:
50+
type: http
51+
scheme: bearer
52+
values:
53+
token: some-token
54+
```
55+
56+
Correct — only `schemeName`:
57+
58+
```yaml
59+
workflows:
60+
- workflowId: get-museum-hours
61+
x-security:
62+
- schemeName: BearerAuth
63+
values:
64+
token: some-token
65+
```
66+
67+
## Related rules
68+
69+
- [x-security-scheme-name-reference](./x-security-scheme-name-reference.md)
70+
- [x-security-scheme-required-values](./x-security-scheme-required-values.md)
71+
72+
## Resources
73+
74+
- Rule source: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/respect/no-x-security-both-scheme-and-scheme-name.ts

‎docs/@v2/rules/respect/no-x-security-scheme-name-in-workflow.md‎

Lines changed: 0 additions & 61 deletions
This file was deleted.

‎docs/@v2/rules/respect/respect-supported-versions.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ arazzo: 1.0.1
4444
- [no-criteria-xpath](./no-criteria-xpath.md)
4545
- [no-x-security-scheme-name-without-openapi](./no-x-security-scheme-name-without-openapi.md)
4646
- [x-security-scheme-required-values](./x-security-scheme-required-values.md)
47-
- [no-x-security-scheme-name-in-workflow](./no-x-security-scheme-name-in-workflow.md)
4847
4948
## Resources
5049

‎docs/@v2/rules/respect/x-security-scheme-name-reference.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# x-security-scheme-name-reference
2+
3+
When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must be a reference to a specific source description (for example, `$sourceDescriptions.{name}.{schemeName}`). If there is only one source description, a plain string is allowed.
4+
5+
| Arazzo | Compatibility |
6+
| ------ | ------------- |
7+
| 1.x | ✅ |
8+
9+
## Design principles
10+
11+
With multiple source descriptions, using a plain `schemeName` is ambiguous. Requiring a reference of the form `$sourceDescriptions.{name}.{schemeName}` disambiguates which source description provides the security scheme.
12+
13+
## Configuration
14+
15+
| Option | Type | Description |
16+
| -------- | ------ | ------------------------------------------------------- |
17+
| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
18+
19+
An example configuration:
20+
21+
```yaml
22+
rules:
23+
x-security-scheme-name-reference: error
24+
```
25+
26+
## Examples
27+
28+
Given the following configuration:
29+
30+
```yaml
31+
rules:
32+
x-security-scheme-name-reference: error
33+
```
34+
35+
Example with multiple source descriptions — incorrect (plain string `schemeName`):
36+
37+
```yaml
38+
sourceDescriptions:
39+
- name: museum-api
40+
type: openapi
41+
url: ./museum.yaml
42+
- name: pets-api
43+
type: openapi
44+
url: ./pets.yaml
45+
46+
workflows:
47+
- workflowId: list-users
48+
x-security:
49+
- schemeName: BasicAuth # <- must be a reference when multiple sources exist
50+
values:
51+
username: test@example.com
52+
password: 123456
53+
```
54+
55+
Example with multiple source descriptions — correct (referenced `schemeName`):
56+
57+
```yaml
58+
sourceDescriptions:
59+
- name: museum-api
60+
type: openapi
61+
url: ./museum.yaml
62+
- name: pets-api
63+
type: openapi
64+
url: ./pets.yaml
65+
66+
workflows:
67+
- workflowId: list-users
68+
x-security:
69+
- schemeName: $sourceDescriptions.museum-api.MuseumPlaceholderAuth
70+
values:
71+
username: test@example.com
72+
password: 123456
73+
```
74+
75+
Example with a single source description — allowed (plain string `schemeName`):
76+
77+
```yaml
78+
sourceDescriptions:
79+
- name: museum-api
80+
type: openapi
81+
url: ./museum.yaml
82+
83+
workflows:
84+
- workflowId: list-users
85+
x-security:
86+
- schemeName: BasicAuth
87+
values:
88+
username: test@example.com
89+
password: 123456
90+
```
91+
92+
## Related rules
93+
94+
- [no-x-security-both-scheme-and-scheme-name](./no-x-security-both-scheme-and-scheme-name.md)
95+
- [x-security-scheme-required-values](./x-security-scheme-required-values.md)
96+
97+
## Resources
98+
99+
- Rule source: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/respect/x-security-scheme-name-reference.ts

‎docs/@v2/sidebars.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,10 @@
149149
- separator: Arazzo
150150
- page: rules/respect/no-criteria-xpath.md
151151
- page: rules/respect/respect-supported-versions.md
152+
- page: rules/respect/no-x-security-both-scheme-and-scheme-name.md
152153
- page: rules/respect/no-x-security-scheme-name-without-openapi.md
154+
- page: rules/respect/x-security-scheme-name-reference.md
153155
- page: rules/respect/x-security-scheme-required-values.md
154-
- page: rules/respect/no-x-security-scheme-name-in-workflow.md
155156
- page: rules/arazzo/criteria-unique.md
156157
- page: rules/arazzo/parameters-unique.md
157158
- page: rules/arazzo/requestBody-replacements-unique.md

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
1010
"no-enum-type-mismatch": "error",
1111
"no-required-schema-properties-undefined": "warn",
1212
"no-schema-type-mismatch": "error",
13-
"no-x-security-scheme-name-in-workflow": "off",
13+
"no-x-security-both-scheme-and-scheme-name": "off",
1414
"no-x-security-scheme-name-without-openapi": "off",
1515
"parameters-unique": "error",
1616
"requestBody-replacements-unique": "warn",
@@ -23,6 +23,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
2323
"stepId-unique": "error",
2424
"workflow-dependsOn": "error",
2525
"workflowId-unique": "error",
26+
"x-security-scheme-name-reference": "off",
2627
"x-security-scheme-required-values": "off",
2728
},
2829
"async2Decorators": {},
@@ -380,7 +381,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
380381
"no-enum-type-mismatch": "error",
381382
"no-required-schema-properties-undefined": "warn",
382383
"no-schema-type-mismatch": "error",
383-
"no-x-security-scheme-name-in-workflow": "off",
384+
"no-x-security-both-scheme-and-scheme-name": "off",
384385
"no-x-security-scheme-name-without-openapi": "off",
385386
"parameters-unique": "error",
386387
"requestBody-replacements-unique": "warn",
@@ -393,6 +394,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
393394
"stepId-unique": "error",
394395
"workflow-dependsOn": "error",
395396
"workflowId-unique": "error",
397+
"x-security-scheme-name-reference": "off",
396398
"x-security-scheme-required-values": "off",
397399
},
398400
"async2Decorators": {},

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ describe('loadConfig', () => {
131131
"no-enum-type-mismatch": "warn",
132132
"no-required-schema-properties-undefined": "warn",
133133
"no-schema-type-mismatch": "warn",
134-
"no-x-security-scheme-name-in-workflow": "off",
134+
"no-x-security-both-scheme-and-scheme-name": "off",
135135
"no-x-security-scheme-name-without-openapi": "off",
136136
"parameters-unique": "off",
137137
"requestBody-replacements-unique": "off",
@@ -144,6 +144,7 @@ describe('loadConfig', () => {
144144
"stepId-unique": "error",
145145
"workflow-dependsOn": "off",
146146
"workflowId-unique": "error",
147+
"x-security-scheme-name-reference": "off",
147148
"x-security-scheme-required-values": "off",
148149
},
149150
"async2Decorators": {},
@@ -438,7 +439,7 @@ describe('loadConfig', () => {
438439
"no-enum-type-mismatch": "error",
439440
"no-required-schema-properties-undefined": "warn",
440441
"no-schema-type-mismatch": "error",
441-
"no-x-security-scheme-name-in-workflow": "off",
442+
"no-x-security-both-scheme-and-scheme-name": "off",
442443
"no-x-security-scheme-name-without-openapi": "off",
443444
"parameters-unique": "error",
444445
"requestBody-replacements-unique": "warn",
@@ -451,6 +452,7 @@ describe('loadConfig', () => {
451452
"stepId-unique": "error",
452453
"workflow-dependsOn": "error",
453454
"workflowId-unique": "error",
455+
"x-security-scheme-name-reference": "off",
454456
"x-security-scheme-required-values": "off",
455457
},
456458
"async2Decorators": {},
@@ -750,7 +752,7 @@ describe('loadConfig', () => {
750752
"no-enum-type-mismatch": "warn",
751753
"no-required-schema-properties-undefined": "warn",
752754
"no-schema-type-mismatch": "warn",
753-
"no-x-security-scheme-name-in-workflow": "off",
755+
"no-x-security-both-scheme-and-scheme-name": "off",
754756
"no-x-security-scheme-name-without-openapi": "off",
755757
"parameters-unique": "off",
756758
"requestBody-replacements-unique": "off",
@@ -763,6 +765,7 @@ describe('loadConfig', () => {
763765
"stepId-unique": "error",
764766
"workflow-dependsOn": "off",
765767
"workflowId-unique": "error",
768+
"x-security-scheme-name-reference": "off",
766769
"x-security-scheme-required-values": "off",
767770
},
768771
"async2Decorators": {},

‎packages/core/src/config/all.ts‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -276,23 +276,24 @@ const all: RawGovernanceConfig<'built-in'> = {
276276
arazzo1Rules: {
277277
'criteria-unique': 'error',
278278
'no-criteria-xpath': 'off',
279+
'no-enum-type-mismatch': 'error',
280+
'no-required-schema-properties-undefined': 'error',
281+
'no-schema-type-mismatch': 'error',
282+
'no-x-security-both-scheme-and-scheme-name': 'off',
283+
'no-x-security-scheme-name-without-openapi': 'off',
279284
'parameters-unique': 'error',
280285
'requestBody-replacements-unique': 'error',
286+
'respect-supported-versions': 'off',
287+
'sourceDescription-name-unique': 'error',
281288
'sourceDescription-type': 'error',
282-
'step-onSuccess-unique': 'error',
289+
'sourceDescriptions-not-empty': 'error',
283290
'step-onFailure-unique': 'error',
291+
'step-onSuccess-unique': 'error',
284292
'stepId-unique': 'error',
285-
'sourceDescription-name-unique': 'error',
286-
'sourceDescriptions-not-empty': 'error',
287-
'respect-supported-versions': 'off',
288-
'workflowId-unique': 'error',
289293
'workflow-dependsOn': 'error',
290-
'no-x-security-scheme-name-without-openapi': 'off',
294+
'workflowId-unique': 'error',
295+
'x-security-scheme-name-reference': 'off',
291296
'x-security-scheme-required-values': 'off',
292-
'no-x-security-scheme-name-in-workflow': 'off',
293-
'no-required-schema-properties-undefined': 'error',
294-
'no-enum-type-mismatch': 'error',
295-
'no-schema-type-mismatch': 'error',
296297
},
297298
overlay1Rules: {
298299
'info-contact': 'error',

0 commit comments

Comments
 (0)