{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"spec-ref-siblings","__idx":0},"children":["spec-ref-siblings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks that only specification-permitted properties are used next to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."]},{"$$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":"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":"AsyncAPI"},"children":["AsyncAPI"]},{"$$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.6"]},{"$$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":"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":"Open-RPC"},"children":["Open-RPC"]},{"$$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":["1.x"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$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":"Overlay"},"children":["Overlay"]},{"$$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":["1.2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 3.1 treats ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," differently depending on where it appears:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schema Object"]}," keywords next to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," take effect."," ","All siblings are allowed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reference Object"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," cannot be extended."," ","Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," are allowed alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OAS 2.0 and OAS 3.0 predate JSON Schema 2020-12 and allow only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," itself."," ","AsyncAPI and Open-RPC also allow only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," itself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Path Item Object is the exception: every OpenAPI version lists ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," among its own fields, so a Path Item keeps its siblings and the rule does not report them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Overlay 1.2, an item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions"]}," that has a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," applies a reusable action from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.actions"]},"."," ","It must have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]},", and it can also have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," and specification extensions."," ","Action fields such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["copy"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove"]}," belong in the reusable action's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]},", so the rule reports them next to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure the rule, add it to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]}," object in your configuration file, and set the desired ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/rules#severity-settings"},"children":["severity"]},"."]},{"$$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"]}," (in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]}," configuration)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  spec-ref-siblings: error\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  spec-ref-siblings: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," siblings next to a Reference Object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," (OAS 3.1), where neither ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}," nor the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-internal"]}," extension is allowed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"responses:\n  '200':\n    $ref: '#/components/responses/Ok'\n    x-internal: true\n    headers:\n      X-Rate-Limit:\n        schema:\n          type: integer\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," siblings next to a Reference Object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," (OAS 3.1), where only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," are allowed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"responses:\n  '200':\n    $ref: '#/components/responses/Ok'\n    description: overrides the referenced description\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," siblings next to a Schema Object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," (OAS 3.1), where JSON Schema 2020-12 keywords are allowed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"schema:\n  $ref: '#/components/schemas/Base'\n  readOnly: true\n  description: a read-only variant of Base\n  x-internal: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-rules","__idx":4},"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/spec-strict-refs"},"children":["spec-strict-refs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/common/struct"},"children":["struct"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":5},"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/oas3/spec-ref-siblings.ts"},"children":["Rule source"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/oas/v3.1.0.html#reference-object"},"children":["Reference Object docs"]}]}]}]},"frontmatter":{"slug":"/docs/cli/rules/oas/spec-ref-siblings"},"tagList":[],"title":"spec-ref-siblings","lastModified":"2026-09-29T07:29:49.000Z"}