OpenAPI Errors Cheat Sheet

In OpenAPI 3.1, nullable: true is no longer valid. Use JSON Schema style with null in the type array.

components:
  schemas:
    UserNickname:
      type: string
      nullable: true  # ✗ deprecated

components:
  schemas:
    UserNickname:
      type:
        - string
        - "null"  # ✓ 3.1

Ref: spec.openapis.org/oas/v3.1.0

oneOf requires the payload to validate against exactly one subschema. Add a discriminator with unique enum values to prevent ambiguity.

Pet:
  oneOf:
    - $ref: '#/…/Cat'
    - $ref: '#/…/Dog'
# Cat & Dog have same shape
# → matches both → error

Pet:
  oneOf:
    - $ref: '#/…/Cat'
    - $ref: '#/…/Dog'
  discriminator:
    propertyName: petType
Cat:
  properties:
    petType: { enum: [cat] }

Ref: json-schema.org · combining

A Reference Object that lacks a $ref property is invalid. Replace any bare descriptions with a proper $ref pointing to a defined component.

schema:
  # missing $ref!
  description: User ref

schema:
  $ref: '#/components/
         schemas/User'

Ref: spec.openapis.org · reference-object

When additionalProperties: false is set, every key in an example or payload must be defined in properties. Either add the missing key or remove it from the example.

User:
  additionalProperties: false
  properties:
    id: { type: integer }
    email: { type: string }

example:
  id: 1
  role: admin  # ✗ not defined

User:
  additionalProperties: false
  properties:
    id: { type: integer }
    email: { type: string }
    role: { type: string }

example:
  id: 1
  role: admin

Ref: json-schema.org · object

When a field uses enum, the provided value must be one of the listed options. Update the example or extend the enum to include the value.

status:
  type: string
  enum:
    - pending
    - paid
    - cancelled

# example value:
status: completed  # ✗ not in enum

status:
  type: string
  enum:
    - pending
    - paid
    - cancelled

# example value:
status: paid  # ✓ in enum

Ref: json-schema.org · enum

When a schema declares type: string, the example value must be a string — not a number, boolean, or object. Wrap the value in quotes.

username:
  type: string

# example value:
username: 12345  # ✗ number

username:
  type: string

# example value:
username: "12345"  # ✓ string

Ref: json-schema.org · string

When a schema defines type: array, the example must be a list — not a single string or object. Wrap the value in YAML sequence syntax.

tags:
  type: array
  items:
    type: string

tags: backend  # ✗ single string

tags:
  type: array
  items:
    type: string

tags:
  - backend  # ✓ array

Ref: json-schema.org · array

A $ref pointing to a component path that does not exist causes validation to fail. Make sure the target schema name matches exactly what is defined under components/schemas.

schema:
  $ref: '#/components/
         schemas/Product'
# …but only "Item" defined:
schemas:
  Item: { ... }

schema:
  $ref: '#/components/
         schemas/Product'

schemas:
  Product:  # ✓ name matches
    type: object

Ref: spec.openapis.org · reference-object