The Easiest Way to Generate Structured Output with the AI SDK

Generating structured output from AI models has always been a challenge. You send a prompt, get back some text, and then spend time parsing it into the format you actually need. The AI SDK changes all of that with its powerful structured output features.

In this guide, we'll explore the different ways to generate structured output using the AI SDK, from simple text generation to complex, validated object schemas.

Why Structured Output Matters

Before diving into the how, let's understand the why:

Type Safety: Get responses that match your expected data structure
Reliability: No more parsing failures or unexpected formats
Developer Experience: Better IntelliSense and error handling
Production Ready: Structured output is essential for production AI applications

Method 1: Basic Text Generation with `generateText`

The simplest form of structured output is getting plain text responses. Here's how to use generateText:

import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const model = google("gemini-2.5-flash-lite");

const result = await generateText({
  model,
  prompt: "Write a short summary of the benefits of structured output",
  system: "You are a helpful AI assistant that writes concise summaries."
});

console.log(result.text); // The generated text

When to use: Simple text generation, creative writing, summaries, explanations.

Method 2: Structured Objects with `generateObject`

This is where the magic happens. generateObject allows you to define a schema and get back a perfectly structured object:

import { generateObject } from 'ai';
import { z } from 'zod';
import { google } from '@ai-sdk/google';

const model = google("gemini-2.5-flash-lite");

// Define your schema using Zod
const UserProfileSchema = z.object({
  name: z.string(),
  age: z.number(),
  interests: z.array(z.string()),
  bio: z.string().max(200),
  isActive: z.boolean()
});

const result = await generateObject({
  model,
  schema: UserProfileSchema,
  prompt: "Create a user profile for a 25-year-old developer who loves TypeScript and AI",
  system: "You are a data generation expert. Always return valid data matching the schema."
});

// result.object is fully typed and validated
console.log(result.object.name); // TypeScript knows this is a string
console.log(result.object.interests); // TypeScript knows this is string[]

Key Benefits:

Automatic Validation: The AI SDK ensures the response matches your schema
Type Safety: Full TypeScript support with IntelliSense
Error Handling: Built-in validation and error reporting

Method 3: Advanced Schemas with Nested Objects

For complex applications, you can create sophisticated schemas:

import { generateObject } from 'ai';
import { z } from 'zod';

const ChangeSchema = z.object({
  title: z.string(),
  content: z.string(),
  type: z.enum(["added", "changed", "deprecated", "removed", "fixed", "security", "other"]),
  size: z.enum(["minor", "patch", "major"]),
  version: z.string(),
  date: z.string()
});

const ChangelogEntrySchema = z.object({
  version: z.string(),
  date: z.string(),
  changes: z.array(ChangeSchema).default([])
});

const result = await generateObject({
  model,
  schema: ChangelogEntrySchema,
  prompt: "Analyze this commit and create a changelog entry",
  system: "You are a changelog expert. Analyze commits and categorize changes appropriately."
});

Method 4: Using Tools for Complex Operations

The AI SDK also supports tools, which are perfect for operations that require external data or complex processing:

import { tool } from 'ai';
import { z } from 'zod';

// Define a tool for extracting context from URLs
export const urlContext = tool({
  description: "Extract context from a URL",
  inputSchema: z.object({
    url: z.string(),
  }),
  execute: async ({ url }) => {
    const res = await fetch(url);
    if (!res.ok) {
      throw new Error(`Failed to fetch URL: ${res.status}`);
    }
    const text = await res.text();
    return { text };
  },
});

// Use the tool in your generation
const result = await generateObject({
  model,
  schema: SummarySchema,
  prompt: "Summarize the content from this URL",
  tools: [urlContext]
});

Real-World Example: Changelog Generation

Here's how we use structured output in ShipLog to analyze commits and generate changelog entries:

// From our actual codebase
export async function analyzeCommit(commit: CommitData, project: Project) {
  const system = ChangelogEntryPrompt;

  try {
    const result = await generateObject({
      model,
      schema: ChangelogEntrySchema,
      system,
      prompt: `Analyze this commit and determine if it should be included in the changelog:

        Commit Information:
        ${JSON.stringify(commit, null, 2)}

        Please analyze this commit and return a structured response.`
    });

    // result.object is guaranteed to match our schema
    return result.object;
  } catch (error) {
    console.error("Error analyzing commit:", error);
    return defaultAnalysis;
  }
}

Best Practices for Structured Output

1. Use Descriptive Schemas

// ❌ Too generic
const Schema = z.object({
  data: z.any()
});

// ✅ Specific and descriptive
const UserProfileSchema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email format"),
  preferences: z.object({
    theme: z.enum(["light", "dark", "auto"]),
    notifications: z.boolean()
  })
});

2. Provide Clear System Prompts

const system = `You are a data generation expert. Your responses must:
- Always match the provided schema exactly
- Use realistic, appropriate data
- Follow the specified format without deviation
- Provide meaningful, useful information`;

3. Handle Errors Gracefully

try {
  const result = await generateObject({
    model,
    schema: MySchema,
    prompt: "Generate user data"
  });

  return result.object;
} catch (error) {
  if (error.name === 'ZodValidationError') {
    console.error('Schema validation failed:', error.issues);
    return fallbackData;
  }
  throw error;
}

4. Use Default Values for Optional Fields

const Schema = z.object({
  required: z.string(),
  optional: z.string().optional().default("default value"),
  array: z.array(z.string()).default([])
});

Performance Considerations

1. Model Selection

Different models have different strengths:

Fast & Cheap: gemini-2.5-flash-lite - Great for simple structured output
Balanced: gpt-4-turbo - Good balance of speed and quality
High Quality: gpt-4 - Best for complex reasoning and structured output

2. Schema Complexity

Keep your schemas as simple as possible while meeting your needs:

// ❌ Too complex - may cause generation issues
const ComplexSchema = z.object({
  nested: z.object({
    deeply: z.object({
      nested: z.object({
        data: z.array(z.object({
          // ... many more levels
        }))
      })
    })
  })
});

// ✅ Simpler, more reliable
const SimpleSchema = z.object({
  items: z.array(z.object({
    id: z.string(),
    value: z.string()
  }))
});

Common Pitfalls and How to Avoid Them

1. Schema Mismatch

Problem: AI generates data that doesn't match your schema Solution: Use clear prompts and validate your schema design

// Make your schema intuitive
const IntuitiveSchema = z.object({
  firstName: z.string(), // Clear field name
  lastName: z.string(),
  fullName: z.string().optional() // Optional computed field
});

2. Overly Strict Validation

Problem: Schema is too restrictive, causing generation failures Solution: Balance strictness with flexibility

// ❌ Too strict
const StrictSchema = z.object({
  age: z.number().int().positive().max(120)
});

// ✅ More flexible
const FlexibleSchema = z.object({
  age: z.number().int().positive().max(120).default(25)
});

3. Insufficient Context

Problem: AI doesn't understand what you want Solution: Provide clear examples and context

const prompt = `Generate a user profile. Here are some examples:
- A developer: {name: "Alice", age: 28, interests: ["coding", "AI"]}
- A designer: {name: "Bob", age: 32, interests: ["UI/UX", "art"]}

Now generate a profile for a data scientist.`;

Testing Your Structured Output

Always test your structured output generation:

// Test function
async function testGeneration() {
  try {
    const result = await generateObject({
      model,
      schema: TestSchema,
      prompt: "Generate test data"
    });

    console.log('✅ Generation successful:', result.object);

    // Validate the result matches your expectations
    const validation = TestSchema.safeParse(result.object);
    if (!validation.success) {
      console.error('❌ Validation failed:', validation.error);
    }
  } catch (error) {
    console.error('❌ Generation failed:', error);
  }
}

Conclusion

The AI SDK's structured output features make it incredibly easy to get reliable, type-safe responses from AI models. Whether you're building a simple text generator or a complex AI-powered application, these tools provide the foundation you need.

Key takeaways:

Use generateText for simple text generation
Use generateObject with Zod schemas for structured data
Design intuitive, well-documented schemas
Provide clear system prompts and examples
Handle errors gracefully
Test your generation thoroughly

With these techniques, you can build AI applications that are both powerful and reliable. The structured output ensures your AI responses integrate seamlessly with your existing codebase, making AI a first-class citizen in your applications.

Ready to implement structured output in your AI applications? Try ShipLog today and see how we use these techniques to generate perfect changelogs automatically.