Schemas

Schemas define the structure of objects that ProposeFlow generates. They use Zod for validation and provide full TypeScript type inference.

What are Schemas?

A schema is a blueprint that describes the shape of data you want the AI to generate. When you call generate(), ProposeFlow uses your schema to ensure the AI output matches your expected structure.

Type Safety

Schemas provide compile-time type checking. Your IDE knows the exact shape of generated data.

Validation

Generated data is automatically validated against your schema before being returned.

AI Guidance

Field descriptions help the AI understand what content to generate for each field.

Defining a Schema

Use Zod to define your schema. Add .describe() to fields to help the AI understand the expected content.

schemas/product.ts

import { z } from 'zod';

export const productSchema = z.object({
  name: z.string().describe('Product name, clear and concise'),
  description: z.string().describe('Compelling product description, 2-3 sentences'),
  price: z.number().positive().describe('Price in USD'),
  category: z.enum(['electronics', 'clothing', 'home', 'sports'])
    .describe('Primary product category'),
  features: z.array(z.string())
    .min(3)
    .max(6)
    .describe('Key product features as bullet points'),
  inStock: z.boolean().describe('Whether the product is currently available'),
});

export type Product = z.infer<typeof productSchema>;

Complex Schemas

Schemas can include nested objects, arrays, unions, and optional fields.

schemas/recipe.ts

import { z } from 'zod';

const IngredientSchema = z.object({
  name: z.string(),
  amount: z.string().describe('e.g., "2 cups", "1 tbsp"'),
  optional: z.boolean().default(false),
});

export const RecipeSchema = z.object({
  title: z.string(),
  description: z.string(),
  prepTime: z.number().describe('Prep time in minutes'),
  cookTime: z.number().describe('Cook time in minutes'),
  servings: z.number().min(1).max(12),
  difficulty: z.enum(['easy', 'medium', 'hard']),
  ingredients: z.array(IngredientSchema).min(3),
  instructions: z.array(z.string()).min(3).describe('Step-by-step instructions'),
  tips: z.array(z.string()).optional().describe('Optional cooking tips'),
});

Registering Schemas

Register your schemas with the ProposeFlow client using the schemas option. The schema registry provides full TypeScript inference.

lib/proposeflow.ts

import { ProposeFlow } from '@proposeflow/sdk';
import { z } from 'zod';
import { productSchema } from './schemas/product';
import { recipeSchema } from './schemas/recipe';

export const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,
  schemas: {
    product: productSchema,
    recipe: recipeSchema,
  },
});

// Now you can use:
// pf.generate('product', { input: '...' }) -> { proposal: Proposal<Product> }
// pf.generate('recipe', { input: '...' }) -> { proposal: Proposal<Recipe> }

Schema-Level Model Tier

Set a default model tier for all generations using a schema. This is useful when certain schemas need higher quality output (like technical documentation) or faster generation (like quick suggestions).

schema-model-tier.ts

// Register schemas with different default model tiers
await pf.schemas.register('quickSuggestion', {
  version: '1.0.0',
  description: 'Fast suggestions for autocomplete',
  modelTier: 'fast',  // Use fastest model for quick suggestions
});

await pf.schemas.register('technicalDoc', {
  version: '1.0.0',
  description: 'Detailed technical documentation',
  modelTier: 'quality',  // Use highest quality for important content
});

await pf.schemas.register('blogPost', {
  version: '1.0.0',
  description: 'Blog posts',
  modelTier: 'balanced',  // Default: balanced quality and cost
});

// Model tier can still be overridden per-generation:
const { proposal } = await pf.generate('blogPost', {
  input: 'Write about AI',
  modelTier: 'quality',  // Override for this specific generation
});

See SDK Configuration for more details on model tiers and credit rates.

Best Practices

•Be specific with descriptions — The more context you provide, the better the AI output.
•Use constraints — Add .min(),.max(), and.length() to control output size.
•Use enums for categories — Enums ensure the AI picks from valid options.
•Export your types — Use z.infer to create TypeScript types from your schemas.