Back to blog API Design

I analyzed 7,039 OpenAPI spec errors and these are the most common ones

I analyzed 7,039 OpenAPI spec errors and summarized the most common ones with broken examples, fixed snippets, and references.

Published

April 23, 2026

Reading time

9 min read

Topics covered

#OpenAPI #Validation #API Design #Swagger #Errors #Best Practices #API Documentation #Debugging #GitHub Actions #CI/CD
Screenshot showing common OpenAPI specification errors and validation results

Why read this

See the most frequent OpenAPI validation errors from real specs and fix them quickly with practical examples.

  • Understand what each validator message usually means.
  • Compare broken and fixed OpenAPI snippets side by side.
  • Use references to verify each fix against the spec.
·
9 min read

I analyzed 7,039 OpenAPI spec errors and grouped the most frequent validator messages into a practical fix guide.

For each error, you get a short explanation, a broken snippet that reproduces the issue, a corrected version, and a reference to the official docs.

If you want to catch these automatically in pull requests, use the ApiNotes GitHub Action: https://github.com/marketplace/actions/apinotes-openapi-validate-diff

# Error frequency across 7,039 specs

The chart below groups all error occurrences by category. The many individual "Schema X is invalid: can't resolve reference" messages are all the same broken $ref pattern from the same large spec — grouped here under one bar.

Error occurrences — 7,039 specs analysed
nullable deprecated (use type array)24,539
Must match exactly one schema in oneOf19,772
Must have required property $ref19,136
Must NOT have additional properties7,232
Must be equal to one of the allowed enum values6,026
Type errors (must be string / array / boolean / object)3,857
Broken $ref resolution (schema can't resolve reference)2,800
Missing required fields (schema / content / description)805

Bars scaled relative to highest error count (24,539). Multiple occurrences per spec are counted.

# Error 1: nullable Is Deprecated in OpenAPI 3.1

# Problem

In OpenAPI 3.1, nullable: true is no longer the recommended way to represent null values. Use JSON Schema style types and include "null" in the type array.

# Broken Spec Example

yaml
components:
  schemas:
    UserNickname:
      type: string
      nullable: true

# Fixed Spec Example

yaml
components:
  schemas:
    UserNickname:
      type:
        - string
        - "null"

# Reference (Optional)

# Error 2: Payload Must Match Exactly One Schema in oneOf

# Problem

oneOf requires the payload to validate against exactly one subschema. If it matches zero or multiple subschemas, validation fails.

# Broken Spec Example

yaml
components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'

    Cat:
      type: object
      properties:
        name:
          type: string

    Dog:
      type: object
      properties:
        name:
          type: string

# Fixed Spec Example

yaml
components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      type: object
      required:
        - petType
      properties:
        petType:
          type: string
          enum: [cat]
        name:
          type: string

    Dog:
      type: object
      required:
        - petType
      properties:
        petType:
          type: string
          enum: [dog]
        name:
          type: string

# Reference (Optional)

# Error 3: Reference Object Must Have Required Property $ref

# Problem

When you use a Reference Object, it must contain a $ref property. If $ref is missing, the object is invalid and validators will fail.

# Broken Spec Example

yaml
paths:
  /users:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                # Invalid reference object (missing $ref)
                description: User schema reference

# Fixed Spec Example

yaml
paths:
  /users:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

# Reference (Optional)

# Error 4: Object Must NOT Have Additional Properties

# Problem

This error appears when an object contains fields that are not allowed by the schema, typically when additionalProperties: false is set or when the schema for that object only permits known keys.

# Broken Spec Example

yaml
components:
  schemas:
    User:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
        email:
          type: string

example:
  id: 1
  email: [email protected]
  role: admin # Not defined in User.properties

# Fixed Spec Example

yaml
components:
  schemas:
    User:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
        email:
          type: string
        role:
          type: string

example:
  id: 1
  email: [email protected]
  role: admin

# Reference (Optional)

# Error 5: Value Must Be Equal to One of the Allowed Values

# Problem

This happens when a field uses enum and the provided value is not one of the allowed options.

# Broken Spec Example

yaml
components:
  schemas:
    Order:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - paid
            - cancelled

example:
  status: completed # Not in enum

# Fixed Spec Example

yaml
components:
  schemas:
    Order:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - paid
            - cancelled

example:
  status: paid

# Reference (Optional)

# Error 6: Value Must Be String

# Problem

This error appears when a schema defines type: string but the provided value is a number, boolean, object, or array.

# Broken Spec Example

yaml
components:
  schemas:
    Profile:
      type: object
      properties:
        username:
          type: string

example:
  username: 12345

# Fixed Spec Example

yaml
components:
  schemas:
    Profile:
      type: object
      properties:
        username:
          type: string

example:
  username: "12345"

# Reference (Optional)

# Error 7: Value Must Be Array

# Problem

This error appears when a schema defines type: array but the provided value is a single item, object, string, or number.

# Broken Spec Example

yaml
components:
  schemas:
    TagsPayload:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string

example:
  tags: backend

# Fixed Spec Example

yaml
components:
  schemas:
    TagsPayload:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string

example:
  tags:
    - backend

# Reference (Optional)

# Error 8: Schema example Is Invalid: Cannot Resolve $ref

# Problem

This happens when an example or schema uses a $ref that points to a component path that does not exist, for example #/components/schemas/Product when Product is missing.

# Broken Spec Example

yaml
openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /products:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: string

# Fixed Spec Example

yaml
openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /products:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

# Reference (Optional)

If these are the same errors your team keeps fixing in reviews, automate the checks in pull requests so developers get feedback before merge with the ApiNotes OpenAPI Validate & Diff action.

🚀 Validate OpenAPI in PRs

# Run These Checks Automatically in GitHub Actions

If your team keeps seeing these same errors, move validation into CI so broken specs do not get merged.

The ApiNotes OpenAPI Validate & Diff GitHub Action validates your spec and can detect breaking changes on every PR.

yaml
name: OpenAPI Check

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'openapi.yml'
      - 'docs/**/*.yaml'
      - 'docs/**/*.yml'

permissions:
  contents: read
  pull-requests: write

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: apinotes/openapi-validate@main
        with:
          api-key: ${{ secrets.APINOTES_API_KEY }}
          spec-path: 'openapi.yaml'
          diff-enabled: 'true'
          fail-on-errors: 'true'
          fail-on-breaking: 'true'
          comment-on-pr: 'true'

Use this when you want fast feedback in PRs and a clear signal when an API change is breaking.

# Final Notes

Most OpenAPI validation failures come from a few repeat patterns: type mismatches, invalid composition (oneOf), unresolved references, and schema constraints (enum, additionalProperties).

If you add validation in CI and run checks before code generation, these errors become fast to catch and cheap to fix.