Last updated

no-schema-type-mismatch

Ensures that a schema's structural properties match its declared type. In particular:

  • A schema of type object must not include an items field.
  • A schema of type array must not include a properties field.
OASCompatibility
2.0✅
3.0✅
3.1✅
if type is object
if type is array
Schema
'items' field exists?
'properties' field exists?

API design principles

When designing an API schema, the defined type should be consistent with its structure:

  • Objects are collections of key/value pairs. They should be defined using properties (or additionalProperties) and must not use items.
  • Arrays are ordered lists of items and must use items to define their content. Including properties is invalid.

This rule helps catch typos and misconfigurations early in your API definition.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default is error in the recommended configuration.

Example configuration:

rules:
  no-schema-type-mismatch: error

Examples

Incorrect Examples

Object type with an items field

properties:
  user:
    type: object
    properties:
      id:
        type: string
    items:
      type: number

Error: An object type should not include an items field.

Array type with a properties field

properties:
  tags:
    type: array
    properties:
      name:
        type: string

Error: An array type should not include a properties field.

Correct Examples

Object type with proper properties

properties:
  user:
    type: object
    properties:
      id:
        type: string
      name:
        type: string

Array type with proper items

properties:
  tags:
    type: array
    items:
      type: string

Resources