JSON Toolkit

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.

Menengah±8 menit bacaDiterbitkan 2026-11-19Diperbarui 2026-11-19
Diagram aturan penulisan ulang JSON Schema untuk mode strict LLM

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.

Referensi

Artikel terkait

Pengujian Kontrak JSON Schema: Las Aturan Validasi ke Dalam CI

Skema tidak berakhir saat ditulis — di situlah degradasi dimulai. Satu salah ketik diam-diam melonggarkan validasi, satu refaktoring memecahkan semua fixture. Panduan ini membedah susunan pengujian kontrak yang bisa dilaksanakan: fixture positif, negatif dan snapshot, lint skema itu sendiri, kompilasi sekali dengan penggunaan ulang, dan empat gerbang CI yang mengubah pecahnya kontrak menjadi build merah.

Menengah±8 menit bacaDiperbarui 2026-11-05

JSON dari LLM terpotong: lihat alasan berhentinya dulu, baru bicara perbaikan

Model mengembalikan JSON yang putus di tengah nilai dan parser hanya memberi nomor kolom. Menutup kurung membuatnya bisa di-parse lagi, tetapi setiap field yang hilang kini tersembunyi di dalam data. Artikel ini menetapkan batas antara apa yang bisa dipulihkan perbaikan pemotongan secara jujur dan apa yang harus diminta ulang.

Praktis±5 menit bacaDiperbarui 2026-11-14

Tanpa additionalProperties, validasi skema tidak memvalidasi apa pun

Validasi yang lulus bukan berarti data bersih. Pydantic secara bawaan mengabaikan kolom tak dikenal, Zod menghapusnya, Ajv membiarkannya — parameter halusinasi dan kunci salah ketik lolos tanpa suara. Artikel ini menunjukkan tiga bentuk penerimaan diam dan memberikan resep lengkap: menutup objek, mengontrol koersi, mengencangkan setiap tingkat sarang.

Intermediate±8 menit bacaDiperbarui 2026-11-02