structured output の任意フィールドが null・空文字・キー欠落で三様にぶれる — 正規化ゲートで一つの表現に畳む

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 },
    // 任意フィールドは required に入れつつ nullable で「値なし=null」を一意に決める
    suggested_tag: { type: Type.STRING, nullable: true },
    reason: { type: Type.STRING, nullable: true },
  },
  // 全フィールドを required に。存在は保証し、無い値は 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,
  },
});

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; // 値が無い場合は必ず null に統一
  reason: string | null;
};
 
// 三態を一態へ畳む中心の関数
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),
  };
}

function assertClean(r: CleanReview, sourceId: string): CleanReview {
  // null は許容するが、undefined・空文字・空白のみは「畳み残し」なので即エラー
  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;
}