Strict JSON or free text: which AI output format makes integrations reliable?
A reliable integration depends on more than model quality. It needs an output contract, syntax validation and business checks before any result is stored or acted on.
Short answer
Choose free text when a person will read the answer and no system needs to interpret it automatically. Use JSON Schema to extract, classify or transmit data with a verifiable structure. Use a tool call when the output needs to request an authorised action. In every case, validate values, permissions and side effects: schema-conforming output is not automatically true, safe or relevant.
Providers do not promise exactly the same capability. OpenAI and Azure distinguish JSON mode, which produces valid JSON, from Structured Outputs that follow a supported subset of JSON Schema with a strict option. Google also documents a JSON Schema subset and recommends business-level validation. Anthropic describes tool calls with an input_schema, and its strict tool-use mode checks that calls match the supplied schema (OpenAI Structured Outputs, Microsoft Azure Structured Outputs, Google Gemini Structured Outputs, Anthropic Tool Use).
Nexxom diagram: choose the format after defining the task, then run syntax and business validation. It does not represent a provider success rate.
The common mistake: asking the model to “answer in JSON”
Asking for JSON in a prompt does not create an interface contract. The model may return syntactically valid JSON while omitting a property, selecting the wrong enum value, mixing a date and a string, or inventing a field that the receiving system cannot process. Even a structured mode does not verify the truth of an address, the compliance of a case or a user’s authority.
The JSON RFC 8259 defines an interchange syntax, while JSON Schema describes instance constraints. Those are different layers. A parser confirms that a document can be read. A validator confirms that its shape matches the schema. Business code must still check rules that belong to the organisation.
Separate three decisions in the contract:
- Shape: can the object be parsed without ambiguity?
- Value: are the fields plausible, complete and consistent with context?
- Action: may the application use the result, and within which limits?
Static Plotly matrix produced by Nexxom. Values from 1 to 3 are an editorial heuristic for reading trade-offs, not a model-quality measurement.
Free text: when readability matters most
Free text fits an answer that a person will read, review or rewrite: a meeting summary, an explanation of a decision, an answer to an open question or a draft that needs approval. It gives the model freedom over tone, order and nuance.
That freedom becomes a problem when a regular expression or script later tries to extract fields. Wording, units, separators and headings can change. If an integration relies on those details, it already has an implicit contract without compatibility tests.
| Situation | Is free text suitable? | Control to add |
|---|---|---|
| Answer read by a support adviser | Yes | Human review or quality sampling |
| Summary shown in an interface | Yes, if no automatic action follows | Length limits, source presence and content filter |
| Data sent to an ERP | Not by default | JSON Schema, business validation and an error log |
| Decision that triggers a payment | No | Authorised tool call, thresholds and human approval |
Free text can include readable markers. Do not present them as a structural guarantee. They make recovery easier, but rejection and validation still need to be explicit.
JSON Schema: a data contract
JSON Schema describes objects, arrays, types, required fields and enumerations. The 2020-12 specification is published by the JSON Schema project (current specification). Validation checks declared structure and constraints, not whether a value is true in the outside world (validation vocabulary).
OpenAI and Azure Structured Outputs add provider-side enforcement for part of this contract. Azure states that the available subset requires properties such as additionalProperties: false and required object fields. Google also documents a subset, nesting limits and the need to handle outputs that match the schema but are semantically wrong (Azure limitations, Gemini best practices).
| Control | What JSON Schema can express | What it does not prove |
|---|---|---|
| Type | string, number, integer, boolean, object, array | That the value is accurate in the real world |
| Enumeration | an allowed list of values | That the model chose the correct value |
| Required fields | presence of required keys | That a key contains complete data |
| Nested structure | relationships between objects and arrays | That the relationship is valid for the business |
| Validation | valid instance or rejection | Permission to execute an action |
Version a schema like an API. Add a version identifier, test added and removed fields, and keep one valid and one rejected example. Changing a schema without changing the downstream contract turns a format improvement into an integration incident.
Tool calls: when output becomes an action
A tool call is appropriate when a model needs to ask the application to run a function: look up an order, create a ticket, book a slot or calculate an amount. Anthropic describes a JSON input_schema for tool parameters and the tool_use and tool_result cycle that the application must handle (Anthropic overview). OpenAI documents the same separation between defining a function and executing it in application code (OpenAI Function Calling).
The schema must never be the only barrier. The application should check caller identity, resource scope, amount, idempotency, expiration and permissions. A refund tool can receive a value that conforms to the number type and still be forbidden by business policy.
| Step | Question | Security decision |
|---|---|---|
| Proposal | Did the model request an approved tool? | Reject every name outside the allow-list |
| Parameters | Do fields meet schema and limit checks? | Validate type, range, enum and size |
| Authorisation | Do user and service have the right? | Check identity and context in code |
| Execution | Can the action be repeated safely? | Use an idempotency key or approval |
| Result | Can the return value be re-injected without checks? | Mark its source, log it and filter it |
How to choose
Choose the output based on the consequence of an error. The closer an output is to an irreversible action, the more explicit the contract and the more independent the validation should be.
| Error consequence | Recommended format | Minimum validation |
|---|---|---|
| A reader corrects it manually | Free text | Tone, sources and sensitive-data checks |
| A record is created in a system | JSON Schema | Schema, business fields, duplicates and version |
| An external action is triggered | Tool call | Schema, identity, permissions, thresholds, idempotency and logs |
| The case is ambiguous or critical | Text or JSON with review | Human queue and an explainable decision |
The choice can be hybrid. An agent may produce a JSON object for an interface and a separate explanation for the user. A tool call may return a structured object that a model summarises, without allowing that summary to alter the source. Keep reference data, wording and action separate.
A production procedure
- Define the consumer: human, interface, database or tool.
- Describe the contract: types, required fields, enums, units, version and maximum size.
- Choose provider capability: JSON Schema, tool use or text, based on the exact model and endpoint documentation.
- Validate outside the model: parser, JSON Schema validator, business rules and permission checks.
- Plan failure handling: refusal, bounded retry, text fallback or human review.
- Observe: parse rate, business-validation rate, missing fields, rejections and cancelled actions.
- Version: retain the schema, examples, changes and downstream compatibility.
Test validation with ordinary cases, boundary values, missing fields, different languages, malicious data and outputs that conform but are false. The NIST AI RMF helps connect these tests to measurement, risk management and accountability without prescribing a provider or format.
Limits and traps
A schema that is too broad protects very little. A schema that is too strict rejects legitimate cases and encourages teams to disable it. Start with invariants that the receiving system truly consumes. Do not hide a long explanation inside an opaque string if a reader or auditor needs to check its provenance.
JSON Schema subsets differ across providers. A property supported by one service may be rejected by another, and availability can depend on the model or API. Check versions and test migrations. Do not compare only the label “structured output”: measure validation cost, retry behaviour, semantic errors and execution permissions.
Conclusion
Free text optimises readability, JSON Schema formalises a data contract, and a tool call frames a request for action. None replaces independent business validation. A reliable decision starts with the consequence of an error, selects the contract, then tests syntax, values, permissions and recovery.
Keep schemas as code, connect them to integration tests and document when a person takes over. This makes AI systems more observable without pretending that well-formed JSON is automatically a correct decision.
Primary sources verified on 21 August 2026
- OpenAI, Structured Outputs
- OpenAI, Function Calling
- Microsoft Azure, Structured Outputs
- Google Gemini API, Structured Outputs
- Anthropic, Tool Use
- JSON Schema, specification
- JSON Schema, validation vocabulary
- IETF, JSON RFC 8259
- NIST, AI Risk Management Framework
