Output Format Specification — Module 13.2

How This Lesson Fits the Module & Volume

Downstream code needs predictable shapes. Building on structured output prompting and JSON prompting, this lecture covers writing format specs that humans and parsers agree on—schemas, headers, and failure modes.

Learning Objectives

By the end of this lesson, students should be able to:

Specify formats with schemas, examples, and field dictionaries.
Choose JSON, Markdown, CSV, or tagged text for the use case.
Ban preambles that break parsers.
Define repair / retry behavior for invalid output.
Align few-shot examples with the live schema.
Validate outputs in code, not by trust alone.

Definition

An output format specification is an explicit contract describing the shape, types, allowed values, and packaging of the model’s response so both reviewers and machines can accept or reject it deterministically.

Format Contract Checklist

Shape

JSON object / bullets / table.

Fields

Names, types, enums.

Packaging

No fences? fences? raw?

Errors

What if unknown / N/A.

Validate

Schema check in code.

Format	Best for	Common break
JSON	APIs, tools, agents	Trailing commentary
Markdown sections	Human docs	Missing headings
CSV / TSV	Tabular exports	Commas in fields
Tagged lines	Simple parsers	Inconsistent labels

Before / After

Before (weak):

Return some JSON about the ticket somehow, maybe explain your thinking too.

After (strong):

Return JSON only. No markdown fences. No prose before or after.

Schema:
{
  "urgency": "LOW" | "MEDIUM" | "HIGH",
  "needs_human": boolean,
  "summary": string  // ≤ 20 words, no PII
}

If urgency cannot be determined, use:
{"urgency":"MEDIUM","needs_human":true,"summary":"Insufficient detail"}

Valid example:
{"urgency":"HIGH","needs_human":false,"summary":"Payment double-charged on invoice"}

Parser-Friendly Rules

Do

Show a minimal valid example.
List enums exhaustively.
State “JSON only, no markdown.”

Don’t

Allow optional mystery fields.
Mix prose and JSON casually.
Trust the model without schema checks.

Common Misconception

“If I ask for JSON, I will always get valid JSON.” Models still emit wrappers and typos. Treat format specs as necessary but not sufficient—validate and retry.

Knowledge Check

Short Answer: What is an output format specification? Answer: An explicit contract for response shape, types, and packaging.
True/False: Asking for JSON guarantees valid JSON. Answer: False.
Multiple Choice: Trailing commentary often breaks: (a) JSON parsers, (b) convolution, (c) batch norms. Answer: (a).
Short Answer: Name one item in the format checklist. Answer: Shape / fields / packaging / errors / validate.
True/False: Few-shot examples should match the live schema. Answer: True.
Multiple Choice: Enums should be: (a) exhaustive in the spec, (b) secret, (c) infinite always. Answer: (a).
Short Answer: What should code do on invalid output? Answer: Reject / repair / retry per policy.
Short Answer: When is Markdown a better format than JSON? Answer: Human-facing documents with sections.
Multiple Choice: Mystery optional fields make parsers: (a) more brittle, (b) faster GPUs, (c) unnecessary. Answer: (a).
True/False: Format specs belong in templates and docs. Answer: True.

Key Takeaways

Write format contracts: shape, fields, packaging, errors.
Ban preambles that break machines.
Validate in code; retry on failure.
Keep examples synchronized with the schema.
Next: Prompt Documentation.

Trainer’s Guide

Hands-on idea: Students write a JSON schema and a prompt; run 20 samples through a validator and compute pass rate.

Discussion prompt: Native structured-output APIs vs prompt-only JSON—when do you still need both?

Recap: Formats are contracts enforced by parsers. Finish the module with Prompt Documentation.