Most misunderstood keywords {#misunderstood-openapi}#

Most Commonly Misunderstood Keywords in OpenAPI#

Even experienced engineers stumble over certain OpenAPI keywords because of subtle differences across versions or unexpected tooling behavior. This page highlights the most commonly misunderstood ones — with explanations, gotchas, and corrected usage.

nullable#

• Problem: In OpenAPI 3.0, nullable: true was used to indicate a field could be null. In 3.1, this keyword was removed in favor of JSON Schema syntax.
• Correct (3.1+):

type: [string, "null"]

example vs examples#

• Problem: Confusion between singular and plural forms.
• Usage:
  • example: a single inline example value.
  • examples: multiple named examples, each with its own summary and value.
• Correct:

content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      simple:
        summary: A basic user example
        value:
          id: 123
          name: "Jane"

$ref#

• Problem: $ref cannot be combined with other siblings (like type or description) unless allowed by tooling. This is a common error.
• Correct:

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

• Incorrect:

schema:
  $ref: '#/components/schemas/User'
  type: object   # ❌ Not allowed alongside $ref

oneOf / anyOf / allOf#

• Problem: Misunderstanding when to use each leads to broken validation or bad client code.
• Usage:
  • oneOf: matches exactly one schema.
  • anyOf: matches one or more.
  • allOf: schema composition (inheritance).
• Correct:

oneOf:
  - $ref: '#/components/schemas/Car'
  - $ref: '#/components/schemas/Truck'

additionalProperties#

• Problem: Many assume it defaults to false. In JSON Schema (and OAS), the default is true.
• Correct:

type: object
properties:
  name:
    type: string
additionalProperties: false

discriminator#

• Problem: Often defined without aligning with oneOf. Clients may not resolve types correctly.
• Correct:

oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
discriminator:
  propertyName: petType

default#

• Problem: Misused as an example or fallback value. In OpenAPI/JSON Schema, default is informative only — tools may or may not enforce it.
• Correct:

type: string
default: "guest"

deprecated#

• Problem: Setting deprecated: true does not remove or disable an operation/field — it is purely a signal for clients.
• Correct:

parameters:
  - name: userId
    in: query
    schema:
      type: string
    deprecated: true

format#

• Problem: format is a hint (like date-time, uuid, binary) and not always enforced. Tools may ignore unknown formats.
• Correct:

type: string
format: uuid

default vs default response#

• Problem: Confusion between schema default values and the default response object for operations.
• Usage:

responses:
  default:
    description: Unexpected error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'

security#

• Problem: Many assume global security overrides local ones. Actually, operation-level security overrides global security.
• Correct:

security:
  - bearerAuth: []

servers#

• Problem: Variables in server URLs are often forgotten.
• Correct:

servers:
  - url: https://{environment}.api.example.com/v1
    variables:
      environment:
        default: dev
        enum:
          - dev
          - staging
          - prod