Creating types.ts Files with Zod Schemas

Overview

This skill documents how to create types.ts files for Output SDK workflows. These files contain Zod schemas for input/output validation and their corresponding TypeScript types.

When to Use This Skill

• Creating a new workflow's type definitions
• Adding new schemas for steps
• Fixing schema validation errors
• Refactoring existing type definitions

Critical Import Rule

ALWAYS import z from @outputai/core, NEVER from zod directly:

// CORRECT
import { z } from '@outputai/core';

// WRONG - will cause runtime errors
import { z } from 'zod';

Related Skill: output-error-zod-import for troubleshooting import issues

Basic Structure

import { z } from '@outputai/core';

// 1. Workflow Input Schema
export const WorkflowInputSchema = z.object( {
  // Define input fields
} );

// 2. Workflow Output Type
export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;
export type WorkflowOutput = /* output type */;

// 3. Step Schemas (for each step)
export const StepNameInputSchema = z.object( {
  // Step input fields
} );

export const StepNameOutputSchema = z.object( {
  // Step output fields
} );

// 4. Type Exports
export type StepNameInput = z.infer<typeof StepNameInputSchema>;
export type StepNameOutput = z.infer<typeof StepNameOutputSchema>;

CRITICAL: Schema Constraints for LLM Output

Schemas passed to Output.object() are sent to LLM providers as tool definitions. Anthropic rejects several JSON Schema constraints that Zod methods produce. Getting this wrong causes runtime errors.

What Is NOT Allowed in LLM Output Schemas

• Numbers: .min(), .max() on z.number() produce minimum/maximum -- rejected by Anthropic.
• Arrays: .min(), .max(), .length() on z.array() produce minItems/maxItems -- Anthropic only supports minItems of 0 or 1. Values like .length( 3 ) or .min( 2 ) will be rejected.

Use .describe() Instead

.describe() is the primary mechanism for guiding LLM output quality. LLM providers use field names and descriptions from the schema to understand what each field should contain. Write clear, specific descriptions that communicate your intent.

Important: .describe() replaces both unsupported constraints AND prompt-based format instructions. Do not also describe the schema in the prompt -- the schema is sent to the provider automatically, and duplicating it reduces performance and creates drift risk. See output-dev-prompt-file for details.

// LLM output schema (sent to provider via Output.object()) -- .describe() ONLY
const llmOutputSchema = z.object( {
  score: z.number().describe( 'Quality score 0-100' ),
  confidence: z.number().describe( 'Confidence 0-1' ),
  predictions: z.array( predictionSchema ).describe( 'Exactly 3 predictions' )
} );

// Workflow/step validation schema (Zod-only, NOT sent to LLM) -- .min()/.max()/.length() OK
const workflowOutputSchema = z.object( {
  score: z.number().min( 0 ).max( 100 ).describe( 'Quality score 0-100' ),
  confidence: z.number().min( 0 ).max( 1 ).describe( 'Confidence 0-1' ),
  predictions: z.array( predictionSchema ).length( 3 ).describe( 'Exactly 3 predictions' )
} );

When to Use Which

LLM Schemas Must Live in types.ts

Define all schemas used in Output.object() in types.ts and import them in step functions. Never define them inline -- this causes duplication and makes it harder to verify they follow the constraints above.

Common Schema Patterns

Basic Types

import { z } from '@outputai/core';

// Strings
const stringField = z.string();
const optionalString = z.string().optional();
const stringWithDefault = z.string().default( 'default value' );
const describedString = z.string().describe( 'Field description' );

// Numbers
const numberField = z.number();
const integerField = z.number().int();
const rangedNumber = z.number().min( 1 ).max( 100 ); // runtime only — NOT safe for Output.object() schemas

// Booleans
const booleanField = z.boolean();
const defaultBoolean = z.boolean().default( false );

// Enums
const enumField = z.enum( [ 'option1', 'option2', 'option3' ] );
const enumWithDefault = z.enum( [ 'small', 'medium', 'large' ] ).default( 'medium' );

Complex Types

import { z } from '@outputai/core';

// Arrays
const stringArray = z.array( z.string() );
const objectArray = z.array( z.object( { id: z.string(), name: z.string() } ) );

// Objects
const nestedObject = z.object( {
  user: z.object( {
    id: z.string(),
    email: z.string().email()
  } ),
  settings: z.object( {
    notifications: z.boolean()
  } )
} );

// Union Types
const flexibleInput = z.union( [
  z.string(),
  z.array( z.string() )
] );

// Records
const keyValueMap = z.record( z.string(), z.number() );

Validation Patterns

import { z } from '@outputai/core';

// String Validations
const emailField = z.string().email();
const urlField = z.string().url();
const uuidField = z.string().uuid();
const minLengthString = z.string().min( 1 );
const maxLengthString = z.string().max( 1000 );

// Number Validations
const positiveNumber = z.number().positive();
const nonNegativeNumber = z.number().nonnegative();
const percentageNumber = z.number().min( 0 ).max( 100 );

// Array Validations (runtime only — NOT safe for Output.object() schemas)
const nonEmptyArray = z.array( z.string() ).min( 1 );
const limitedArray = z.array( z.string() ).max( 10 );
const fixedLengthArray = z.array( z.string() ).length( 3 );

Complete Example

Based on a real workflow (image_infographic_nano):

import { z } from '@outputai/core';

// ============================================
// Workflow Schemas
// ============================================

export const WorkflowInputSchema = z.object( {
  content: z.string().describe( 'Text content to generate image ideas from' ),
  mode: z.enum( [ 'infographic' ] ).default( 'infographic' ).describe( 'Type of image to generate' ),
  colorPalette: z.string().optional().describe( 'Color palette preference for the images' ),
  artDirection: z.string().optional().describe( 'Art direction or style preference' ),
  numberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of image concepts to generate' ),
  referenceImageUrls: z.union( [
    z.string(),
    z.array( z.string() )
  ] ).optional().describe( 'Reference image URLs for style guidance (max 14)' ),
  aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ).default( '1:1' ).describe( 'Aspect ratio for generated images' ),
  resolution: z.enum( [ '1K', '2K', '4K' ] ).default( '1K' ).describe( 'Resolution for generated images' ),
  numberOfGenerations: z.number().min( 1 ).max( 10 ).default( 1 ).describe( 'Number of images to generate per concept' ),
  storageNamespace: z.string().optional().describe( 'S3 folder path for storing images' )
} );

export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;
export type WorkflowOutput = string[];

// ============================================
// Step Schemas
// ============================================

export const ValidateReferenceImagesInputSchema = z.object( {
  referenceImageUrls: z.array( z.string() ).optional()
} );

export const GenerateImageIdeasInputSchema = z.object( {
  content: z.string(),
  numberOfIdeas: z.number(),
  colorPalette: z.string().optional(),
  artDirection: z.string().optional()
} );

export const GenerateImagesInputSchema = z.object( {
  input: z.object( {
    referenceImageUrls: z.union( [ z.string(), z.array( z.string() ) ] ).optional(),
    aspectRatio: z.enum( [ '1:1', '16:9', '9:16', '4:3', '3:4' ] ),
    resolution: z.enum( [ '1K', '2K', '4K' ] ),
    numberOfGenerations: z.number(),
    storageNamespace: z.string().optional()
  } ),
  prompt: z.string()
} );

// Schema for LLM response validation
export const ImageIdeasSchema = z.object( {
  ideas: z.array( z.string() ).describe( 'Array of detailed image prompts for Gemini' )
} );

// ============================================
// Type Exports
// ============================================

export type ValidateReferenceImagesInput = z.infer<typeof ValidateReferenceImagesInputSchema>;
export type GenerateImageIdeasInput = z.infer<typeof GenerateImageIdeasInputSchema>;
export type GenerateImagesInput = z.infer<typeof GenerateImagesInputSchema>;
export type ImageIdeas = z.infer<typeof ImageIdeasSchema>;

Best Practices

1. Use Descriptive Field Descriptions

// Good - helps with documentation and error messages
z.string().describe( 'User email address for notifications' )

// Avoid - no context for errors
z.string()

2. Provide Sensible Defaults

// Good - workflow works without optional fields
numberOfIdeas: z.number().min( 1 ).max( 10 ).default( 1 )

// Avoid - forces users to provide every field
numberOfIdeas: z.number().min( 1 ).max( 10 )

3. Separate Workflow and Step Schemas

// Workflow input schema (what the user provides)
export const WorkflowInputSchema = z.object( { ... } );

// Step schemas (internal data shapes)
export const StepNameInputSchema = z.object( { ... } );

4. Export Both Schemas and Types

// Export schema for runtime validation
export const UserSchema = z.object( { ... } );

// Export type for TypeScript type checking
export type User = z.infer<typeof UserSchema>;

Verification Checklist

• [ ] z is imported from @outputai/core
• [ ] WorkflowInputSchema is defined and exported
• [ ] WorkflowInput type is exported
• [ ] WorkflowOutput type is defined
• [ ] Each step has corresponding input/output schemas
• [ ] All schemas have .describe() for important fields
• [ ] Optional fields use .optional() or .default()
• [ ] Numeric fields have appropriate constraints (.min()/.max() for runtime schemas, .describe() for Output.object() schemas)
• [ ] Code follows style conventions (see output-dev-code-style)

Related Skills

• output-dev-workflow-function - Using schemas in workflow definitions
• output-dev-step-function - Using schemas in step definitions
• output-dev-evaluator-function - Using schemas in evaluator definitions
• output-dev-folder-structure - Where types.ts belongs in the project
• output-error-zod-import - Troubleshooting schema import issues
• output-dev-code-style - Code style conventions