# schema-oneof-no-overlap

Source: https://api-genie.dev/docs/linter/openapi/rules/schema-oneof-no-overlap

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. 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.

```yaml
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.

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

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

```yaml
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
```
