schema-no-contradictions (OpenAPI linter rule)

schema-no-contradictions

Since 0.9.0

This rule reports schemas with contradicting constraints, which reject every value or some of the properties they describe.

Rule Details

The rule merges each schema with its allOf members, following references, and reports contradictions it can prove:

allOf members requiring types with nothing in common, such as string and integer;
bounds excluding every value: minimum above maximum (taking exclusiveMinimum and exclusiveMaximum into account, and integers when the type is integer), minLength above maxLength, minItems above maxItems, minProperties above maxProperties, or more required properties than maxProperties;
an allOf member rejecting every value, e.g. false or not: {}, and anyOf or oneOf whose every branch does;
enum or const values of an allOf member none of which satisfies the whole schema;
a required property whose schema rejects every value, or which an allOf member with additionalProperties: false does not declare;
a property which can never be present because an allOf member with additionalProperties: false does not declare it. This is the common mistake of closing a base schema and extending it with allOf; use unevaluatedProperties: false (OpenAPI 3.1) on the combined schema instead.

A contradiction is reported once, at the schema it originates from, and not again at every schema using that one. Formats are not checked, and constraints the rule cannot reason about (such as pattern) never lead to a report.

Configuration

None.

Examples

Good. Cat declares every property it allows.

components:
  schemas:
    Pet:
      type: object
      required: [petType]
      properties:
        petType:
          type: string
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - properties:
            meow:
              type: boolean
      unevaluatedProperties: false

Bad. Pet forbids meow, so a Cat can never have it.

components:
  schemas:
    Pet:
      type: object
      additionalProperties: false
      required: [petType]
      properties:
        petType:
          type: string
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - properties:
            meow:
              type: boolean

Bad. No value is both a string and an integer.

components:
  schemas:
    Id:
      allOf:
        - type: string
        - type: integer

When Not to Use It

We recommend to always enable this rule.

Compatibility