openapi-editing-patterns

OpenAPI Schema Editing Patterns

Required Fields Pattern

Always specify required fields explicitly:

# ✅ CORRECT: Explicit required array
type: object
required:
  - id
  - name
  - email
properties:
  id:
    type: string
  name:
    type: string
  email:
    type: string
  phoneNumber:
    type: string
    nullable: true  # Optional field

# ❌ WRONG: No required array
type: object
properties:
  id:
    type: string
  name:
    type: string

Nullable vs Optional

• Optional field: Not in required array
• Nullable field: Can be null, use nullable: true

# ✅ CORRECT: Clear nullable pattern
properties:
  middleName:
    type: string
    nullable: true
    description: Optional middle name (can be null)

  lastName:
    type: string
    description: Required last name (not nullable)

Descriptions

Add descriptions for non-obvious fields:

# ✅ CORRECT: Descriptive
properties:
  status:
    type: string
    enum: [pending, approved, rejected]
    description: Current approval status of the application

  createdAt:
    type: string
    format: date-time
    description: ISO 8601 timestamp when record was created

# ❌ WRONG: Missing descriptions
properties:
  status:
    type: string
    enum: [pending, approved, rejected]
  createdAt:
    type: string

Unverified Backend Contracts

Mark fields that need backend verification with x-unverified: true:

# ✅ CORRECT: Mark unverified fields
properties:
  agentCommission:
    type: number
    nullable: true
    x-unverified: true
    description: "TODO: Verify with backend - observed in responses but not documented in route handler"

Enum Values

Use enums for fixed value sets:

# ✅ CORRECT: Enum with description
status:
  type: string
  enum:
    - draft
    - pending
    - approved
    - rejected
  description: Document workflow status

# ❌ WRONG: String without enum constraint
status:
  type: string
  description: Status (draft, pending, approved, or rejected)