Prefill and Guaranteed Structured Output

Seeding the start of Claude's response to force format, and the difference between asking for JSON and actually constraining it.

Prompt Engineering·Lesson 4 of 6·8 min

Two mechanisms let you control response format at the API level rather than relying on the model to follow prose instructions: prefill and structured/constrained output. The exam distinguishes them clearly, and conflating them is a common mistake.

Prefill

Prefill means you supply the beginning of the assistant's response yourself, in the messages array, as an assistant-role message with partial content, and the model continues from there. A common use is starting the assistant turn with a literal { so the model has no room to add a conversational preamble like "Sure, here's the JSON you requested:" before the actual object. This is a cheap, low-effort way to eliminate an entire class of formatting failures (preamble text, markdown code fences around JSON, apologetic hedging) without adding any instructions or examples.

Prefill nudges the model toward a format; it does not enforce a schema. The model can still prefill-continue into malformed or incomplete JSON, wrong field names, or the wrong data types. It reduces one specific failure mode (extra text around the payload) but is not validation.

Actually constraining output vs. asking nicely

"Ask nicely for JSON" means putting instructions in the prompt like "respond only with valid JSON matching this schema" — this relies entirely on the model's compliance and can fail, especially under edge-case inputs. Actually constraining output means using a mechanism, such as a tool/function-call definition with a strict input schema, or a structured-output feature, where the response is generated to conform to a schema rather than merely asked to. Downstream code parsing model output should be built assuming "asked nicely" can fail; a genuinely constrained schema is far more reliable for code that cannot tolerate a parse error.

A common real pattern: define a tool with a JSON schema for the exact fields you want, and force the model to call that tool, even though you have no intention of "executing" anything — the tool-call mechanism itself is being used purely to get schema-conformant output.

Exam trap A question shows a prompt with the instruction "return only valid JSON, no other text" and asks why production code still occasionally throws a JSON parse error. The trap answer is "the instruction should be reworded to be more forceful." The correct diagnosis is that a prose instruction is being relied upon as if it were a guarantee — the fix is to move to an actual schema-constraining mechanism (tool-call schema) and/or add prefill, and code should also validate before trusting the output regardless.

A pipeline extracts structured line items from invoices and feeds them directly into an accounting system with no human review. The team is currently prompting "respond with a JSON array of objects with fields item, quantity, price" and parsing the raw text response. Occasional malformed responses break the pipeline. The correct fix is to define a tool with a strict schema for the line-item array and force a tool call, rather than continuing to refine the prose instruction — because this is a non-interactive, unattended path where a parse failure has real downstream cost, so relying on the model to voluntarily comply with a text instruction is the wrong tradeoff.

Prefill beyond JSON

Prefill is not limited to forcing JSON. It also works for forcing a specific opening structure in free text — for example, prefilling "Verdict: " to force the model to lead with a classification before any explanation, or prefilling the first line of a multi-section report to lock in the section header format. The underlying mechanism is the same in every case: whatever text you supply becomes the literal start of the assistant's response, so the model has no opportunity to deviate from it, only to continue from it.

Combining prefill with schema constraints

Prefill and schema-constrained output are not competing choices — they stack. Forcing a tool call gets you a response shaped by a schema; prefill (where applicable to the surrounding response) removes any remaining preamble around it. On the exam, watch for scenarios that ask you to pick "the one best fix" when the real answer is that these techniques address different failure modes and are commonly used together rather than as alternatives to choose between.

Structured output still needs downstream validation

Even a strict schema only constrains shape and type — it typically cannot express business-rule constraints like "end_date must be after start_date" or "discount must not exceed the customer's tier limit." A response can satisfy the schema perfectly and still be wrong in a way that matters to your application. Structured output reduces parsing failures; it does not eliminate the need for application-level validation, which is the subject of the next lesson.

Try it

Take a prompt where you currently ask for JSON in prose. Run 10 varied inputs against it and count parse failures or preamble text. Then run the same 10 inputs with the assistant turn prefilled with a bare {, and separately with a tool-call schema forcing structured output. Compare failure rates across all three approaches, and note which failures each fix does and does not address.