Structured Output

Generate type-safe JSON data with AI models

Structured Output

Genkit allows you to generate structured JSON data that maps directly to your programming language’s type system. This ensures type safety and makes it easy to use AI-generated data in your applications.

Basic Structured Output

Define a schema and get type-safe JSON output:

TypeScript

import { genkit, z } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({ plugins: [googleAI()] });

const RecipeSchema = z.object({
  title: z.string(),
  ingredients: z.array(z.string()),
  steps: z.array(z.string()),
});

const { output } = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Create a recipe for chocolate chip cookies',
  output: { schema: RecipeSchema }
});

console.log(output.title);
console.log(output.ingredients);

Schema Annotations

Use schema annotations to guide the model’s output:

TypeScript

const JokeSchema = z.object({
  setup: z.string().describe('The joke setup'),
  punchline: z.string().describe('The joke punchline'),
  category: z.enum(['pun', 'wordplay', 'observational']),
});

const { output } = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Tell me a joke about cats',
  output: { schema: JokeSchema }
});

Complex Schemas

Create nested structures for complex data:

Go

type Ingredient struct {
    Name     string `json:"name" jsonschema:"description=The ingredient name"`
    Amount   string `json:"amount" jsonschema:"description=The ingredient amount (e.g. 1 cup, 2 tablespoons, etc.)"`
    Optional bool   `json:"optional,omitempty" jsonschema:"description=Whether the ingredient is optional in the recipe"`
}

type Recipe struct {
    Title        string        `json:"title" jsonschema:"description=The recipe title (e.g. 'Spicy Chicken Tacos')"`
    Description  string        `json:"description,omitempty" jsonschema:"description=The recipe description (under 100 characters)"`
    Ingredients  []*Ingredient `json:"ingredients" jsonschema:"description=The recipe ingredients (order by type first and then importance)"`
    Instructions []string      `json:"instructions" jsonschema:"description=The recipe instructions (step by step)"`
    PrepTime     string        `json:"prepTime" jsonschema:"description=The recipe preparation time (e.g. 10 minutes, 30 minutes, etc.)"`
    Difficulty   string        `json:"difficulty" jsonschema:"enum=easy,enum=medium,enum=hard"`
}

recipe, _ := genkit.GenerateData[*Recipe](ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("Create a recipe for spaghetti carbonara."),
)

Structured Output in Flows

Create flows that return structured data:

Go

type RecipeRequest struct {
    Dish                string   `json:"dish" jsonschema:"default=pasta"`
    Cuisine             string   `json:"cuisine" jsonschema:"default=Italian"`
    ServingSize         int      `json:"servingSize" jsonschema:"default=4"`
    MaxPrepMinutes      int      `json:"maxPrepMinutes" jsonschema:"default=30"`
    DietaryRestrictions []string `json:"dietaryRestrictions,omitempty"`
}

recipeFlow := genkit.DefineFlow(g, "recipeFlow",
    func(ctx context.Context, input RecipeRequest) (*Recipe, error) {
        return genkit.GenerateData[*Recipe](ctx, g,
            ai.WithModelName("googleai/gemini-2.5-flash"),
            ai.WithSystem("You are an experienced chef. Come up with easy, creative recipes."),
            ai.WithPromptFn(func(ctx context.Context, _ any) (string, error) {
                prompt := fmt.Sprintf(
                    "Create a %s %s recipe for %d people that takes under %d minutes to prepare.",
                    input.Cuisine, input.Dish, input.ServingSize, input.MaxPrepMinutes,
                )
                if len(input.DietaryRestrictions) > 0 {
                    prompt += fmt.Sprintf(" Dietary restrictions: %v.", input.DietaryRestrictions)
                }
                return prompt, nil
            }),
        )
    },
)

recipe, _ := recipeFlow.Run(ctx, RecipeRequest{
    Dish:        "tacos",
    Cuisine:     "Mexican",
    ServingSize: 4,
})

Dynamic Prompts with Structured Input

Use structured input to build complex prompts:

Go

ai.WithPromptFn(func(ctx context.Context, _ any) (string, error) {
    prompt := fmt.Sprintf(
        "Create a %s %s recipe for %d people that takes under %d minutes to prepare.",
        input.Cuisine, input.Dish, input.ServingSize, input.MaxPrepMinutes,
    )
    if len(input.DietaryRestrictions) > 0 {
        prompt += fmt.Sprintf(" Dietary restrictions: %v.", input.DietaryRestrictions)
    }
    return prompt, nil
})

Streaming Structured Output

Stream structured data as it’s generated. See the Streaming guide for details.

Best Practices

Use Descriptive Field Names

Choose clear, self-explanatory field names that help the model understand what to generate.

Add Schema Descriptions

Use jsonschema tags (Go) or .describe() (TypeScript) to provide additional context:

Go

type Product struct {
    Name  string  `json:"name" jsonschema:"description=The product name"`
    Price float64 `json:"price" jsonschema:"description=Price in USD"`
}

Use Enums for Categories

Constrain outputs to specific values using enums:

Go

type Article struct {
    Category string `json:"category" jsonschema:"enum=news,enum=sports,enum=tech"`
}

Handle Optional Fields

Mark fields as optional when they may not always be present:

Go

type User struct {
    Name     string `json:"name"`
    Nickname string `json:"nickname,omitempty"`
}

Next Steps

• Learn about Streaming to stream structured data
• Explore Tool Calling for dynamic capabilities
• Check out Prompts for advanced templating