prompt-schema

Convert Zod schemas to AI prompts in Markdown.

!prompt-schema


---

Table of Contents

- What is this?
- Quick Start
- Themes
- Options
- Advanced Usage
- API Reference
- Supported Features
- License

---

What is this?

When using LLMs with structured output (OpenAI function calling, AI SDK generateObject, etc.), you need to tell the model what schema to follow. This library converts your Zod schemas into clear, Markdown-formatted prompt instructions that LLMs understand well.

Before (raw JSON Schema dumped into prompt):

``json
{
"type": "object",
"properties": {
"name": { "type": "string", "maxLength": 100 },
"email": { "type": "string", "format": "email" },
"age": { "type": "number", "minimum": 0, "maximum": 120 }
},
"required": ["name", "email", "age"]
}
`

After (prompt-schema output):

`


Schema

- name: string (required • max 100 chars)
- email: string (required • format: email)
- age: number (required • min: 0 • max: 120)
`

---

Quick Start

$3

`bash
npm install prompt-schema zod
`

> Requires zod@^3.25.0 (includes both v3 and v4 APIs)

$3

`typescript
import { getPrompts } from 'prompt-schema';
import { z } from 'zod/v3';

const schema = z.object({
name: z.string().max(100),
email: z.string().email(),
age: z.number().min(0).max(120),
});

const prompt = getPrompts(schema);
`

Output:

`


Schema

- name: string (required • max 100 chars)
- email: string (required • format: email)
- age: number (required • min: 0 • max: 120)
`

---

Themes

Choose an output format that fits your use case. The standard, expanded, and condensed themes output Markdown, which LLMs parse reliably:

$3

Clean and readable, optimized for AI prompts:

`


Schema

- name: string (required)
- age: number (required • min: 0)
- email: string (required • format: email)
`

$3

Ultra-compact for token efficiency:

`
name:str!
age:num![≥0]
email:str![@]
`

$3

Includes full constraint details:

`


Schema

- name: string (required)
- age: number (required • min: 0)
- email: string (required • pattern: ^[...] • format: email)

Examples

{ "name": "John Doe", "age": 30, "email": "john@example.com" }
`

$3

Structured data for programmatic use:

`json
{
"schema": {
"fields": [
{ "name": "name", "type": "string", "required": true },
{ "name": "age", "type": "number", "required": true, "constraints": { "min": 0 } },
{ "name": "email", "type": "string", "required": true, "constraints": { "format": "email" } }
]
}
}
`

$3

`typescript
const prompt = getPrompts(schema, { theme: 'condensed' });
`

---

Options

| Option | Type | Default | Description |
| ---------- | --------------------------------------------------------- | ------------ | ---------------------------------------------------- |
| theme | 'standard' \| 'condensed' \| 'expanded' \| 'json' | 'standard' | Output format |
| maxDepth | number | 3 | Maximum nesting depth for objects/arrays |
| safe | boolean | false | Return fallback message on error instead of throwing |

---

Advanced Usage

$3

Zod v4 supports .meta() for adding examples:

`typescript
import { getPrompts } from 'prompt-schema';
import { z } from 'zod/v4';

const schema = z
.object({
username: z.string().min(3).max(20),
age: z.number().min(18),
})
.meta({
examples: [{ username: 'john_doe', age: 25 }],
});

const prompt = getPrompts(schema, { theme: 'expanded' });
`

$3

`typescript
import { z } from 'zod/v3';

// Unions
const unionSchema = z.object({
value: z.union([z.string(), z.number(), z.boolean()]),
});
// → value: string | number | boolean (required)

// Tuples
const tupleSchema = z.object({
coordinates: z.tuple([z.number(), z.number()]),
});
// → coordinates: [number, number] (required)

// Records
const recordSchema = z.object({
metadata: z.record(z.string(), z.string()),
});
// → metadata: Record (required)

// Discriminated Unions
const notificationSchema = z.object({
notification: z.discriminatedUnion('type', [
z.object({ type: z.literal('email'), to: z.string().email() }),
z.object({ type: z.literal('sms'), phone: z.string() }),
]),
});
`

$3

For advanced use cases, use the PromptSchema class directly:

`typescript
import { PromptSchema, zodV3Adapter, zodV4Adapter, jsonSchemaAdapter } from 'prompt-schema';

const converter = new PromptSchema();
converter.registerAdapter(zodV4Adapter);
converter.registerAdapter(zodV3Adapter);
converter.registerAdapter(jsonSchemaAdapter);

const prompt = converter.toPrompt(schema, { theme: 'expanded' });
`

See CONTRIBUTING.md for creating custom adapters.

---

API Reference

$3

Main entry point. Auto-detects Zod v3 or v4.

`typescript
function getPrompts(schema: unknown, options?: ContextOptions): string;
`

$3

`typescript
class PromptSchema {
registerAdapter(adapter: SchemaAdapter): void;
toPrompt(schema: unknown, options?: ContextOptions): string;
getAdapters(): string[];
}
`

$3

`typescript
interface ContextOptions {
theme?: 'standard' | 'condensed' | 'expanded' | 'json';
maxDepth?: number;
safe?: boolean;
}

interface SchemaAdapter {
name: string;
canHandle: (schema: unknown) => boolean;
toJsonSchema: (schema: T, options?: unknown) => JsonSchema;
}
`

---

Supported Features

$3

- Objects with nested properties
- Arrays with typed items
- Tuples (fixed-length arrays)
- Records (dynamic key-value maps)
- Enums and literal values
- Optional and nullable fields
- Discriminated unions
- Regular unions
- Date types (z.date() → format: date-time)
- All Zod constraints (min, max, length, regex, format)
- Zod v3 and v4

$3

- Intersections - Treated as merged objects, may lose some type information

$3

These Zod features don't translate to JSON Schema:

- transform(), refine() - Runtime-only validations
- lazy() - Recursive schemas would cause infinite loops
- set(), map() - No JSON Schema equivalent
- bigint(), symbol(), function(), promise() - Not serializable
- never(), unknown(), any(), void(), undefined(), nan()` - Fall back to generic types

---

License

MIT - Created by Joe Seifi