output-dev-types-file

What this skill does

# 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:

```typescript
// 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

```typescript
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.

```typescript
// 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

| Context | `.min()/.max()/.length()` | `.describe()` |
|---------|:-:|:-:|
| Schema passed to `Output.object()` | **No** (numbers or arrays) | Yes |
| `inputSchema` / `outputSchema` on steps | OK | Optional |
| `inputSchema` / `outputSchema` on workflows | OK | Optional |
| `outputSchema` on evaluators | OK | Optional |

### 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

```typescript
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

```typescript
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

```typescript
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`):

```typescript
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.strin