Docs

Documentation

Structured JSON AI Outputs

Stop parsing raw text. Define strict JSON schemas for your AI responses. ModelRiver handles validation, merging, and type-safe delivery across all providers.

Why structured outputs?

Raw AI responses are unpredictable. Different providers return different formats, and even the same model can vary between requests. Structured outputs solve this by enforcing a JSON schema on every response, giving your application a contract it can rely on.

How it works

  1. Define a schema: Create a JSON schema in the ModelRiver console under Structured Outputs.
  2. Attach to a workflow: Link the schema to one or more workflows.
  3. Automatic validation: ModelRiver validates every AI response against your schema and merges results so required fields are always present.
  4. Fallback synthesis: If a provider is down or times out, ModelRiver can synthesise a schema-compliant fallback, flagged via meta.offline_fallback = true.

Creating a structured output

  1. Navigate to Structured Outputs in your project sidebar
  2. Click Create Structured Output
  3. Define your JSON schema with required fields, types, and descriptions
  4. Add sample data that conforms to the schema (used for test mode)
  5. Save and attach to workflows

Schema example

JSON
1{
2 "type": "object",
3 "required": ["summary", "sentiment", "category"],
4 "properties": {
5 "summary": {
6 "type": "string",
7 "description": "A concise summary of the input"
8 },
9 "sentiment": {
10 "type": "string",
11 "enum": ["positive", "negative", "neutral"],
12 "description": "Overall sentiment classification"
13 },
14 "category": {
15 "type": "string",
16 "description": "Topic category of the content"
17 },
18 "confidence": {
19 "type": "number",
20 "minimum": 0,
21 "maximum": 1,
22 "description": "Model confidence score"
23 }
24 }
25}

Best practices

  • Include examples in the schema to guide providers. ModelRiver passes these as context to improve compliance.
  • Start simple: Begin with a minimal schema and add fields as your application matures.
  • Use enums for categorical fields to constrain values and reduce parsing errors.
  • Monitor validation: Check Observability for validation failure rates and adjust schemas accordingly.
  • Leverage fallbacks: The meta.offline_fallback flag lets your application distinguish between real and synthesised responses.

Offline fallback behaviour

When all configured providers fail, ModelRiver can return a schema-compliant response using your sample data:

  • The response is flagged with meta.offline_fallback = true
  • Your application can detect this and show appropriate UI (e.g. "Results may be approximate")
  • This ensures your application never crashes due to missing AI responses

Next steps