When an Optional Field Comes Back Three Ways: Null, Empty String, and Missing Key in Gemini Structured Output

Tightening the entry point: nullable and required in responseSchema

Start at the entry. Instead of treating an optional field as "may be omitted," decide firmly that it "always exists, and when there is no value, it is null." Putting the field in required and declaring nullable: true sharply reduced both the missing-key and the empty-string drift.

import { GoogleGenAI, Type } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
const reviewSchema = {
  type: Type.OBJECT,
  properties: {
    sentiment: { type: Type.STRING, enum: ["positive", "neutral", "negative"] },
    summary: { type: Type.STRING },
    // Keep optional fields in required, but use nullable so "no value" is exactly null
    suggested_tag: { type: Type.STRING, nullable: true },
    reason: { type: Type.STRING, nullable: true },
  },
  // All fields required: existence is guaranteed, absence is expressed as null
  required: ["sentiment", "summary", "suggested_tag", "reason"],
  propertyOrdering: ["sentiment", "summary", "suggested_tag", "reason"],
};
 
const res = await ai.models.generateContent({
  model: "gemini-flash-latest",
  contents: reviewText,
  config: {
    responseMimeType: "application/json",
    responseSchema: reviewSchema,
  },
});

I also add one line to the prompt: "If there is no applicable value, return null rather than an empty string." Making the same promise twice — in the schema and in the prompt — visibly cut the empty-string filling. Even so, this does not drive the three shapes to zero; occasionally null and empty string still mix. That is precisely why the exit gate is needed.

Folding at the exit: the normalization gate

At the exit, fold null, empty string, undefined, and whitespace-only strings all into one representation (here, null). Once folded, keep going and shape the value into exactly what downstream expects — trimmed, lower-cased, length-capped.

type RawReview = {
  sentiment?: string | null;
  summary?: string | null;
  suggested_tag?: string | null;
  reason?: string | null;
};
 
type CleanReview = {
  sentiment: "positive" | "neutral" | "negative";
  summary: string;
  suggested_tag: string | null; // absence is always unified to null
  reason: string | null;
};
 
// The one function that folds three shapes into one
function normalizeOptional(v: unknown): string | null {
  if (v === null || v === undefined) return null;
  if (typeof v !== "string") return null;
  const t = v.trim();
  return t.length === 0 ? null : t;
}
 
function normalizeReview(raw: RawReview): CleanReview {
  const sentiment = raw.sentiment?.trim().toLowerCase();
  if (sentiment !== "positive" && sentiment !== "neutral" && sentiment !== "negative") {
    throw new Error(`unexpected sentiment: ${JSON.stringify(raw.sentiment)}`);
  }
  const tag = normalizeOptional(raw.suggested_tag);
  return {
    sentiment,
    summary: (raw.summary ?? "").trim(),
    suggested_tag: tag ? tag.toLowerCase().slice(0, 32) : null,
    reason: normalizeOptional(raw.reason),
  };
}

After passing through normalizeOptional, an optional field is either a meaningful string or null — nothing else. The line that threw on .toUpperCase() can now be written against null, like tag ? tag.toUpperCase() : "UNTAGGED". The failure asymmetry disappears, and the downstream code gets much easier to read.

The numbers: what was happening across 3,200 reviews

Before adding the normalization gate, I saved one night of raw output as-is and counted how the optional field was represented. The sample was 3,200 App Store reviews in Japanese and English, on gemini-flash-latest.

The three shapes that all mean "no value" add up to 592 rows, or 18.5% of the total. Of those, the null form that can throw is 12.6%, and the quietly-garbage empty string and missing key together are 6.0%. The night the batch died, it had stepped on one of that 12.6%.

Re-measuring after tightening the entry point, missing keys dropped to 0.3% and empty strings to 0.9%, with absence landing almost entirely on null. The remaining 1.2% is folded by the exit gate, so by the time data reaches downstream there are zero of the three shapes left. The lesson from the measurements was concrete: the entry alone, or the exit alone, each leaves a residue.

A final assertion before handing off

After normalizing, I slip a light assertion in right before the data goes to Firestore or the AdMob report rollup. If it trips here, a broken record is stopped before it enters the production datastore.

function assertClean(r: CleanReview, sourceId: string): CleanReview {
  // null is allowed, but undefined / empty / whitespace-only means a normalization leak
  for (const key of ["suggested_tag", "reason"] as const) {
    const v = r[key];
    if (v !== null && (typeof v !== "string" || v.trim().length === 0)) {
      throw new Error(`normalize leak at ${key} (source=${sourceId}): ${JSON.stringify(v)}`);
    }
  }
  return r;
}

This assertion doubles as a nightly health check on whether normalization is still working. If it fires in a batch one night, that is a signal that a model update — or a schema change on my side — has broken an assumption. I route this error to Slack and look at it first thing in the morning. An explicit stop is far easier to work with than data that silently turns murky.

Deciding how far to take it

A word on where to draw the line. My rule is: if a schema has even one optional field, I add both the nullable declaration at the entry and the normalization gate at the exit. The more fields there are, the more the combinations of three shapes multiply, so having one small function like normalizeOptional that every optional field passes through is easier to maintain than patching field by field.

At the same time, if you make an essential field nullable, you hand the model an escape hatch to omit a value. Something like sentiment, which must resolve to exactly one of a few values, stays locked down as enum plus required; only genuinely optional things are left optional. That judgment is what balances stable output against the amount of information you keep.

Three checks before adopting this

Before I add this two-stage setup to a new schema, I run through three checks every time. Most of my rework happened on the nights I skipped them.

1. Is this field genuinely optional? Anything that must resolve to exactly one value stays enum plus required, not nullable. Widening the optional surface too far hands the model an escape hatch to omit values.
2. Is the correct "no value" a null, or a meaningful default? For something like a tag, absence is natural, so null fits; for something like a count, 0 carries meaning, so 0 is the default — the normalization branch should match what the field means.
3. Where does it break downstream? Map the spots that throw on null and the spots that quietly rot on an empty string, then include them in the final assertion. Drawing that map of failure asymmetry first keeps root-cause work short.

Once a field passes these three checks and I wire up the entry and exit, adding more fields later fits the same shape.

I hope this helps anyone whose nightly batch died in the same spot. Thank you for reading.