schema-oneof-no-overlap (OpenAPI linter rule)

schema-oneof-no-overlap

Since 0.9.0

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.

Configuration

None.

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

When Not to Use It

Disable this rule when the tools consuming your document do not validate oneOf strictly. Where overlapping branches are intended, anyOf expresses them correctly.

Compatibility