# schema-oneof-no-overlap

Source: https://apigenie.pl/docs/linter/openapi/rules/schema-oneof-no-overlap

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.

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

## 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

This rule is compatible with all OpenAPI 3.x versions.