---
title: "JSON mode vs JSON schema untuk output terstruktur | BroadRouter"
description: "JSON mode memberi JSON valid; json_schema memberi bentuk Anda. Cara memintanya di model kompatibel OpenAI, validasi dengan Pydantic, dan perbaiki output buruk."
url: https://broadrouter.com/id/blog/structured-output-json-schema/
lang: id
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Diterjemahkan dari bahasa Inggris dengan bantuan AI. [Baca versi asli bahasa Inggris](https://broadrouter.com/blog/structured-output-json-schema/) (diperbarui 2026-11-14).

# JSON mode vs json\_schema: output terstruktur yang andal

Oleh tim BroadNet Inference · 4 menit baca · Dipublikasikan 2026-11-14

JSON mode (response\_format json\_object) hanya menjanjikan JSON yang valid. Output terstruktur (response\_format json\_schema) juga menjanjikan field dan tipe data Anda, sejauh penyedia menegakkannya. Apa pun pilihannya, cek finish\_reason, parse hasilnya, lalu validasi terhadap skema seperti model Pydantic. Jika validasi gagal, kirim error-nya kembali dan minta ulang, dengan batas percobaan yang tegas.

## Poin penting

-   Panduan OpenAI: kedua mode menghasilkan JSON valid, tetapi "only Structured Outputs ensure schema adherence" (Terjemahan BroadRouter: "hanya Structured Outputs yang menjamin kepatuhan pada skema").
-   Dukungan berbeda-beda di antara penyedia yang kompatibel OpenAI. Uji json\_schema dulu, lalu mundur ke json\_object, lalu ke prompt saja.
-   Validasi setiap balasan. Balasan yang terpotong oleh max\_tokens adalah JSON rusak, apa pun kata skemanya.
-   Loop perbaikan berhasil jika Anda mengirim kembali error validasi yang persis. Batasi dua atau tiga percobaan.
-   Di BroadNet Inference, GLM 5.3 dan Qwen3.8 27B tercantum mendukung output terstruktur.

**Di halaman ini**

1.  Apa beda JSON mode dan json\_schema?
2.  Bagaimana cara meminta json\_schema?
3.  Mode mana yang didukung penyedia Anda?
4.  Bagaimana memvalidasi dan memperbaiki output yang buruk?
5.  Fitur skema apa yang sering bermasalah?
6.  Bagaimana memantau output terstruktur di produksi?
7.  Kapan sebaiknya memakai tool?
8.  Posisi BroadNet Inference

Kode Anda butuh data, sedangkan model menulis teks. [Output terstruktur](https://broadrouter.com/id/glossary/structured-output/) menjembatani celah itu, tetapi “model mengembalikan JSON” bisa berarti tiga hal berbeda tergantung cara Anda memintanya. Artikel ini membandingkan opsinya di model open yang kompatibel OpenAI, menunjukkan cara meminta masing-masing, dan memberi loop validasi-dan-perbaikan yang bisa langsung Anda pasang di produksi.

## Apa beda JSON mode dan json\_schema?

| Metode | Permintaan | Yang dijanjikan |
| --- | --- | --- |
| Prompt saja | “Balas dalam JSON dengan field…” | Tidak ada; biasanya JSON, kadang dengan teks tambahan |
| JSON mode | `response_format: {"type": "json_object"}` | JSON valid, bentuk apa pun |
| Output terstruktur | `response_format: {"type": "json_schema", ...}` | JSON yang sesuai skema Anda, jika ditegakkan |

Panduan Structured Outputs OpenAI mengatakannya terus terang: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (Terjemahan BroadRouter: “Meski keduanya memastikan JSON yang dihasilkan valid, hanya Structured Outputs yang menjamin kepatuhan pada skema.”) Panduan itu merekomendasikan output terstruktur dibanding JSON mode bila memungkinkan.

Di penyedia model open, jaminannya bergantung pada cara server mengimplementasikannya. Banyak yang memakai constrained decoding, yang memblokir token yang akan merusak skema. Ada juga yang menerima field-nya tetapi tidak menegakkannya. Itulah sebabnya kode di bawah tetap melakukan validasi.

## Bagaimana cara meminta json\_schema?

```python
import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}
```

Pydantic menghasilkan JSON Schema dari class Anda, sehingga skema dan validatornya tidak pernah selisih. Jika Anda tidak memakai Pydantic, [generator JSON schema](https://broadrouter.com/tools/json-schema-generator/) membuat skema mode strict dari objek contoh. Untuk mode strict, OpenAI mewajibkan `additionalProperties: false` dan setiap properti dicantumkan sebagai required.

## Mode mana yang didukung penyedia Anda?

Jalankan uji ini sekali per model sebelum membangun sesuatu di atasnya:

1.  Kirim `json_schema` dengan prompt yang memancing field ekstra (“tambahkan juga komentar singkat”).
2.  Jika permintaan error, penyedia tidak menerima `json_schema`. Coba `json_object`.
3.  Jika balasannya berisi field ekstra itu, skema tidak ditegakkan. Perlakukan sebagai JSON mode.
4.  Jika `json_object` juga error, pakai prompt saja dengan validasi.

Di BroadNet Inference, dokumentasinya mencantumkan output terstruktur untuk [GLM 5.3](https://broadrouter.com/id/models/glm-5.3/) dan [Qwen3.8 27B](https://broadrouter.com/id/models/qwen3.8-27b/) ([perbandingan berdampingan](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)), tetapi tidak menyebut nama parameter permintaannya. Jalankan uji di atas pada model yang akan Anda rilis.

## Bagaimana memvalidasi dan memperbaiki output yang buruk?

```python
import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")
```

Yang membuat loop ini berhasil:

-   **Cek `finish_reason` lebih dulu.** Balasan yang menyentuh [`max_tokens`](https://broadrouter.com/id/glossary/max-tokens/) adalah JSON yang terpotong. Mencoba ulang dengan batas yang sama akan gagal dengan cara yang sama. Kedua model di atas melakukan penalaran sebelum menjawab, dan [penalaran ikut dihitung dalam batas itu](https://broadrouter.com/id/guides/reasoning-tokens-empty-response/), jadi sisakan ruang.
-   **Tangani penolakan secara terpisah.** Panduan OpenAI mencatat bahwa penolakan “does not necessarily follow the schema you have supplied” (Terjemahan BroadRouter: “belum tentu mengikuti skema yang Anda berikan”).
-   **Kirim kembali error yang persis.** Retry buta sering mengembalikan kesalahan yang sama. “line\_items: field required” memberi model sesuatu yang konkret untuk diperbaiki.
-   **Cek aturan bisnis di kode.** Skema tidak bisa menyatakan bahwa total harus sama dengan jumlah rinciannya. Pengecekan di atas bisa.
-   **Batasi percobaan.** Setiap percobaan mengirim ulang seluruh prompt sebagai [token input](https://broadrouter.com/id/glossary/input-and-output-tokens/).

## Fitur skema apa yang sering bermasalah?

Buat skema sesederhana mungkin:

1.  **Datar lebih baik daripada bersarang.** Dua level sudah lebih dari cukup untuk sebagian besar ekstraksi.
2.  **Enum alih-alih string bebas** untuk kategori.
3.  **Hindari objek terbuka.** Field `dict` berbentuk bebas menghilangkan manfaatnya.
4.  **Nama field pendek dengan deskripsi.** Deskripsi di skema memandu model.
5.  **Field opsional dibuat nullable.** Di mode strict, cantumkan setiap field sebagai required dan izinkan `null`.

Panduan OpenAI mencatat beberapa fitur JSON Schema tidak didukung di mode strict. Server model open juga punya batasannya sendiri. Jika skema ditolak, sederhanakan dulu sebelum mengganti mode.

## Bagaimana memantau output terstruktur di produksi?

Loop yang memperbaiki diam-diam bisa menyembunyikan masalah yang setiap hari menghabiskan token Anda. Catat tiga angka per titik pemanggilan:

| Metrik | Yang ditunjukkannya |
| --- | --- |
| Tingkat keberhasilan percobaan pertama | Seberapa cocok model dan skema; penurunan sering terjadi setelah perubahan prompt atau model |
| Rata-rata percobaan per keberhasilan | Biaya token dari perbaikan |
| Kegagalan akhir | Input yang tidak bisa ditangani pipeline Anda; tinjau secara manual |

Jika keberhasilan percobaan pertama turun di bawah biasanya, sederhanakan skema atau coba model lain sebelum menambah retry. Simpan sampel balasan mentah yang gagal agar Anda bisa menguji perbaikan pada kasus nyata.

## Kapan sebaiknya memakai tool?

Pakai output terstruktur untuk **jawaban akhir**: ekstraksi, klasifikasi, rencana. Pakai [tool calling](https://broadrouter.com/id/blog/tool-calling-open-models/) saat model perlu kode Anda **melakukan** sesuatu lalu melanjutkan. Banyak agen memakai keduanya: tools selama loop, skema untuk langkah terakhir. Untuk contoh gambar-ke-JSON, lihat [membaca faktur bahasa Arab dengan model vision](https://broadrouter.com/id/guides/read-arabic-invoices-with-vision/).

## Posisi BroadNet Inference

BroadNet Inference mencantumkan output terstruktur untuk GLM 5.3 dan Qwen3.8 27B, di balik format chat completions standar, sehingga kode di atas berjalan dengan [SDK Python OpenAI](https://broadrouter.com/id/guides/openai-python-sdk/) tanpa perubahan. Qwen3.8 27B juga menerima gambar, cocok untuk ekstraksi dokumen. Dokumentasi BroadNet tidak menyebut output terstruktur untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi di sana pakai jalur prompt saja dengan validasi. Bandingkan harga per token di [halaman harga](https://broadrouter.com/id/pricing/).

Alat gratis untuk topik ini (bahasa Inggris)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Alat gratis (bahasa Inggris)](https://broadrouter.com/tools/)

## Istilah dalam artikel ini

[Output terstruktur (structured output)](https://broadrouter.com/id/glossary/structured-output/)

Output terstruktur adalah fitur API LLM yang membatasi balasan model pada format yang ditentukan developer, biasanya JSON Schema, agar kode bisa mem-parse-nya dengan andal. Fitur ini lebih ketat daripada JSON mode, yang menjamin JSON valid tetapi tidak menjamin bentuk tertentu.

[JSON Schema (skema JSON)](https://broadrouter.com/id/glossary/json-schema/)

JSON Schema adalah kosakata yang ditulis dalam JSON untuk mendeskripsikan dan memvalidasi struktur data JSON: tipe, field wajib, nilai yang diizinkan, dan susunan bertingkat. Versi terbarunya 2020-12. API LLM memakainya untuk mendefinisikan parameter tool dan bentuk persis yang harus diikuti output terstruktur.

[Token](https://broadrouter.com/id/glossary/token/)

Token adalah satuan teks yang dibaca dan ditulis model bahasa: sebuah kata, bagian kata, tanda baca, atau urutan byte yang dihasilkan tokenizer model. API LLM menghitung, membatasi, dan biasanya menagih pemakaian dalam token.

[JSON mode (mode JSON)](https://broadrouter.com/id/glossary/json-mode/)

JSON mode adalah pengaturan API LLM, yaitu response\_format {"type": "json\_object"} di API bergaya OpenAI, yang membuat balasan model berupa JSON yang valid dan bisa di-parse. Berbeda dengan structured outputs yang memakai JSON Schema, mode ini tidak menjamin key, tipe, atau nilai apa yang ada di objek.

[Tool calling (function calling)](https://broadrouter.com/id/glossary/tool-calling/)

Tool calling, disebut juga function calling, adalah fitur API LLM di mana model mengembalikan permintaan terstruktur untuk menjalankan fungsi yang didefinisikan developer, lengkap dengan argumen JSON. Aplikasi yang menjalankan fungsi itu dan mengirim hasilnya kembali; model tidak pernah menjalankan kode sendiri.

[Chat Completions API](https://broadrouter.com/id/glossary/chat-completions-api/)

Chat Completions API adalah endpoint HTTP milik OpenAI, POST /v1/chat/completions, yang menerima nama model dan daftar pesan bertanda peran lalu mengembalikan pesan berikutnya dari model. Bentuk request dan response-nya menjadi format umum yang dipakai ulang oleh penyedia dan SDK yang kompatibel dengan OpenAI.

[Token input dan output](https://broadrouter.com/id/glossary/input-and-output-tokens/)

Token input adalah token yang dibaca model bahasa dalam sebuah permintaan, termasuk system prompt, riwayat percakapan, definisi tool, dan gambar. Token output adalah token yang dihasilkannya sebagai balasan, termasuk penalaran. API LLM biasanya menghargainya secara terpisah, dan output biasanya lebih mahal.

[Vision-language model (VLM)](https://broadrouter.com/id/glossary/vision-language-model/)

Vision-language model (VLM) adalah model yang menerima gambar dan teks sekaligus sebagai input dan menghasilkan teks, sehingga bisa mendeskripsikan gambar, menjawab pertanyaan tentangnya, serta membaca dokumen, grafik, atau screenshot. VLM juga disebut model image-text-to-text atau model multimodal.

## Pertanyaan umum

### Apa beda JSON mode dan output terstruktur?

JSON mode, response\_format tipe json\_object, hanya menjanjikan balasan bisa di-parse sebagai JSON. Output terstruktur, tipe json\_schema, juga menjanjikan field dan tipe yang Anda definisikan, sejauh penyedia menegakkannya. OpenAI merekomendasikan output terstruktur dibanding JSON mode bila memungkinkan.

### Apakah model open mendukung response\_format json\_schema?

Tergantung penyedianya. Ada yang menerima json\_schema, ada yang hanya json\_object, dan ada yang mengabaikan field itu. Kirim permintaan uji dengan skema dan prompt yang memancing model menambahkan field ekstra, lalu cek balasannya.

### Apakah output terstruktur masih perlu divalidasi?

Ya. Balasan bisa terpotong oleh max\_tokens, bisa berupa penolakan, dan bisa melanggar aturan bisnis yang tidak bisa diekspresikan skema, misalnya total yang harus pas dengan jumlah rinciannya.

### Berapa kali JSON yang tidak valid sebaiknya dicoba ulang?

Dua atau tiga percobaan dengan menyertakan error validasinya biasanya cukup. Setelah itu, catat input-nya dan arahkan ke jalur cadangan, model yang lebih kuat, atau manusia. Loop tanpa batas membuang token.

### Sebaiknya pakai output terstruktur atau tool calling?

Pakai output terstruktur jika Anda ingin jawaban akhir dalam bentuk yang tetap. Pakai tool calling jika model perlu kode Anda melakukan sesuatu lalu melanjutkan.

## Baca juga

-   [Klasifikasi teks bahasa Arab dengan LLM: sentimen, intent, triase](https://broadrouter.com/id/blog/arabic-text-classification-llm/)
-   [Tool calling dengan model terbuka: skema, panggilan paralel, retry](https://broadrouter.com/id/blog/tool-calling-open-models/)
-   [Pindah ke API kompatibel OpenAI: checklist migrasi](https://broadrouter.com/id/blog/openai-compatible-api-migration-checklist/)
-   [AI Agent n8n dengan LLM murah: setup, pilihan model, biaya per run](https://broadrouter.com/id/blog/n8n-ai-agent-cheap-llm/)
-   [Cara memperbaiki JSON tidak valid dari LLM: penyebab, perbaikan, retry](https://broadrouter.com/id/blog/fix-invalid-json-from-llm/)
-   [Ekstraksi entitas bernama bahasa Arab dengan LLM: JSON, tanggal, cek](https://broadrouter.com/id/blog/arabic-named-entity-extraction-llm/)
-   [Hardware GPU dan pendekatan serving BroadNet, menurut BroadNet](https://broadrouter.com/id/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache respons API LLM untuk memangkas biaya: exact cache di Python](https://broadrouter.com/id/blog/cache-llm-responses-cut-cost/)
-   [Panduan: Memakai OpenAI Python SDK dengan BroadNet Inference](https://broadrouter.com/id/guides/openai-python-sdk/)
-   [Panduan: Membaca faktur dan struk berbahasa Arab dengan model vision](https://broadrouter.com/id/guides/read-arabic-invoices-with-vision/)
-   [Panduan: Kenapa model reasoning mengembalikan jawaban kosong](https://broadrouter.com/id/guides/reasoning-tokens-empty-response/)

Coba dengan beban kerja Anda yang sebenarnya. Akun baru mendapat kredit US$5 untuk Gemma dan transkripsi. DeepSeek, GLM, dan Qwen3.8 memerlukan top up.

[Mulai](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=id-blog-structured-output-json-schema&utm_content=page-cta) ·

**Sumber**

-   [OpenAI, panduan Structured Outputs (dicek 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [Referensi API OpenAI, membuat chat completion (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Dokumentasi Pydantic, JSON Schema dan validasi](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [Referensi API BroadNet Inference, model (bahasa Inggris)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=id-blog-structured-output-json-schema&utm_content=sources#models)
