schema-no-contradictions

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

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. In OpenAPI 3.0 documents, nullable and the boolean exclusiveMinimum and exclusiveMaximum are taken into account, and keywords beside $ref are ignored as the specification requires.

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

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-no-contradictions: off

Related rules

Was this helpful?