How to Handle Optional Fields When Converting JSON to Typescript Types

When your JSON-to-TypeScript converter marks everything as optional, how do you know which fields actually matter?

You just pasted a 340-line JSON response from a third-party shipping API into your go-to JSON-to-TypeScript converter. The output looks clean—until you notice every single field has a question mark next to it. Now your IDE won't flag you when you forget to pass a critical trackingNumber, and your staging environment logged 47 uncaught type errors last week because the generated types weren't actually catching gaps.

This is the optional field problem. If you're building client integrations against APIs you don't control, it's the single biggest type safety issue you'll face after conversion. Most converters play it safe. They mark everything optional because they can't distinguish between a field that's genuinely absent and one that just happened to be null in the sample you pasted. That safety net becomes a blind spot.

Let's walk through a step-by-step process for taking a raw converter output and turning it into types that actually reflect what your API does.

Why do JSON-to-TypeScript converters mark fields as optional by default?

Most converters—whether you're using an online tool, a CLI, or a library like quicktype—analyze the JSON you give them. If a field is missing from your sample, they mark it optional. If it's present but null, some converters mark it optional. Others generate a union like string | null. Neither approach is wrong, but neither is complete either.

Here's the core issue: a converter only knows what it sees. If your sample payload includes discountCode in 3 out of 10 responses, the converter can't know whether that field is conditionally required by the API contract or just rare in your sample. It guesses. And the safest guess is always ?.

The result? You get types that compile cleanly but lie about your data. Fields that the API always returns get marked optional, and fields that are genuinely conditional get treated the same as required ones. Your type system loses its teeth.

How can you detect truly optional fields vs. nullable fields in JSON data?

Before you touch any generated types, you need to separate three distinct cases:

Step 1: Collect multiple sample payloads

Grab at least 10–15 real responses from your API endpoint. Not from documentation—actual responses. If you're working with a payment API, pull successful charges, failed charges, refunds, and edge cases. One sample is never enough. I've seen APIs where the failureReason field only appears in 8% of responses, but when it does, it's critical for debugging.

Step 2: Diff the field presence across samples

Run each sample through your converter and compare the outputs. Fields that appear in every single payload are required. Fields that appear in some but not others are genuinely optional. Fields that appear in every payload but sometimes carry null are nullable—not optional. These are three different type signatures:

// Required: always present, never null
recipientName: string;

// Optional: sometimes absent entirely
discountCode?: string;

// Nullable: always present, sometimes null
failureReason: string | null;

That distinction matters. If you conflate nullable with optional, you'll write defensive checks like if (response.failureReason) when the field is actually always there—you just need to check if it's null, not if it exists.

Step 3: Cross-reference with API documentation

If the API provider offers a schema (Swagger, OpenAPI, or even a field reference table), use it to validate your findings. Documentation tells you intent. Samples tell you reality. When they disagree, trust the samples for type generation but flag the discrepancy for your team. I've encountered APIs where the docs said a field was required, but 15% of live responses omitted it due to a backend bug. Your types should match reality, not aspiration.

What's the step-by-step process for refining optional fields after conversion?

Once you've categorized your fields, here's the workflow I use on every converter output:

Step 1: Strip all optional markers first

Take the converter's output and remove every ?. This sounds aggressive, but it gives you a clean baseline. You're going to add optionality back deliberately, field by field, based on what your sample analysis showed.

// Before: everything optional
interface Shipment {
  id?: string;
  status?: string;
  trackingNumber?: string;
  estimatedDelivery?: string;
  signatureRequired?: boolean;
}

// After stripping: everything required (temporary)
interface Shipment {
  id: string;
  status: string;
  trackingNumber: string;
  estimatedDelivery: string;
  signatureRequired: boolean;
}

Step 2: Add optionality back based on sample data

For each field, check your diff results. If the field was absent in any sample, add the ?. If it was present but null in some samples, add | null to the type. If it was present and non-null in every sample, leave it required.

interface Shipment {
  id: string;                        // Always present
  status: string;                    // Always present
  trackingNumber?: string;           // Absent for label-less shipments
  estimatedDelivery: string | null;  // Present but null for pending shipments
  signatureRequired: boolean;        // Always present, defaults to false
}

Step 3: Add JSDoc annotations for conditional optionality

Some fields are optional only under specific conditions. A returnLabel field might only appear when status is "delivered". Document these relationships so the next engineer doesn't have to reverse-engineer them:

interface Shipment {
  id: string;
  status: "pending" | "shipped" | "delivered" | "returned";
  trackingNumber?: string;
  /**
   * Only present when status === "delivered"
   */
  returnLabel?: string;
  estimatedDelivery: string | null;
  signatureRequired: boolean;
}

How do you handle nested optional fields without breaking type safety?

Nested objects are where most engineers give up and leave everything optional. Don't. The same rules apply—you just need to apply them recursively.

Step 1: Treat each nested object as its own type

If your shipment has a sender object with name, address, and phone, analyze that object's field presence independently. The parent field might always be present while inner fields vary.

Step 2: Watch for the "optional parent" trap

If sender is optional on the parent type, TypeScript won't let you access sender.name without a null check. That's correct behavior. But if sender is always present and only sender.phone is optional, don't mark the whole sender object optional just because one inner field is. This is the most common mistake I see in converter output—propagating optionality upward when it should stay at the leaf.

// Wrong: marking sender optional because phone is optional
interface Shipment {
  sender?: {
    name: string;
    address: string;
    phone?: string;
  };
}

// Correct: sender is always present, phone is the optional field
interface Shipment {
  sender: {
    name: string;
    address: string;
    phone?: string;
  };
}

Step 3: Use utility types for deeply nested optionality

If you're dealing with a response that has 4+ levels of nesting and mixed optionality, consider breaking out utility types. TypeScript's Partial<T> is tempting but dangerous—it marks everything optional. Instead, define explicit partial versions only for the sections that need them:

type RequiredSender = {
  name: string;
  address: string;
};

type OptionalSenderFields = {
  phone?: string;
  email?: string;
  company?: string;
};

type Sender = RequiredSender & OptionalSenderFields;

When should you override a converter's optional field decisions?

Converters are starting points, not finish lines. Override them in three specific scenarios:

Scenario 1: The converter marked a field optional, but your business logic requires it. If your application crashes without a trackingNumber, mark it required in your type even if the API sometimes omits it. Then handle the missing-field case explicitly in your runtime validation. Your types should reflect what your code needs, not just what the API sends.

Scenario 2: The converter generated a union type when you know the field is enum-like. If status came back as string but your samples only ever show four values, tighten it to a union of string literals. This prevents typos and gives you exhaustiveness checking in switch statements.

Scenario 3: The converter marked a field required, but it's actually optional in edge cases. This happens when your sample set was too narrow. If you later encounter a response that omits a field the converter marked required, update the type immediately. Stale types are worse than no types.

The goal throughout this process is simple: your TypeScript types should be a contract you can trust. When a field is required, you should be able to access it without a null check and never hit a runtime error. When a field is optional, the type system should force you to handle the missing case. A converter gets you 60% of the way there. The remaining 40% is manual work—but it's the work that turns generated types into actual safety rails.