fix: rename x-security-scheme-name-link to x-security-scheme-name-reference and update related documentation and tests

Author: vadyvas

__tests__/lint/x-security-scheme-name-link-rule/redocly.yaml

@@ -2,4 +2,4 @@ apis:
   main:
     root: ./museum.yaml
 rules:
-  x-security-scheme-name-link: error
+  x-security-scheme-name-reference: error

__tests__/lint/x-security-scheme-name-link-rule/snapshot.txt

@@ -1,6 +1,6 @@
 [1] museum.yaml:15:21 at #/workflows/0/x-security/0/schemeName
 
-When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must be a link to a source description (e.g. `$sourceDescriptions.{name}.{scheme}`)
+When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must be a reference to a source description (e.g. `$sourceDescriptions.{name}.{scheme}`)
 
 13 | - workflowId: get-museum-hours
 14 |   x-security:
@@ -9,7 +9,7 @@ When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must
 16 |       values:
 17 |         token: some-token
 
-Error was generated by the x-security-scheme-name-link rule.
+Error was generated by the x-security-scheme-name-reference rule.
 
 
 

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

@@ -136,8 +136,6 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica
 - [workflow-dependsOn](./arazzo/workflow-dependsOn.md): the items in the `workflow` `dependsOn` property must exist and be unique
 - [workflowId-unique](./arazzo/workflowId-unique.md): the `workflowId` property must be unique across all workflows
 - [sourceDescriptions-not-empty](./arazzo/sourceDescriptions-not-empty.md): the `sourceDescriptions` must be defined and the list must have at least one entry.
-- [x-security-scheme-name-link](./arazzo/x-security-scheme-name-link.md): when multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must link to a source description (for example, `$sourceDescriptions.{name}.scheme`)
-- [no-x-security-both-scheme-and-scheme-name](./arazzo/no-x-security-both-scheme-and-scheme-name.md): forbids using both `scheme` and `schemeName` in the same `x-security` item
 
 ### Respect
 
@@ -147,6 +145,8 @@ The below rules are being migrated to Respect:
 - [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values.
 - [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`.
 - [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`.
+- [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}.scheme`)
+- [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
 
 ## Resources
 

…-security-both-scheme-and-scheme-name.md …-security-both-scheme-and-scheme-name.mddocs/@v2/rules/arazzo/no-x-security-both-scheme-and-scheme-name.md renamed to docs/@v2/rules/respect/no-x-security-both-scheme-and-scheme-name.md docs/@v2/rules/arazzo/no-x-security-both-scheme-and-scheme-name.md renamed to docs/@v2/rules/respect/no-x-security-both-scheme-and-scheme-name.md

@@ -8,8 +8,8 @@ Forbids using both `scheme` and `schemeName` in the same `x-security` item.
 
 ## Rationale
 
-A single `x-security` item must reference a security scheme in exactly one way: either by embedding the `scheme` object or by referencing it with `schemeName`.
-Having both is ambiguous and is rejected by the runtime.
+Each `x-security` entry must reference a security scheme in exactly one way—either embed the `scheme` object or reference it via `schemeName`.
+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.
 
 ## Configuration
 
@@ -66,9 +66,9 @@ workflows:
 
 ## Related rules
 
-- [x-security-scheme-name-link](./x-security-scheme-name-link.md)
-- [x-security-scheme-required-values](../respect/x-security-scheme-required-values.md)
+- [x-security-scheme-name-reference](./x-security-scheme-name-reference.md)
+- [x-security-scheme-required-values](./x-security-scheme-required-values.md)
 
 ## Resources
 
-- Rule source: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/no-x-security-both-scheme-and-scheme-name.ts
+- Rule source: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/respect/no-x-security-both-scheme-and-scheme-name.ts

…es/arazzo/x-security-scheme-name-link.md …pect/x-security-scheme-name-reference.mddocs/@v2/rules/arazzo/x-security-scheme-name-link.md renamed to docs/@v2/rules/respect/x-security-scheme-name-reference.md docs/@v2/rules/arazzo/x-security-scheme-name-link.md renamed to docs/@v2/rules/respect/x-security-scheme-name-reference.md

@@ -1,16 +1,14 @@
-# x-security-scheme-name-link
+# x-security-scheme-name-reference
 
-When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must be a link to a specific source description (for example, `$sourceDescriptions.{name}.scheme`).
-If there is only one source description, a plain string is allowed.
+When multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must be a reference to a specific source description (for example, `$sourceDescriptions.{name}.scheme`). If there is only one source description, a plain string is allowed.
 
 | Arazzo | Compatibility |
 | ------ | ------------- |
 | 1.x    | ✅            |
 
 ## Design principles
 
-With multiple source descriptions, using a plain `schemeName` is ambiguous.
-Requiring a link of the form `$sourceDescriptions.{name}.scheme` disambiguates which source description provides the security scheme.
+With multiple source descriptions, using a plain `schemeName` is ambiguous. Requiring a reference of the form `$sourceDescriptions.{name}.scheme` disambiguates which source description provides the security scheme.
 
 ## Configuration
 
@@ -22,7 +20,7 @@ An example configuration:
 
 ```yaml
 rules:
-  x-security-scheme-name-link: error
+  x-security-scheme-name-reference: error
 ```
 
 ## Examples
@@ -31,7 +29,7 @@ Given the following configuration:
 
 ```yaml
 rules:
-  x-security-scheme-name-link: error
+  x-security-scheme-name-reference: error
 ```
 
 Example with multiple source descriptions — incorrect (plain string `schemeName`):
@@ -48,13 +46,13 @@ sourceDescriptions:
 workflows:
   - workflowId: list-users
     x-security:
-      - schemeName: BasicAuth   # <- must be a link when multiple sources exist
+      - schemeName: BasicAuth   # <- must be a reference when multiple sources exist
         values:
           username: test@example.com
           password: 123456
 ```
 
-Example with multiple source descriptions — correct (linked `schemeName`):
+Example with multiple source descriptions — correct (referenced `schemeName`):
 
 ```yaml
 sourceDescriptions:
@@ -93,10 +91,9 @@ workflows:
 
 ## Related rules
 
-- [sourceDescriptions-not-empty](./sourceDescriptions-not-empty.md)
-- [sourceDescriptions-name-unique](./sourceDescriptions-name-unique.md)
-- [sourceDescriptions-type](./sourceDescriptions-type.md)
+- [no-x-security-both-scheme-and-scheme-name](./no-x-security-both-scheme-and-scheme-name.md)
+- [x-security-scheme-required-values](./x-security-scheme-required-values.md)
 
 ## Resources
 
-- Rule source: https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/x-security-scheme-name-link.ts
+- 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

@@ -151,13 +151,13 @@
             - page: rules/respect/respect-supported-versions.md
             - page: rules/respect/no-x-security-scheme-name-without-openapi.md
             - page: rules/respect/x-security-scheme-required-values.md
+            - page: rules/respect/x-security-scheme-name-reference.md
+            - page: rules/respect/no-x-security-both-scheme-and-scheme-name.md
             - page: rules/arazzo/criteria-unique.md
             - page: rules/arazzo/parameters-unique.md
             - page: rules/arazzo/requestBody-replacements-unique.md
             - page: rules/arazzo/sourceDescriptions-name-unique.md
             - page: rules/arazzo/sourceDescriptions-type.md
-            - page: rules/arazzo/x-security-scheme-name-link.md
-            - page: rules/arazzo/no-x-security-both-scheme-and-scheme-name.md
             - page: rules/arazzo/stepId-unique.md
             - page: rules/arazzo/step-onFailure-unique.md
             - page: rules/arazzo/step-onSuccess-unique.md

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

@@ -10,7 +10,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "no-enum-type-mismatch": "error",
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
-    "no-x-security-both-scheme-and-scheme-name": "error",
+    "no-x-security-both-scheme-and-scheme-name": "off",
     "no-x-security-scheme-name-without-openapi": "off",
     "parameters-unique": "error",
     "requestBody-replacements-unique": "warn",
@@ -23,7 +23,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "stepId-unique": "error",
     "workflow-dependsOn": "error",
     "workflowId-unique": "error",
-    "x-security-scheme-name-link": "error",
+    "x-security-scheme-name-reference": "off",
     "x-security-scheme-required-values": "off",
   },
   "async2Decorators": {},
@@ -381,7 +381,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "no-enum-type-mismatch": "error",
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
-    "no-x-security-both-scheme-and-scheme-name": "error",
+    "no-x-security-both-scheme-and-scheme-name": "off",
     "no-x-security-scheme-name-without-openapi": "off",
     "parameters-unique": "error",
     "requestBody-replacements-unique": "warn",
@@ -394,7 +394,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "stepId-unique": "error",
     "workflow-dependsOn": "error",
     "workflowId-unique": "error",
-    "x-security-scheme-name-link": "error",
+    "x-security-scheme-name-reference": "off",
     "x-security-scheme-required-values": "off",
   },
   "async2Decorators": {},

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

@@ -144,7 +144,7 @@ describe('loadConfig', () => {
               "stepId-unique": "error",
               "workflow-dependsOn": "off",
               "workflowId-unique": "error",
-              "x-security-scheme-name-link": "off",
+              "x-security-scheme-name-reference": "off",
               "x-security-scheme-required-values": "off",
             },
             "async2Decorators": {},
@@ -439,7 +439,7 @@ describe('loadConfig', () => {
               "no-enum-type-mismatch": "error",
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "error",
-              "no-x-security-both-scheme-and-scheme-name": "error",
+              "no-x-security-both-scheme-and-scheme-name": "off",
               "no-x-security-scheme-name-without-openapi": "off",
               "parameters-unique": "error",
               "requestBody-replacements-unique": "warn",
@@ -452,7 +452,7 @@ describe('loadConfig', () => {
               "stepId-unique": "error",
               "workflow-dependsOn": "error",
               "workflowId-unique": "error",
-              "x-security-scheme-name-link": "error",
+              "x-security-scheme-name-reference": "off",
               "x-security-scheme-required-values": "off",
             },
             "async2Decorators": {},
@@ -765,7 +765,7 @@ describe('loadConfig', () => {
               "stepId-unique": "error",
               "workflow-dependsOn": "off",
               "workflowId-unique": "error",
-              "x-security-scheme-name-link": "off",
+              "x-security-scheme-name-reference": "off",
               "x-security-scheme-required-values": "off",
             },
             "async2Decorators": {},

packages/core/src/config/all.ts

@@ -292,8 +292,8 @@ const all: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'error',
     'no-enum-type-mismatch': 'error',
     'no-schema-type-mismatch': 'error',
-    'x-security-scheme-name-link': 'error',
-    'no-x-security-both-scheme-and-scheme-name': 'error',
+    'x-security-scheme-name-reference': 'off',
+    'no-x-security-both-scheme-and-scheme-name': 'off',
   },
   overlay1Rules: {
     'info-contact': 'error',

packages/core/src/rules/arazzo/index.ts

@@ -15,12 +15,12 @@ import { NoCriteriaXpath } from '../respect/no-criteria-xpath.js';
 import { CriteriaUnique } from './criteria-unique.js';
 import { NoXSecuritySchemeNameWithoutOpenAPI } from '../respect/no-x-security-scheme-name-without-openapi.js';
 import { XSecuritySchemaRequiredValues } from '../respect/x-security-scheme-required-values.js';
-import { XSecuritySchemeNameLink } from './x-security-scheme-name-link.js';
-import { NoXSecurityBothSchemeAndSchemeName } from './no-x-security-both-scheme-and-scheme-name.js';
 import { NoUnresolvedRefs } from '../common/no-unresolved-refs.js';
 import { NoRequiredSchemaPropertiesUndefined } from '../common/no-required-schema-properties-undefined.js';
 import { NoEnumTypeMismatch } from '../common/no-enum-type-mismatch.js';
 import { NoSchemaTypeMismatch } from '../common/no-schema-type-mismatch.js';
+import { NoXSecurityBothSchemeAndSchemeName } from '../respect/no-x-security-both-scheme-and-scheme-name.js';
+import { XSecuritySchemeNameReference } from '../respect/x-security-scheme-name-reference.js';
 
 import type { Arazzo1Rule } from '../../visitors.js';
 import type { Arazzo1RuleSet } from '../../oas-types.js';
@@ -44,7 +44,7 @@ export const rules: Arazzo1RuleSet<'built-in'> = {
   'criteria-unique': CriteriaUnique,
   'no-x-security-scheme-name-without-openapi': NoXSecuritySchemeNameWithoutOpenAPI,
   'x-security-scheme-required-values': XSecuritySchemaRequiredValues,
-  'x-security-scheme-name-link': XSecuritySchemeNameLink,
+  'x-security-scheme-name-reference': XSecuritySchemeNameReference,
   'no-x-security-both-scheme-and-scheme-name': NoXSecurityBothSchemeAndSchemeName,
   'no-required-schema-properties-undefined': NoRequiredSchemaPropertiesUndefined as Arazzo1Rule,
   'no-enum-type-mismatch': NoEnumTypeMismatch as Arazzo1Rule,