schema-oneof-no-overlap

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

This rule reports oneOf branches that a single value can match.

Rule details

A value is valid against oneOf only if it matches exactly one branch. When branches overlap, the values matching several of them are rejected, which is rarely intended: two object schemas without additionalProperties: false both accept {}, and number overlaps integer.

The rule reports:

  • identical branches, such as two references to the same schema or two schemas with the same content;
  • a value matching two branches. The rule tries the values the branches document (example, examples, default, const and enum) and small values it builds from their constraints, and reports only a value that it has validated against both branches and against the keywords beside oneOf. The message shows that value.

oneOf with a discriminator is skipped, because tools choose the branch named by the discriminator instead of validating every branch. Branches with recursive or external references are skipped too. Turn the rule off when the tools that consume the document do not validate oneOf strictly; where overlapping branches are meant, anyOf says so.

Examples

Good. Each branch forbids the other one’s properties.

components:
  schemas:
    Pet:
      oneOf:
        - type: object
          additionalProperties: false
          required: [meow]
          properties:
            meow:
              type: boolean
        - type: object
          additionalProperties: false
          required: [bark]
          properties:
            bark:
              type: boolean

Good. A discriminator selects the branch.

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType

Bad. {"name": ""} matches both branches, so it is rejected.

components:
  schemas:
    Pet:
      oneOf:
        - type: object
          required: [name]
          properties:
            name:
              type: string
            meow:
              type: boolean
        - type: object
          required: [name]
          properties:
            name:
              type: string
            bark:
              type: boolean

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      schema-oneof-no-overlap: off

Related rules

Last updated on View as Markdown
Was this helpful?