Structured Outputs

The flow

1. 1.Output contract
2. 2.Model output
3. 3.Parse
4. 4.Validate
5. 5.Business rule

Three layers of validity

Valid JSON can have an invalid schema; a valid schema can still describe a false fact or forbidden action. Define required properties, enums, length bounds and unknown-field behavior. Validate business invariants after structural validation.

Provider-native schema features and prompt-based converters offer different guarantees and support different schema subsets. Check the selected model and API rather than assuming every provider behaves identically.

Failure is part of the interface

Handle empty output, safety refusal, invalid JSON and output truncation separately. Use a bounded repair attempt for recoverable formatting errors; do not execute partially parsed content.

Do not silently fill a missing permission or account ID with a privileged default. Return a typed application error or request clarification. Keep raw sensitive output out of logs.

Evolve the contract

Version schemas and retain fixtures from earlier releases. When adding a field, check whether old clients reject unknown properties or require a migration. The example manually validates a small contract so its failure cases are visible.

Try it

import assert from 'node:assert/strict';
// A small executable contract; production can use a JSON Schema validator.
function parseDecision(text) {
  const value = JSON.parse(text);
  if (value === null || typeof value !== 'object' || Array.isArray(value) ||
      Object.keys(value).sort().join(',') !== 'action,reason' ||
      !['ESCALATE', 'ANSWER'].includes(value.action) ||
      typeof value.reason !== 'string' || !value.reason.trim()) {
    throw new Error('Invalid decision');
  }
  return value;
}
assert.equal(parseDecision('{"action":"ESCALATE","reason":"Missing source"}').action, 'ESCALATE');
for (const invalid of ['null', '[]', '{}', '{"action":"DELETE","reason":"x"}',
  '{"action":"ANSWER","reason":"x","admin":true}', 'not json']) {
  assert.throws(() => parseDecision(invalid));
}
console.log('Valid shape; factual correctness and authorization still need separate checks.');

Run with Node.js 22: node examples/generative-ai/structured-outputs.mjs. This is a deterministic teaching example, not a live model call.

Interview questions

Official references

• Spring AI — structured output converters

Continue learning

• Tool Calling →
• LLM Evaluation →