Output Terstruktur LLM yang Rusak: Cara Sebenarnya Menulis Schema untuk Mode strict
Intinya: Mengaktifkan strict pada JSON Schema apa pun hampir selalu mengembalikan 400: semua field required, additionalProperties:false di setiap objek, dan $ref serta allOf langsung ditolak. Panduan ini menunjukkan cara menulis ulang schema longgar menjadi versi kompatibel strict — dengan union nullable, batas keras, dan checklist refusal.

Intinya: strict: true bukan sakelar "harus lebih serius" — itu kontrak yang hanya menerima sebagian kecil dari JSON Schema. Semua field required, additionalProperties: false di setiap objek, $ref dan allOf langsung dilarang. Kirim schema ke mode strict tanpa menulis ulang, jawabannya adalah 400, bukan output yang andal.
Dalam praktik sehari-hari, adegan ini berulang persis sama: tim punya schema yang dirancang baik, dengan field opsional, $defs yang bisa dipakai ulang, dan additionalProperties yang terbuka demi kompatibilitas. Lalu seseorang menambahkan "strict": true ke panggilan API, yakin bahwa model kini "akan menghormati" schema. Hasil seketika adalah error 400 dengan pesan panjang, atau lebih buruk — schema diterima tetapi menghasilkan output yang tak terduga. Mode strict tidak menafsirkan schema dengan toleransi: ia menulis ulang schema dari nol menjadi tata bahasa yang bisa diikuti mesin generasi secara harfiah, dan segala hal yang tidak muat dalam tata bahasa itu ditolak atau diam-diam diabaikan. Memahami aturan mana yang benar-benar berlaku, sebelum mengirim permintaan, adalah perbedaan antara pipeline yang stabil dan seminggu debugging.
Mode strict = JSON Schema Anda dikompilasi menjadi tata bahasa yang harus diikuti model kata demi kata. Segala hal yang tak bisa diekspresikan tata bahasa ditolak saat pengiriman atau diam-diam diabaikan — dan dalam kedua kasus, masalah muncul setelah pengguna sudah melihatnya.
Cara mesin mode strict benar-benar bekerja
Model tidak membaca JSON Schema Anda seperti validator biasa. Ketika strict: true aktif, schema diubah menjadi tata bahasa terbatas — automaton status hingga yang memutuskan token demi token kelanjutan mana yang legal. Model hanya menghasilkan transisi yang diizinkan automaton; tidak ada kontrol pasca-generasi yang memperbaiki output — kebenarannya bersifat struktural.
Arsitektur ini menjelaskan semua perilaku yang tampak misterius. Jika sebuah field tidak termasuk dalam required, automaton harus memutuskan kapan berhenti: satu-satunya solusi aman adalah memberi model kebebasan mengeluarkan null, sehingga schema efektif yang diterima mesin akan selalu memuat field itu. Jika sebuah objek mengizinkan properti tambahan, automaton tak bisa memprediksi kunci apa yang akan muncul, jadi setiap objek harus ditutup secara kaku. Setiap "terlarang" dalam dokumentasi lahir dari batasan konkret automaton ini, bukan pilihan gaya OpenAI.
Konsekuensi kedua lebih berbahaya: beberapa kata kunci JSON Schema (seperti pattern, minLength, maximum) valid untuk schema tetapi tidak ditegakkan oleh tata bahasa. Schema diterima, respons datang bersih, tetapi kendala tidak pernah dipatuhi. Ini cara paling senyap merusak pipeline: validasi berikutnya gagal di produksi dan tidak ada log yang menunjukkan error schema.
Tiga aturan yang tidak bisa dinegosiasikan
Jika Anda hanya punya waktu memperbaiki satu hal, perbaiki tiga ini. Mereka menyelesaikan mayoritas kasus 400.
1. Semua field dalam required, selalu. Dalam mode strict, setiap kunci yang dideklarasikan di properties harus muncul di required — termasuk yang opsional. Trik resmi untuk menyatakan "opsional" adalah union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Dengan begitu automaton tahu tepat kapan kunci itu legal, dan model menyatakan "tidak ada kupon" dengan null alih-alih menghilangkan kunci.
2. additionalProperties: false di setiap objek. Bukan hanya di objek akar: setiap objek bersarang, tanpa pengecualian. Satu tingkat terbuka saja membuat seluruh schema tidak mematuhi.
3. $ref dan allOf dilarang. Tanpa referensi, tanpa $defs, tanpa komposisi. Schema harus sepenuhnya diperluas — satu pohon tunggal yang berdiri sendiri. if/then/else dan oneOf di akar menerima nasib yang sama.
Tabel istilah terlarang dan yang tidak berdaya
| Kata kunci | Hasil dalam mode strict | Pengganti yang disarankan |
|---|---|---|
$ref, $defs |
Ditolak dengan 400 | Ekspansi penuh schema |
allOf |
Ditolak dengan 400 | Penggabungan properti manual |
if/then/else |
Ditolak dengan 400 | enum + penanganan sisi klien |
oneOf di akar |
Masalah / respons tidak mematuhi | Hanya satu objek akar |
Field di luar required |
Berubah menjadi selalu wajib | Union nullable ["string", "null"] |
pattern, minLength |
Schema diterima tetapi kendala diabaikan | Validasi eksplisit setelah respons |
maximum, format |
Schema diterima tetapi kendala diabaikan | Verifikasi sisi aplikasi |
Baris paling berbahaya adalah pasangan terakhir: schema lulus validasi tetapi kendalanya tidak ada. Jika logika Anda memercayai pattern, Anda membangun di atas pasir.
Batas keras yang tak pernah dibaca siapa pun
Sebelum menulis schema, pastikan Anda berada di dalam batas ini — melampauinya menghasilkan error generik yang sulit didiagnosis:
| Kendala | Maksimum |
|---|---|
| Total properti per schema | 5000 |
| Kedalaman nesting | 10 tingkat |
| Ukuran string schema | 120.000 karakter |
| Total nilai enum | 1000 |
Schema yang dihasilkan otomatis dari framework atau definisi OpenAPI sering melewati batas ini tanpa disadari: total 6000 properti, 12 tingkat nesting, 1500 nilai enum berserakan. Pesan error API jarang menunjukkan ambang mana yang terlampaui, jadi sebaiknya periksa sendiri sebelum pengiriman.
Penulisan ulang otomatis: skrip make_strict
Untuk schema besar, penulisan ulang manual tidak praktis. Skrip Python ini menelusuri pohon dan menerapkan tiga aturan secara rekursif:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# setiap properti menjadi required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# field "opsional" harus Anda tandai nullable terlebih dahulu
# buang hal yang tidak diterima strict
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Dua peringatan. Pertama: skrip tidak menebak field mana yang opsional — Anda harus menandai union nullable sendiri, sebaiknya di sumber schema, bukan di hasilnya. Kedua: setelah transformasi, selalu jalankan permintaan uji: ekspansi bisa melewati batas ukuran atau jumlah properti yang sebelumnya Anda patuhi.
Jalur setara di Anthropic
Anthropic tidak menyediakan flag strict, tetapi mencapai hasil yang sama melalui mekanisme tool: definisi alat berperan sebagai schema, dan model terikat pada bentuknya. Pendekatannya praktis identik:
const tool = {
name: "extract_invoice",
description: "Mengekstrak data faktur dari teks",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// model merespons dengan panggilan tool yang mematuhi
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
Aturan praktisnya sama: di Anthropic pun, setiap objek membutuhkan required lengkap dan additionalProperties: false. Perbedaannya ada di kanal respons — tool_use alih-alih konten teks — dan pada kenyataan bahwa field refusal khusus OpenAI.
Refusal, pemotongan, dan bentuk rusak: tiga kerusakan, tiga obat
Bahkan dengan schema sempurna, output bisa gagal karena tiga sebab yang berbeda, dan mencampuradukkannya adalah cara tercepat menghilangkan sehari:
1. refusal tidak kosong. OpenAI dalam mode strict bisa mengembalikan field refusal beserta alasan permintaan ditolak. Ini bukan error schema — model menolak tugas secara semantik. Obatnya adalah meninjau ulang prompt atau kebijakan, bukan schema.
2. Pemotongan karena max_tokens. Generasi terputus di tengah string dan JSON tidak tertutup. Dalam mode strict, respons yang datang mematuhi schema — tetapi jika anggaran token habis, ia datang terpotong. Naikkan max_tokens atau kurangi ukuran output yang diharapkan. Untuk skenario berulang, perbaikan otomatis JSON terpotong punya pola siap pakai.
3. Bentuk rusak yang tidak mematuhi. Schema terbuka (properti tambahan diizinkan, field di luar required) dan strict tidak diaktifkan: model menghasilkan JSON valid yang tidak mematuhi kontrak. Obatnya adalah menulis ulang schema seperti dalam panduan ini, bukan menambah kontrol pasca-generasi.
Diagnosis yang benar selalu dimulai dari membedakan tiga kasus ini: lihat field finish_reason, keberadaan refusal, dan bandingkan respons dengan schema yang benar-benar dikirim.
Checklist akhir sebelum masuk produksi
| Titik pemeriksaan | Apa yang dicek |
|---|---|
required lengkap |
Setiap properti yang dideklarasikan ada di required |
| Nullable eksplisit | Field opsional berupa union ["...", "null"] |
additionalProperties: false |
Di setiap objek, bukan hanya akar |
Nol $ref / allOf / if-then-else |
Schema diperluas sepenuhnya |
| Batas dipatuhi | ≤ 5000 properti, ≤ 10 tingkat, ≤ 120k karakter |
| Kendala tak berdaya dipindahkan | pattern/format diverifikasi sisi aplikasi |
Penanganan refusal |
Kode membedakan penolakan dari error schema |
| Uji dengan permintaan nyata | Respons uji telah divalidasi sebelum deploy |
Jika Anda ingin memahami mengapa additionalProperties: false begitu sentral, analisis mendalam tentang kata kunci additionalProperties menunjukkan bagaimana setiap objek terbuka memperluas ruang generasi. Untuk memasukkan schema ke pipeline CI dengan uji kontrak otomatis, alur yang dijelaskan dalam JSON Schema contract testing menutup regresi senyap. Dan jika Anda perlu membangun schema dari contoh JSON yang ada, alat konversi ke JSON Schema di platform membantu Anda mulai dari data nyata — meski demikian, untuk mode strict Anda tetap perlu menerapkan penulisan ulang dari panduan ini.
FAQ
Mengapa dokumentasi mensyaratkan semua field required, termasuk yang opsional?
Karena automaton status hingga harus memutuskan lebih dulu kapan setiap kunci legal. "Opsional" diekspresikan dengan null, bukan dengan ketiadaan kunci: union nullable adalah cara resmi menyatakannya.
Schema diterima tetapi pattern tidak berfungsi. Ini bug?
Bukan. Dalam mode strict, pattern, minLength, maximum, dan format tidak ditegakkan oleh tata bahasa generasi. Schema valid secara sintaksis tetapi kendalanya tidak ada: verifikasi di sisi aplikasi.
Bolehkah saya memakai $ref jika juga mendeklarasikan $defs?
Tidak, keduanya dilarang. Schema harus berupa satu pohon tunggal, sepenuhnya diperluas. Skrip penulisan ulang otomatis menangani ekspansinya.
Apa perbedaan antara refusal dan error schema? Refusal adalah respons yang mematuhi di mana model menyatakan secara semantik bahwa ia tidak ingin melakukan tugas. Error schema adalah 400 saat pengiriman atau output yang tidak mematuhi. Dua masalah berbeda dengan dua obat berbeda.
Seberapa dalam saya bisa menumpuk objek? Maksimal 10 tingkat nesting dan total 5000 properti per schema. Schema yang dihasilkan otomatis sering melewati batas ini: periksa sebelum pengiriman.
Kesimpulan
Mode strict bukan opsi kosmetik: ini adalah lompatan dari "berharap model menghormati schema" ke "tata bahasa secara fisik mencegah output yang tidak mematuhi". Harganya adalah subset JSON Schema yang kaku — required lengkap, objek tertutup, tanpa referensi — dan beberapa kendala yang lolos tanpa perhatian tetapi tidak ditegakkan. Sisihkan setengah jam untuk menulis ulang dengan skrip make_strict, tandai union nullable secara sengaja, dan selalu uji dengan permintaan nyata sebelum deploy: pipeline yang dihasilkan secara kualitatif berbeda dari yang dibangun di atas retry dan perbaikan setelah kejadian.