Schema-First Prompting

~14 min · outputs, schema, design

Level 0Apprentice

0 XP0/100 lessons0/14 achievements

0/120 XP to next level120 XP to go0% complete

Design the output before the prompt

The cleanest prompts are written after the consumer's data shape is known. If the next step in your pipeline expects {verdict, reason_codes, sla_tier}, write that schema first, then write the prompt that produces it. This prevents the common bug where the prompt produces what the writer thought sounded helpful but the parser can't use.

Schema as the source of truth

Schemas live in source control alongside prompts.
The schema is shared between the prompt, the validator, and the consumer (TypeScript types, Python pydantic, etc.).
Schema changes force prompt changes — a feature, not a bug.
Optional fields are explicit, not implied. The model needs to know which can be omitted.

From schema to prompt

For each field, the prompt should explain meaning, allowed values, and absence behavior. Don't let the schema's enum carry semantics that the model can't learn from a name alone.

Code

Schema → prompt mapping·markdown

## Output schema (verdict_v3)
- verdict: string, one of [approve, reject, hold]
- reason_codes: array of strings, 1–3 entries from the enum below
- sla_tier: string, one of [silver, gold, platinum]
- notes: string, optional, ≤ 200 chars

## Field semantics
- approve = full approval. reason_codes must include 'ok'.
- reject = denied. reason_codes must include the policy that triggered.
- hold = needs human review. reason_codes must explain what info is missing.
- sla_tier = take from the customer record; do not infer.
- notes = optional human-readable summary; omit if no value to add.

External links

Exercise

Pick a prompt where you currently inline the output shape. Externalize it as a Pydantic or Zod schema. Generate the JSON Schema and use it as response_format. Note one mismatch the migration surfaced.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousStructured Outputs — JSON Mode and Beyond Next →Tool Calling — How the Model Decides

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.