Nullable fields explicitly marked

When a field typed as string returns null at runtime, consumers get a type error or a silent coercion depending on their language. When some endpoints omit missing fields and others include them as null, every consumer must guard against both undefined and null for every optional field. This is the most common source of unexpected Cannot read properties of null errors in client applications. iso-25010:2011 compatibility.interoperability requires that the schema truthfully represent what the API sends — nullability is a core part of that contract.

Mark nullable fields explicitly in both your TypeScript types and your OpenAPI schema. Choose one approach for missing data — always include with null, or always omit — and document it:

// TypeScript -- explicit nullability:
interface UserResponse {
  id: string            // always present
  name: string          // always present
  avatarUrl: string | null   // explicitly nullable
  bio: string | null         // explicitly nullable
}

# OpenAPI -- nullable fields:
UserResponse:
  type: object
  required: [id, name]
  properties:
    avatarUrl: { type: string, nullable: true }

Consistency between "return null" and "omit the field" is non-negotiable — consumers cannot handle both reliably.