Structured Outputs: Turn Messy Notes into Reliable Agent Data

Learning outcome: Convert an unstructured study note into typed tasks and deadlines that application code can reliably process.

This is Day 7 of AI Agents in 30 Days. On Day 6, we made a model call. Today, we make the response predictable enough for the rest of an application to use.

The core idea

A normal model response is written for a person:

You should finish graphs before Friday, revise arrays tomorrow and spend an hour studying dynamic programming.

That sentence is understandable, but your code still has to discover where one task ends, whether a deadline exists and how long an activity might take.

A structured output defines the expected shape before the model responds. For example:

task_name
deadline
priority
estimated_minutes

The result is still generated by a model, but every task follows the same contract. Your application can read a known key instead of repeatedly parsing a new paragraph.

OpenAI describes Structured Outputs as model responses that adhere to a supplied JSON Schema. JSON Schema itself describes and validates the structure, constraints and data types of JSON documents. See the current OpenAI Structured Outputs guide and the official JSON Schema getting-started guide.

From messy note to typed tasks

Consider this input:

Finish graphs before Friday, revise arrays tomorrow, and spend about an hour on DP.

We want an array of tasks in which every item has the same four fields.

Using null matters. The original note never gives a priority and only provides a time estimate for DP. A reliable extraction should represent missing information rather than quietly invent it.

The transformation flow

Messy note
   ↓
Defined schema
   ↓
Consistent task objects
   ↓
Sort · Save · Schedule · Pass to a tool

The schema creates a boundary between probabilistic language generation and deterministic application code.

Completed example

Here is one reasonable structured result:

[
  {
    "task_name": "Finish graphs",
    "deadline": "Friday",
    "priority": null,
    "estimated_minutes": null
  },
  {
    "task_name": "Revise arrays",
    "deadline": "tomorrow",
    "priority": null,
    "estimated_minutes": null
  },
  {
    "task_name": "Study dynamic programming",
    "deadline": null,
    "priority": null,
    "estimated_minutes": 60
  }
]

In a real scheduling application, relative deadlines such as tomorrow and Friday should be resolved using an explicit reference date and timezone. You could then require an ISO date such as 2026-08-21 instead of accepting ambiguous text.

JSON Schema object properties map names to values, and properties listed under required must be present. The official references explain object properties and required properties.

Why this helps an agent

Once the output follows a known shape, the next step becomes ordinary code:

• Sort tasks by deadline.

• Save tasks in a database.

• Build a daily or weekly study schedule.

• Send one task to a calendar or reminder tool.

• Reject or review an item when a required value is missing.

This is an important design principle: use the model for interpreting language, then use deterministic code for operations that should behave predictably.

Try this today

Choose one messy note from your phone, chat history or notebook.

1. Decide what your application should do with it.

2. Define four fields the application needs.

3. Give every field a type.

4. Decide which fields may be null.

5. Write one example output by hand.

For example, start with:

Prepare for next week's system-design interview.

A useful four-field structure might contain task_name, deadline, priority and estimated_minutes. If the note does not provide a value, keep it null or ask the user for clarification.

Common mistakes

1. Treating valid structure as factual correctness

A response can match the schema and still contain an incorrect deadline or a poor estimate. Validate important values and add human approval where mistakes have consequences.

2. Making every field required without handling missing information

If the input does not contain a value, the model may feel forced to invent one. Allow null, provide a default intentionally or ask a follow-up question.

3. Using vague field names

date is less clear than deadline. time could mean a clock time or duration; estimated_minutes removes that ambiguity.

4. Mixing extraction with action

First extract and validate the task. Then let ordinary code save it or let the agent request permission before taking an external action.

5. Ignoring refusals and incomplete responses

Production code should handle model refusals, truncation and other cases in which a normal structured result is unavailable.

Knowledge check

1. Why is a paragraph difficult for application code to use?
Because the location and format of each value can change from one response to another.

2. What does a schema define?
The expected fields, types and constraints of the output.

3. Does a valid schema guarantee that every value is true?
No. It guarantees structure, not factual accuracy.

4. What should you do when the input omits a value?
Allow null, apply an intentional default or ask the user for clarification.

Continue learning with Korshub

If you want to go deeper, use Korshub to discover courses and current learning deals related to AI agents, APIs, JSON and software development. Course availability and prices can change, so review the current listing before enrolling.

Series navigation

• Previous: Day 6 - Development Setup and APIs

• Roadmap: AI Agents in 30 Days

• Next: Day 8 - Function and Tool Calling will be linked after publication.