chore: add linting for dataValue in example

.changeset/public-ravens-taste.md

@@ -0,0 +1,5 @@
+---
+'@redocly/openapi-core': minor
+---
+
+Added linting for the OpenAPI 3.2 Example Object `dataValue` field.

docs/@v2/rules/oas/no-invalid-media-type-examples.md

@@ -146,6 +146,57 @@ post:
               color: red
 ```
 
+### OpenAPI 3.2 `dataValue`
+
+In OpenAPI 3.2, provide the structured example in `dataValue`, which is validated against the schema the same way `value` is.
+When `dataValue` is present, `value` must be absent (see [spec-example-values](./spec-example-values.md)).
+
+Example of an **incorrect** `dataValue`:
+
+```yaml
+post:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            make:
+              type: string
+            year:
+              type: integer
+        examples:
+          tesla:
+            summary: Red Tesla
+            dataValue:
+              make: Tesla
+              year: '2022'
+```
+
+> This example produces an error because the year is a string instead of an integer.
+
+Example of a **correct** `dataValue`:
+
+```yaml
+post:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            make:
+              type: string
+            year:
+              type: integer
+        examples:
+          tesla:
+            summary: Red Tesla
+            dataValue:
+              make: Tesla
+              year: 2022
+```
+
 ## Related rules
 
 - [no-invalid-parameter-examples](./no-invalid-parameter-examples.md)

docs/@v2/rules/oas/no-invalid-parameter-examples.md

@@ -100,6 +100,49 @@ paths:
           example: ella
 ```
 
+### OpenAPI 3.2 `dataValue`
+
+In OpenAPI 3.2, provide the structured example in `dataValue`, which is validated against the schema the same way `value` is.
+When `dataValue` is present, `value` must be absent (see [spec-example-values](./spec-example-values.md)).
+
+Example of an **incorrect** `dataValue`:
+
+```yaml
+paths:
+  /results:
+    get:
+      summary: Search Chess Results
+      operationId: searchChessResult
+      parameters:
+        - name: rating
+          in: query
+          schema:
+            type: integer
+          examples:
+            grandmaster:
+              dataValue: '2500'
+```
+
+> This example produces an error because the rating is a string instead of an integer.
+
+Example of a **correct** `dataValue`:
+
+```yaml
+paths:
+  /results:
+    get:
+      summary: Search Chess Results
+      operationId: searchChessResult
+      parameters:
+        - name: rating
+          in: query
+          schema:
+            type: integer
+          examples:
+            grandmaster:
+              dataValue: 2500
+```
+
 ## Related rules
 
 - [no-invalid-media-type-examples](./no-invalid-media-type-examples.md)

packages/core/src/rules/common/__tests__/no-invalid-parameter-examples.test.ts

@@ -100,7 +100,7 @@ describe('no-invalid-parameter-examples', () => {
           },
           "location": [
             {
-              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/extraProperty",
+              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/value/extraProperty",
               "reportOnKey": true,
               "source": "foobar.yaml",
             },
@@ -194,7 +194,7 @@ describe('no-invalid-parameter-examples', () => {
           },
           "location": [
             {
-              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/readOnlyProp",
+              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/value/readOnlyProp",
               "reportOnKey": false,
               "source": "foobar.yaml",
             },
@@ -208,4 +208,156 @@ describe('no-invalid-parameter-examples', () => {
       ]
     `);
   });
+
+  it('should report invalid dataValue in parameter examples (OAS 3.2)', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.2.0
+        paths:
+          /users:
+            get:
+              parameters:
+                - name: filter
+                  in: query
+                  schema:
+                    type: object
+                    properties:
+                      name:
+                        type: string
+                  examples:
+                    invalid:
+                      dataValue:
+                        name: 42
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({ rules: { 'no-invalid-parameter-examples': 'error' } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/paths/~1users/get/parameters/0",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/dataValue/name",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: \`name\` property type must be string.",
+          "reference": "https://redocly.com/docs/cli/rules/oas/no-invalid-parameter-examples",
+          "ruleId": "no-invalid-parameter-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should validate boolean query parameter dataValue and ignore serializedValue (OAS 3.2)', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.2.0
+        paths:
+          /search:
+            get:
+              parameters:
+                - name: exact
+                  in: query
+                  schema:
+                    type: boolean
+                  examples:
+                    invalid:
+                      dataValue: "true"
+                      serializedValue: "true"
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({ rules: { 'no-invalid-parameter-examples': 'error' } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/paths/~1search/get/parameters/0",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/paths/~1search/get/parameters/0/examples/invalid/dataValue",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: type must be boolean.",
+          "reference": "https://redocly.com/docs/cli/rules/oas/no-invalid-parameter-examples",
+          "ruleId": "no-invalid-parameter-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should still validate legacy value in OAS 3.2 examples (backward compatibility)', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.2.0
+        paths:
+          /users:
+            get:
+              parameters:
+                - name: age
+                  in: query
+                  schema:
+                    type: integer
+                  examples:
+                    invalid:
+                      value: "not-a-number"
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({ rules: { 'no-invalid-parameter-examples': 'error' } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": {
+            "pointer": "#/paths/~1users/get/parameters/0",
+            "source": "foobar.yaml",
+          },
+          "location": [
+            {
+              "pointer": "#/paths/~1users/get/parameters/0/examples/invalid/value",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Example value must conform to the schema: type must be integer.",
+          "reference": "https://redocly.com/docs/cli/rules/oas/no-invalid-parameter-examples",
+          "ruleId": "no-invalid-parameter-examples",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
 });

packages/core/src/rules/common/no-invalid-parameter-examples.ts

@@ -4,7 +4,7 @@ import { isPlainObject } from '../../utils/is-plain-object.js';
 import type { Oas2Rule, Oas3Rule } from '../../visitors.js';
 import type { UserContext } from '../../walk.js';
 import { AjvValidator } from '../ajv.js';
-import { validateExample } from '../utils.js';
+import { getExampleValueToValidate, validateExample } from '../utils.js';
 
 export const NoInvalidParameterExamples: Oas3Rule | Oas2Rule = (opts) => {
   const validator = new AjvValidator();
@@ -28,12 +28,13 @@ export const NoInvalidParameterExamples: Oas3Rule | Oas2Rule = (opts) => {
 
         if (isPlainObject(parameter.examples)) {
           for (const [key, example] of Object.entries(parameter.examples)) {
-            if (isPlainObject(example) && 'value' in example) {
+            const selected = getExampleValueToValidate(example);
+            if (selected) {
               validateExample({
-                example: example.value,
+                example: selected.value,
                 schema: parameter.schema!,
                 options: {
-                  location: ctx.location.child(['examples', key]),
+                  location: ctx.location.child(['examples', key, selected.field]),
                   ctx,
                   validator,
                   allowAdditionalProperties: !!opts.allowAdditionalProperties,