Turn LLM prompts into testable output contracts

Start with the receiving application

Suppose an application needs a support category, a short explanation, and a list of source identifiers. Decide the exact allowed categories and how to represent an unknown value before writing the prompt. A downstream workflow should not need to guess whether “billing issue,” “payments,” and “invoice problem” mean the same thing.

Keep extraction separate from execution. The model can propose a category or an action, while application code decides whether it meets the requirements for storage or further processing.

Validate shape and meaning separately

OpenAI’s Structured Outputs documentation describes constraining supported responses to a supplied JSON Schema, while also documenting refusals, incomplete responses, and schema limitations. Schema adherence is a structural property; it does not establish that a generated fact is correct.

• Shape checks: Required keys, types, allowed values, and extra fields.
• Semantic checks: Amounts within allowed ranges, consistent dates, and valid references.
• Evidence checks: Whether extracted values actually appear in the supplied material.
• Outcome checks: Whether the receiving workflow can use the response without repair.

Use explicit empty or unknown values when the business process supports them. Forcing every input into a positive answer can hide missing evidence and make an apparently complete record less trustworthy.

Version the whole experiment

A meaningful prompt comparison records more than the text. Preserve the model identifier, output schema, relevant request settings, source-selection logic, and test dataset. Otherwise, a change in behavior may be incorrectly attributed to a single sentence.

Include borderline examples where two categories look plausible, input contains contradictory values, or required evidence is absent. Write the expected handling for each case. Review individual failures as well as overall pass rates; a small number of severe mistakes may outweigh many easy successes.

Assign a change note to each revision and keep a known useful baseline. Before adopting a new version, check that its improvement survives the same evaluation conditions.

The prompt design guide covers task wording and context. The QA test guide explains how these checks fit alongside API contract and regression testing.