Output Terstruktur LLM: JSON Schema yang Benar-Benar Tervalidasi

Pertama kali sebuah job produksi gagal karena pagar markdown yang tiba-tiba membungkus payload JSON yang sebenarnya sudah sempurna, saya belajar dengan cara yang menyakitkan bahwa meminta model bahasa mengembalikan JSON dengan sopan tidak sama dengan benar-benar menerima JSON yang bisa diparse. Model itu mengikuti instruksi. Ia hanya juga menambahkan satu kalimat ramah sebelum objeknya, karena tidak ada yang benar-benar mencegahnya melakukan itu.

Tulisan ini membahas bagian-bagian yang benar-benar membuat output terstruktur bisa diandalkan: decoding terbatas melalui JSON Schema, memilih antara output JSON langsung dan pemanggilan fungsi berbasis tool, mendeteksi penolakan dan pemotongan respons sebelum keduanya merusak pipeline, serta memvalidasi setiap respons dengan Zod agar pelanggaran skema tidak pernah sampai ke database.

Mengapa sekadar meminta JSON tidak cukup

Rekayasa prompt bisa membawa Anda mendekati hasil yang benar, tetapi mendekati bukan berarti terjamin. Bahkan system prompt yang ditulis rapi dan berisi instruksi untuk hanya merespons dengan JSON valid sesuai bentuk tertentu, sesekali tetap bisa menghasilkan output yang secara teknis memenuhi instruksi namun merusak setiap parser di sisi Anda. Pola kegagalannya cukup dapat diprediksi setelah Anda melihatnya beberapa kali.

• Model membungkus objeknya dalam pagar kode markdown, sehingga panggilan JSON parse yang naif langsung melempar error pada karakter pertama.
• Field yang diwajibkan skema justru diringkas menjadi kalimat prosa dan tidak terisi nilainya, karena model menganggap penjelasan singkat lebih membantu daripada nilai yang ketat.
• Field numerik datang sebagai string yang diberi tanda kutip, atau field enum diisi sinonim yang menurut model setara tetapi tidak dikenali validator Anda.

Semua ini bukan bug pada model. Ini adalah akibat alami dari memperlakukan generator teks probabilistik seolah ia adalah serializer deterministik. Jika sistem Anda bergantung pada bentuk respons, Anda membutuhkan mekanisme yang membatasi proses pembuatannya sendiri, bukan sekadar permintaan yang disusun dengan sopan.

Decoding terbatas: cara kerja output terstruktur sesungguhnya

Decoding terbatas berarti API mengompilasi JSON Schema Anda menjadi sebuah grammar dan membatasi token mana yang boleh dikeluarkan model pada setiap langkah pembuatan teks. Jika skema Anda menyatakan sebuah field harus salah satu dari tiga nilai enum, model secara mekanis dicegah menghasilkan nilai keempat. Ini diberlakukan pada lapisan sampling, bukan melalui validasi setelah fakta, sehingga tidak ada jendela waktu di mana model bisa saja mengeluarkan sesuatu yang lain lalu lolos dari pemeriksaan yang longgar.

import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

const InvoiceLine = z.object({
  sku: z.string(),
  quantity: z.number().int().positive(),
  unitPriceCents: z.number().int().nonnegative(),
});

const InvoiceExtraction = z.object({
  vendorName: z.string(),
  invoiceNumber: z.string(),
  lines: z.array(InvoiceLine),
  totalCents: z.number().int().nonnegative(),
});

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: rawInvoiceText }],
  output_config: { format: zodOutputFormat(InvoiceExtraction) },
});

Claude menyediakan ini melalui dua mekanisme yang saling melengkapi: format output JSON yang dilampirkan pada permintaan pesan, dan strict tool use di mana skema input sebuah tool diberlakukan dengan cara yang sama. Fitur setara di OpenAI adalah flag strict pada response_format bertipe json_schema, yang datang dengan aturan tegas: setiap properti harus dicantumkan sebagai required, dan additionalProperties harus secara eksplisit diset ke false. Anda tidak bisa begitu saja menghilangkan sebuah field opsional dari daftar required seperti pada JSON Schema buatan sendiri; cara idiomatik untuk mengatasinya adalah membuat tipe field tersebut nullable.

Memilih antara mode output JSON dan pemanggilan tool

Kedua penyedia memberi Anda dua bentuk untuk jaminan yang sama, dan pilihan yang tepat bergantung pada apa yang direpresentasikan oleh respons dalam aplikasi Anda, bukan pada bentuk mana yang terasa lebih familiar.

Menangani penolakan dan pemotongan respons dengan baik

Batasan skema menjamin bentuk dari respons yang selesai. Ia tidak menjamin apakah respons itu benar-benar selesai, atau apakah model justru menolak menjawab sama sekali. Kedua penyedia memberi Anda sinyal untuk ini, dan mengabaikannya adalah cara paling umum output yang sudah dibatasi skema tetap bisa gagal di produksi.

1. Periksa field stop reason atau finish reason sebelum Anda mencoba memparsing apa pun. Penolakan atau pemotongan karena panjang berarti tidak ada payload valid sesuai skema yang bisa diekstraksi, seberapa pun cermat Anda menulis skemanya.
2. Saat terjadi penolakan, tampilkan error yang jelas dan spesifik ke pemanggil, bukan mencoba menyelamatkan teks parsial. OpenAI mengembalikan field refusal khusus untuk kasus ini, dan Claude melaporkan stop reason berupa refusal.
3. Saat terjadi pemotongan, artinya respons mencapai batas token maksimum di tengah objek, jangan coba memperbaiki JSON secara manual. Coba lagi dengan batas token yang lebih tinggi atau skema yang lebih sempit yang meminta lebih sedikit sekaligus.
4. Catat teks respons mentah pada setiap stop reason yang bukan sukses sebelum Anda membuangnya. Saat pertama kali skema yang Anda kira sudah rapat tetap menghasilkan array yang terpotong, Anda akan membutuhkan payload itu untuk debugging.

Validasi setiap respons dengan Zod sebelum menyentuh database Anda

Pembuatan yang dibatasi skema membuat JSON yang cacat jarang terjadi, bukan mustahil, dan itu tidak menjamin apakah nilai-nilainya memang yang Anda inginkan. Model bisa mengembalikan objek yang secara sintaksis sempurna dengan jumlah bernilai negatif atau nomor invoice yang sebenarnya adalah nama pelanggan. Perlakukan respons yang sudah dibatasi skema sama seperti input eksternal lainnya: parsing dulu, lalu validasi dengan pustaka skema sungguhan sebelum menyentuh proses penyimpanan.

const parsed = InvoiceExtraction.safeParse(
  JSON.parse(response.content[0].text)
);

if (!parsed.success) {
  logger.warn("schema_validation_failed", {
    issues: parsed.error.issues,
  });
  throw new ExtractionValidationError(parsed.error);
}

// parsed.data is now fully typed and safe to persist
await saveInvoice(parsed.data);

Menjalankan bentuk yang sama melalui safeParse milik Zod memberi Anda dua hal yang tidak bisa diberikan oleh JSON parse mentah: objek bertipe yang bisa dipercaya oleh kode TypeScript Anda di tahap selanjutnya, dan array masalah terstruktur yang bisa Anda catat atau kembalikan ke pemanggil, bukan sekadar exception parsing yang generik. Jika Anda sudah menggunakan skema Zod untuk membangun JSON Schema yang dikirim ke model, seperti pada contoh sebelumnya, langkah validasi ini hampir gratis karena definisi skema yang sama dipakai dua kali.

Saat output yang dibatasi skema saja tidak cukup

JSON Schema dan Zod keduanya memvalidasi bentuk dan tipe dari satu respons. Tidak ada satu pun yang bisa menyatakan relasi antar-field yang hanya bermakna bila digabungkan, atau fakta yang hidup di luar respons itu sendiri. Rencanakan tahap validasi kedua untuk kasus-kasus seperti ini.

• Aturan bisnis yang melibatkan beberapa field sekaligus, seperti tanggal akhir yang harus jatuh setelah tanggal mulai, yang membutuhkan fungsi refine khusus dan bukan skema biasa.
• Pemeriksaan lintas-data, seperti memastikan sebuah ID order yang dirujuk benar-benar ada di database Anda, yang hanya bisa dijawab oleh pencarian sungguhan.
• Rentang numerik yang spesifik pada domain Anda, seperti tarif pajak yang secara struktural adalah angka valid tetapi tidak masuk akal di atas ambang tertentu untuk bisnis Anda.