AI structured data: JSON
This course covers getting reliable structured data out of model calls as JSON. It separates four failure modes: envelope, syntax, shape and semantics. It explains what structured outputs guarantee and which JSON Schema keywords are unsupported. Lessons cover designing schemas a model can fill, choosing between response formats and strict tools, and validating values with ActiveModel in Rails. Later lessons handle refusals, truncation and bounded repair, then assemble an extraction pipeline with testing and schema versioning.
What you'll learn
- ✓The four failure modes of model JSON and which ones structured outputs remove
- ✓The supported JSON Schema subset and the rules you must check in Ruby
- ✓Schema design with units in names, enums, nullable fields and verbatim quotes
- ✓When to use output_config.format and when to use strict tools
- ✓Validating extractions with an ActiveModel value object and logging rejections
- ✓Handling refusals, truncation and repair inside a tested extraction pipeline
Why asking nicely fails
Seven courses have leaned on the same assumption: a model call returns a value your code can use. Chaining passes structured output between stages. Routers return a route. Orchestrators emit plans. Evaluators return typed critiques. Every one of those breaks the same way when the JSON is not JSON.
Read the full lesson free →Curriculum
7 lessonsWhy asking nicely fails
Shows why prompting for JSON breaks and splits failures into envelope, syntax, shape and semantic problems.
What the guarantee covers
Lists the JSON Schema subset structured outputs support, what is guaranteed, and what refusals and truncation bypass.
Designing a schema a model can fill
Covers field naming, enums, nullable fields, confidence and quote fields, flattening recursion and keeping schemas small.
Tools, strict, and choosing a mechanism
Compares response formats with strict tools, deciding by whether the model is answering or acting.
Validation after the guarantee
Adds a second validation layer in Rails with ActiveModel for ranges, plausibility, source quotes and business rules.
When it fails anyway
Handles refusals, truncation and semantic failures with stop_reason checks, bounded repair and a human review queue.
Extraction as a pipeline
Assembles a five-stage extraction pipeline with closed statuses, layered tests and versioned schema changes treated as migrations.