{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/rules/oas/no-illogical-composition-keywords","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/rules/oas/no-illogical-composition-keywords","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"no-illogical-composition-keywords","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"no-illogical-composition-keywords","__idx":0},"children":["no-illogical-composition-keywords"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensures that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," combine schemas that a value can actually resolve against."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rule reports:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]}," with fewer than two schemas, unless the schema declares a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]}," with fewer than two schemas, unless the schema declares a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," with fewer than two schemas that neither declares another keyword of its own nor extends a discriminated schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["schemas repeated inside the same keyword"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["empty schemas (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{}"]},") used as members"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["two ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," schemas that a single value can match at the same time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["schemas that accept null alongside a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," member that also accepts null"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["member schemas that omit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," property from required"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inline ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]}," members that a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," cannot select"]}]},{"$$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 ==> components --> NamedSchemas --> Schema\n\nSchema ==> OneOf\nSchema ==> AnyOf\nSchema ==> AllOf\n\nstyle OneOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\nstyle AnyOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\nstyle AllOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\n","diagramHtml":"

Root

components

NamedSchemas

Schema

OneOf

AnyOf

AllOf

","diagramHtmlDark":"

Root

components

NamedSchemas

Schema

OneOf

AnyOf

AllOf

"},"children":["flowchart TD\n\nRoot ==> components --> NamedSchemas --> Schema\n\nSchema ==> OneOf\nSchema ==> AnyOf\nSchema ==> AllOf\n\nstyle OneOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\nstyle AnyOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\nstyle AllOf fill:#codaf9,stroke:#0044d4,stroke-width:5px\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," means \"exactly one\"."," ","When a value matches two of the listed schemas, no tool can tell which one was intended."," ","Validators, code generators, and documentation all disagree about the result."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One of the most common ambiguous patterns is nullability."," ","If a referenced schema already accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," also lists ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: 'null'"]},", a null value matches both branches."," ","The same ambiguity appears one level up, when the schema holding the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," is itself nullable and a member accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," too."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deciding whether two arbitrary schemas overlap is not solvable in general, so the comparison stays deliberately narrow."," ","It reads ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nullable"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["const"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["properties"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["additionalProperties: false"]},"."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["const"]}," counts as a single-value ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]},"."," ","One member can use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]}," and the other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["const"]},"."," ","When a member uses any other constraint, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pattern"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum"]},", or a nested ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]},", that constraint may be what separates the schemas."," ","In such cases, the rule reports nothing for the pair."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," names the property that tells the members apart."," ","The rule trusts it and checks only what the specification requires."," ","The property must be listed in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]}," in every member schema, because a value can otherwise omit it and nothing decides which schema applies."," ","OAS 3.2 turned this into a specification requirement and added ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultMapping"]}," as an alternative to marking the property required, so on 3.2 documents ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/oas/spec-discriminator-defaultMapping"},"children":["spec-discriminator-defaultMapping"]}," reports it and this rule stays quiet."," ","Every member must also be a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},": a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," selects a schema by its component name, and the specification states that inline ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]}," subschemas are not considered, so an inline member can never be selected."," ","A member that declares ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$id"]}," is exempt, because a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapping"]}," entry can name it by URI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wrapping one schema in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," to attach sibling keywords, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," next to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},", stays common because support for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," siblings is uneven across tools."," ","Referencing a schema that declares a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," carries meaning of its own too: the discriminator resolves the subtype by its schema name, so the wrapper declares a subtype even when it adds no properties."," ","The rule reports an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," wrapper only when neither applies."]},{"$$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"]}," (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 no-illogical-composition-keywords: 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 this configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n no-illogical-composition-keywords: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," where both schemas accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n PhotoUrl:\n type: [string, 'null']\n format: uri\n MenuItemPhoto:\n oneOf:\n - $ref: '#/components/schemas/PhotoUrl'\n - type: 'null'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n PhotoUrl:\n type: string\n format: uri\n MenuItemPhoto:\n oneOf:\n - $ref: '#/components/schemas/PhotoUrl'\n - type: 'null'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]}," with an inline member:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n Beverage:\n type: object\n properties:\n category:\n type: string\n const: beverage\n required:\n - category\n MenuItem:\n discriminator:\n propertyName: category\n oneOf:\n - $ref: '#/components/schemas/Beverage'\n - type: object\n properties:\n category:\n type: string\n const: dessert\n required:\n - category\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Move the inline schema into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/schemas"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dessert"]}," and reference it with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]}," is optional:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n MenuItem:\n discriminator:\n propertyName: category\n oneOf:\n - $ref: '#/components/schemas/Beverage'\n - $ref: '#/components/schemas/Dessert'\n Beverage:\n type: object\n properties:\n category:\n type: string\n const: beverage\n Dessert:\n type: object\n properties:\n category:\n type: string\n const: dessert\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]}," in both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Beverage"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dessert"]}," to fix this."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," single-schema ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," that declares a subtype:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n MenuBaseItem:\n type: object\n required:\n - category\n properties:\n category:\n type: string\n discriminator:\n propertyName: category\n Dessert:\n allOf:\n - $ref: '#/components/schemas/MenuBaseItem'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," composition keywords:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"components:\n schemas:\n MenuItem:\n oneOf:\n - $ref: '#/components/schemas/Beverage'\n Order:\n allOf:\n - $ref: '#/components/schemas/Beverage'\n - $ref: '#/components/schemas/Beverage'\n - {}\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MenuItem"]}," wraps a single schema, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Order"]}," repeats one schema and adds an empty one that matches any value."]},{"$$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":"MarkdownLink","attributes":{"href":"/docs/cli/rules/common/no-schema-type-mismatch"},"children":["no-schema-type-mismatch"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/common/no-required-schema-properties-undefined"},"children":["no-required-schema-properties-undefined"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/oas/spec-discriminator-defaultMapping"},"children":["spec-discriminator-defaultMapping"]}," — on OAS 3.2, flags a discriminator whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["propertyName"]}," is optional but has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultMapping"]}," required by OAS 3.2."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no-illogical-composition-keywords"]}," checks the same issue on OAS 3.0 and 3.1, where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultMapping"]}," doesn't exist."," ","Enable both rules to cover every OAS version."]}]},{"$$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":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/oas3/no-illogical-composition-keywords.ts"},"children":["Rule source"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/schemas/"},"children":["Schema object docs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/discriminator/"},"children":["Discriminator object docs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/openapi/any-of-one-of"},"children":["How to use oneOf and anyOf in OpenAPI"]}]}]}]},"headings":[{"value":"no-illogical-composition-keywords","id":"no-illogical-composition-keywords","depth":1},{"value":"API design principles","id":"api-design-principles","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Related rules","id":"related-rules","depth":2},{"value":"Resources","id":"resources","depth":2}],"frontmatter":{"slug":"/docs/cli/rules/oas/no-illogical-composition-keywords","seo":{"title":"no-illogical-composition-keywords"}},"lastModified":"2026-08-26T10:56:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/rules/oas/no-illogical-composition-keywords","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}