{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"no-invalid-parameter-examples","__idx":0},"children":["no-invalid-parameter-examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Disallow invalid parameter examples."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"OAS"},"children":["OAS"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Compatibility"},"children":["Compatibility"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n\nRoot ==> Paths --> PathItem --> Operation --> Parameter --> Example\nPathItem --> Parameter\nParameter --> Schema\nRoot ==> components\n\nNamedParameters --> Parameter\n\nSchema -.compares schema\\nto example.- Example\n\nsubgraph components\nNamedParameters\nend\n\n\nstyle Example fill:#codaf9,stroke:#0044d4,stroke-width:5px\nstyle Schema fill:#codaf9,stroke:#0044d4,stroke-width:5px\n","diagramHtml":"

components

compares schema
to example

Root

Paths

PathItem

Operation

Parameter

Example

Schema

NamedParameters

","diagramHtmlDark":"

components

compares schema
to example

Root

Paths

PathItem

Operation

Parameter

Example

Schema

NamedParameters

"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your parameter schema and example conflict, there is a problem in the definition of the schema or the example."," ","Solve it before you ship it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},". Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["allowAdditionalProperties"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Determines if additional properties are allowed in examples. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n no-invalid-parameter-examples:\n severity: error\n allowAdditionalProperties: false\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given the following configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n no-invalid-parameter-examples:\n severity: error\n allowAdditionalProperties: false\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," parameter example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /results:\n get:\n summary: Search Chess Results\n operationId: searchChessResult\n parameters:\n - name: username\n in: query\n schema:\n type: string\n maxLength: 15\n description: Value to query the chess results against usernames\n example: ThisUsernameIsTooLong\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," parameter example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /results:\n get:\n summary: Search Chess Results\n operationId: searchChessResult\n parameters:\n - name: username\n in: query\n schema:\n type: string\n maxLength: 10\n description: Value to query the chess results against usernames\n example: ella\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"openapi-32-datavalue","__idx":4},"children":["OpenAPI 3.2 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In OpenAPI 3.2, provide the structured example in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]},", which is validated against the schema the same way ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is."," ","When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]}," is present, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," must be absent (see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/spec-example-values"},"children":["spec-example-values"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /results:\n get:\n summary: Search Chess Results\n operationId: searchChessResult\n parameters:\n - name: rating\n in: query\n schema:\n type: integer\n examples:\n grandmaster:\n dataValue: '2500'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example produces an error because the rating is a string instead of an integer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /results:\n get:\n summary: Search Chess Results\n operationId: searchChessResult\n parameters:\n - name: rating\n in: query\n schema:\n type: integer\n examples:\n grandmaster:\n dataValue: 2500\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-rules","__idx":5},"children":["Related rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-invalid-media-type-examples"},"children":["no-invalid-media-type-examples"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-invalid-schema-examples"},"children":["no-invalid-schema-examples"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":6},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-invalid-parameter-examples.ts"},"children":["Rule source"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/parameter/"},"children":["OpenAPI Parameter docs"]}]}]}]},"frontmatter":{"slug":"/docs/cli/rules/oas/no-invalid-parameter-examples"},"tagList":[],"title":"no-invalid-parameter-examples","lastModified":"2026-07-16T10:18:52.000Z"}