← Voltar aos guias

Structured Output and JSON Mode: A Practical LLM Guide

Why structured output matters for LLM applications

Large language models are excellent at generating natural language, but applications usually need predictable data. A support-routing tool may need a category and priority. An extraction workflow may need a customer name, invoice total, and date. If the model returns a friendly paragraph instead of machine-readable fields, your code must guess what the answer means.

Structured output asks an LLM to return data in a defined shape, commonly JSON. Instead of accepting any answer, your application defines the fields, types, allowed values, and sometimes validation rules it expects. This makes the response easier to parse, store, display, and pass to downstream services.

JSON mode versus schema-based structured output

JSON mode generally means the provider constrains the response to valid JSON syntax. It solves an important problem: missing quotes, trailing prose, and malformed objects. However, valid JSON alone does not guarantee the right structure. A model could return an array when you expect an object, omit a required property, or provide a string where your code expects a number.

Schema-based structured output adds a contract. You define the expected object, such as ticket_type, urgency, and summary, plus acceptable values. When a provider supports strict schema enforcement, it can ensure the generated data matches that contract more closely than prompt instructions alone.

• Use JSON mode when you need syntactically valid JSON and can validate the result in your application.
• Use schema-based output when a fixed response shape is essential for automation or user-facing workflows.
• Use tool or function calling when the model must select and invoke an action, such as looking up an order or creating a calendar event.

Build a reliable JSON output workflow

First, design a small schema around what your application actually needs. Avoid asking for ten fields when three will do. For example, a product-review classifier could require an object with sentiment, topics, and requires_reply. Restrict sentiment to values such as positive, neutral, or negative.

Second, make the instruction unambiguous. State that the response must contain JSON only, name the required fields, describe each field, and give rules for unknown data. For example: return null for an unavailable order number; do not invent one. Clear handling of absent information prevents plausible but unusable output.

Third, request the provider's JSON mode or structured-output setting through its SDK. With OpenAI-compatible APIs, this typically means setting the response format supported by the selected model. Check the current provider documentation because parameter names and schema support differ by model.

Fourth, validate every response server-side. Parse JSON with a real JSON parser, then validate its structure using your language's schema tooling, such as Zod in TypeScript, Pydantic in Python, or JSON Schema. Even when a model offers strict output, validation protects your application against empty responses, transport errors, model changes, and incorrect assumptions in your own code.

Handle failures without breaking the user experience

Do not send unvalidated model output directly into a database query, payment flow, or external API call. If parsing or validation fails, log the raw response safely, retry once with a concise repair instruction, or fall back to a review queue. Your retry should include the validation error, such as “priority must be one of low, medium, high,” rather than simply asking the model to try again.

Also separate reasoning from production data. Ask the model for only the final structured object when possible. This reduces tokens, lowers parsing risk, and limits accidental exposure of unnecessary generated text.

Use low-cost model access for structured workloads

Classification, extraction, tagging, and routing can involve high request volumes, so token cost matters. 59API is a practical option for these workloads: it provides pay-as-you-go access to native official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, plus GPT models, without a model downgrade. Its OpenAI SDK compatibility means many existing integrations can be pointed at https://api.59api.com by changing the base URL and credentials.

Start with a smaller, lower-cost model for simple extraction and classification, then evaluate accuracy with representative examples. Reserve more capable models for ambiguous documents or complex schemas. This model-routing approach can reduce spend while keeping structured-output quality high. Sign up for 59API when you are ready to test JSON workflows with affordable usage-based access and its available referral rebate.

Preços · Docs