feat: add nullable-type-sibling rule instead of validating the nullable field in the struct rule (#2146)

tatomyr · web-flow · commit 4c9c055f18d9 · 2025-07-09T11:17:13.000+02:00
diff --git a/.changeset/fuzzy-ducks-exist.md b/.changeset/fuzzy-ducks-exist.md
@@ -0,0 +1,6 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Extracted `nullable` validation from the `struct` rule into a new `nullable-type-sibling` rule for OpenAPI 3.0. This allows users to disable `nullable` validation separately from other structural checks.
diff --git a/__tests__/lint/no-invalid-media-type-examples-invalid-schema/snapshot.txt b/__tests__/lint/no-invalid-media-type-examples-invalid-schema/snapshot.txt
@@ -9,7 +9,7 @@ The `type` field must be defined when the `nullable` field is used.
 17 | paths:
 18 |   /test:
 
-Error was generated by the struct rule.
+Error was generated by the nullable-type-sibling rule.
 
 
 [2] openapi.yaml:28:17 at #/paths/~1test/get/responses/202/content/application~1json/schema
diff --git a/docs/@v2/rules/minimal.md b/docs/@v2/rules/minimal.md
@@ -28,6 +28,7 @@ Warnings:
 - [no-server-example.com](./oas/no-server-example-com.md)
 - [no-undefined-server-variable](./oas/no-undefined-server-variable.md)
 - [no-unused-components](./oas/no-unused-components.md)
+- [nullable-type-sibling](./oas/nullable-type-sibling.md)
 - [operation-2xx-response](./oas/operation-2xx-response.md)
 - [operation-operationId-unique](./oas/operation-operationId-unique.md)
 - [operation-operationId-url-safe](./oas/operation-operationId-url-safe.md)
diff --git a/docs/@v2/rules/oas/nullable-type-sibling.md b/docs/@v2/rules/oas/nullable-type-sibling.md
@@ -0,0 +1,84 @@
+---
+slug: /docs/cli/v2/rules/oas/nullable-type-sibling
+---
+
+# nullable-type-sibling
+
+Ensures that all schemas with `nullable` field have a `type` field explicitly set.
+
+| OAS | Compatibility |
+| --- | ------------- |
+| 3.0 | ✅            |
+
+## API design principles
+
+The `nullable` field is not allowed without the `type` field explicitly set.
+
+## Configuration
+
+| Option   | Type   | Description                                                                                |
+| -------- | ------ | ------------------------------------------------------------------------------------------ |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
+
+An example configuration:
+
+```yaml
+rules:
+  nullable-type-sibling: error
+```
+
+## Examples
+
+Given this configuration:
+
+```yaml
+rules:
+  nullable-type-sibling: error
+```
+
+Example of an **incorrect** usage of `nullable` field:
+
+```yaml
+components:
+  schemas:
+    Incorrect:
+      nullable: true
+    ReferencingATypeButStillIncorrect:
+      nullable: true
+      allOf:
+        - $ref: '#/components/schemas/SomeType'
+    SomeType:
+      type: string
+
+```
+
+Example of a **correct** usage:
+
+```yaml
+components:
+  schemas:
+    Correct:
+      type: string
+      nullable: true
+    CorrectWithAllOf:
+      type: object
+      nullable: true
+      allOf:
+        - type: object
+          properties:
+            name:
+              type: string
+        - type: object
+          properties:
+            age:
+              type: number
+```
+
+## Related rules
+
+- [struct](./struct.md)
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/oas3/nullable-type-sibling.ts)
+- [Examples](https://redocly.com/learn/openapi/openapi-visual-reference/null)
diff --git a/docs/@v2/rules/recommended.md b/docs/@v2/rules/recommended.md
@@ -17,6 +17,7 @@ Errors:
 - [no-server-variables-empty-enum](./oas/no-server-variables-empty-enum.md)
 - [no-undefined-server-variable](./oas/no-undefined-server-variable.md)
 - [no-unresolved-refs](./oas/no-unresolved-refs.md)
+- [nullable-type-sibling](./oas/nullable-type-sibling.md)
 - [operation-operationId-unique](./oas/operation-operationId-unique.md)
 - [operation-operationId-url-safe](./oas/operation-operationId-url-safe.md)
 - [operation-parameters-unique](./oas/operation-parameters-unique.md)
diff --git a/docs/@v2/rules/ruleset-templates.md b/docs/@v2/rules/ruleset-templates.md
@@ -107,6 +107,7 @@ rules:
   operation-singular-tag: off
   no-unresolved-refs: error
   no-enum-type-mismatch: warn
+  nullable-type-sibling: warn
   paths-kebab-case: off
   struct: error
   spec-strict-refs: off
@@ -384,6 +385,7 @@ rules:
   operation-singular-tag: off
   no-unresolved-refs: error
   no-enum-type-mismatch: error
+  nullable-type-sibling: error
   paths-kebab-case: off
   struct: error
   spec-strict-refs: off
diff --git a/packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap b/packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap
@@ -128,6 +128,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "no-undefined-server-variable": "error",
     "no-unresolved-refs": "error",
     "no-unused-components": "warn",
+    "nullable-type-sibling": "error",
     "operation-2xx-response": "off",
     "operation-4xx-problem-details-rfc7807": "off",
     "operation-4xx-response": "error",
@@ -433,6 +434,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "no-undefined-server-variable": "error",
     "no-unresolved-refs": "error",
     "no-unused-components": "warn",
+    "nullable-type-sibling": "error",
     "operation-2xx-response": "error",
     "operation-4xx-problem-details-rfc7807": "off",
     "operation-4xx-response": "off",
diff --git a/packages/core/src/config/__tests__/load.test.ts b/packages/core/src/config/__tests__/load.test.ts
@@ -267,6 +267,7 @@ describe('loadConfig', () => {
               "no-undefined-server-variable": "warn",
               "no-unresolved-refs": "error",
               "no-unused-components": "warn",
+              "nullable-type-sibling": "warn",
               "operation-2xx-response": "warn",
               "operation-4xx-problem-details-rfc7807": "off",
               "operation-4xx-response": "off",
@@ -503,6 +504,7 @@ describe('loadConfig', () => {
               "no-undefined-server-variable": "error",
               "no-unresolved-refs": "error",
               "no-unused-components": "warn",
+              "nullable-type-sibling": "error",
               "operation-2xx-response": "warn",
               "operation-4xx-problem-details-rfc7807": "off",
               "operation-4xx-response": "warn",
@@ -750,6 +752,7 @@ describe('loadConfig', () => {
               "no-undefined-server-variable": "warn",
               "no-unresolved-refs": "error",
               "no-unused-components": "warn",
+              "nullable-type-sibling": "warn",
               "operation-2xx-response": "warn",
               "operation-4xx-problem-details-rfc7807": "off",
               "operation-4xx-response": "off",
diff --git a/packages/core/src/config/all.ts b/packages/core/src/config/all.ts
@@ -86,6 +86,7 @@ const all: RawGovernanceConfig<'built-in'> = {
     'no-unused-components': 'error',
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
+    'nullable-type-sibling': 'error',
     'operation-summary': 'error',
     'operation-operationId': 'error',
     'operation-operationId-unique': 'error',
diff --git a/packages/core/src/config/minimal.ts b/packages/core/src/config/minimal.ts
@@ -80,6 +80,7 @@ const minimal: RawGovernanceConfig<'built-in'> = {
     'no-unused-components': 'warn',
     'no-undefined-server-variable': 'warn',
     'no-server-variables-empty-enum': 'error',
+    'nullable-type-sibling': 'warn',
     'operation-summary': 'warn',
     'operation-operationId': 'warn',
     'operation-operationId-unique': 'warn',
diff --git a/packages/core/src/config/recommended-strict.ts b/packages/core/src/config/recommended-strict.ts
@@ -80,6 +80,7 @@ const recommendedStrict: RawGovernanceConfig<'built-in'> = {
     'no-unused-components': 'error',
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
+    'nullable-type-sibling': 'error',
     'operation-summary': 'error',
     'operation-operationId': 'error',
     'operation-operationId-unique': 'error',
diff --git a/packages/core/src/config/recommended.ts b/packages/core/src/config/recommended.ts
@@ -91,6 +91,7 @@ const recommended: RawGovernanceConfig<'built-in'> = {
     'operation-parameters-unique': 'error',
     'operation-tag-defined': 'off',
     'operation-singular-tag': 'off',
+    'nullable-type-sibling': 'error',
     'parameter-description': 'off',
     'path-declaration-must-exist': 'error',
     'path-not-include-query': 'error',
diff --git a/packages/core/src/rules/common/__tests__/struct.test.ts b/packages/core/src/rules/common/__tests__/struct.test.ts
@@ -158,39 +158,11 @@ describe('Oas3 struct', () => {
     const results = await lintDocument({
       externalRefResolver: new BaseResolver(),
       document,
-      config: await createConfig({ rules: { struct: 'error' } }),
+      config: await createConfig({ rules: { 'nullable-type-sibling': 'error' } }),
     });
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
       [
-        {
-          "from": undefined,
-          "location": [
-            {
-              "pointer": "#/",
-              "reportOnKey": true,
-              "source": "foobar.yaml",
-            },
-          ],
-          "message": "The field \`paths\` must be present on this level.",
-          "ruleId": "struct",
-          "severity": "error",
-          "suggest": [],
-        },
-        {
-          "from": undefined,
-          "location": [
-            {
-              "pointer": "#/",
-              "reportOnKey": true,
-              "source": "foobar.yaml",
-            },
-          ],
-          "message": "The field \`info\` must be present on this level.",
-          "ruleId": "struct",
-          "severity": "error",
-          "suggest": [],
-        },
         {
           "location": [
             {
@@ -200,7 +172,7 @@ describe('Oas3 struct', () => {
             },
           ],
           "message": "The \`type\` field must be defined when the \`nullable\` field is used.",
-          "ruleId": "struct",
+          "ruleId": "nullable-type-sibling",
           "severity": "error",
           "suggest": [],
         },
@@ -232,39 +204,11 @@ describe('Oas3 struct', () => {
     const results = await lintDocument({
       externalRefResolver: new BaseResolver(),
       document,
-      config: await createConfig({ rules: { struct: 'error' } }),
+      config: await createConfig({ rules: { 'nullable-type-sibling': 'error' } }),
     });
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
       [
-        {
-          "from": undefined,
-          "location": [
-            {
-              "pointer": "#/",
-              "reportOnKey": true,
-              "source": "foobar.yaml",
-            },
-          ],
-          "message": "The field \`paths\` must be present on this level.",
-          "ruleId": "struct",
-          "severity": "error",
-          "suggest": [],
-        },
-        {
-          "from": undefined,
-          "location": [
-            {
-              "pointer": "#/",
-              "reportOnKey": true,
-              "source": "foobar.yaml",
-            },
-          ],
-          "message": "The field \`info\` must be present on this level.",
-          "ruleId": "struct",
-          "severity": "error",
-          "suggest": [],
-        },
         {
           "location": [
             {
@@ -274,20 +218,72 @@ describe('Oas3 struct', () => {
             },
           ],
           "message": "The \`type\` field must be defined when the \`nullable\` field is used.",
-          "ruleId": "struct",
+          "ruleId": "nullable-type-sibling",
           "severity": "error",
           "suggest": [],
         },
+      ]
+    `);
+  });
+
+  it('should not report on nullable with type defined', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+      openapi: 3.0.0
+      components:
+        requestBodies:
+          TestRequestBody:
+            content:
+              application/json:
+                schema:
+                  nullable: true
+                  type: object
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({ rules: { 'nullable-type-sibling': 'error' } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should not report on nullable without type with the struct rule', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        components:
+          requestBodies:
+            TestRequestBody:
+              content:
+                application/json:
+                  schema:
+                    nullable: true
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({ rules: { struct: 'error' } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
         {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/components/requestBodies/schemas",
+              "pointer": "#/",
               "reportOnKey": true,
               "source": "foobar.yaml",
             },
           ],
-          "message": "The field \`content\` must be present on this level.",
+          "message": "The field \`paths\` must be present on this level.",
           "ruleId": "struct",
           "severity": "error",
           "suggest": [],
@@ -296,12 +292,12 @@ describe('Oas3 struct', () => {
           "from": undefined,
           "location": [
             {
-              "pointer": "#/components/requestBodies/schemas/TestSchema",
+              "pointer": "#/",
               "reportOnKey": true,
               "source": "foobar.yaml",
             },
           ],
-          "message": "Property \`TestSchema\` is not expected here.",
+          "message": "The field \`info\` must be present on this level.",
           "ruleId": "struct",
           "severity": "error",
           "suggest": [],
diff --git a/packages/core/src/rules/common/struct.ts b/packages/core/src/rules/common/struct.ts
diff --git a/packages/core/src/rules/oas3/index.ts b/packages/core/src/rules/oas3/index.ts
diff --git a/packages/core/src/rules/oas3/nullable-type-sibling.ts b/packages/core/src/rules/oas3/nullable-type-sibling.ts
diff --git a/packages/core/src/types/redocly-yaml.ts b/packages/core/src/types/redocly-yaml.ts
