Decide Optional vs Required Fields in JSON-to-TypeScript

Three Modifiers, Four Field Behaviors

JSON conversion tools often guess wrong about whether a field is optional, required, nullable, or absent. The right call comes from observing several samples, not one.

Sample Evidence

[
  { "id": 1, "name": "Alice", "email": "a@x.com", "phone": "555" },
  { "id": 2, "name": "Bob",   "email": "b@x.com", "phone": null },
  { "id": 3, "name": "Carol", "email": "c@x.com" }
]

Generated TypeScript

interface Contact {
  id: number;            // present in every sample
  name: string;          // present in every sample
  email: string;         // present in every sample
  phone?: string | null; // sometimes missing, sometimes null, sometimes a string
}

Decision Table

Observed across samples	Modifier to apply	TypeScript
Always present, never null	required	field: T
Always present, sometimes null	nullable	field: T | null
Sometimes absent, never null	optional	field?: T
Sometimes absent or null	optional + nullable	field?: T | null

Why It Matters at the Call Site

const c: Contact = await loadContact();

c.phone.toLowerCase();           // Error: c.phone is string | null | undefined
c.phone?.toLowerCase();          // Safe

If the converter had marked phone as string, every consumer would write code that crashes on the second sample. The optional-plus-nullable modifier forces correct handling.

Generation Workflow

1. Feed the converter at least 3-5 representative samples, not just one.
2. Toggle "merge keys" so the tool unifies seen variants per field.
3. Manually review fields you know are nullable in your domain (timestamps, foreign keys, optional metadata).
4. Document edge cases with comments — // nullable when no payment method next to paymentMethod: string | null.

The closer your modifiers match production reality, the fewer runtime surprises survive into your UI.