D4 · Prompt Engineering › Cluster 7 · Structured Outputs & JSON

7.2 · JSON via Prefill + Stop Sequence

The no-feature classic

CONCEPT The classic two-part trick

Before structured outputs existed, the standard way to coax clean JSON out of Claude with no feature at all combined two Messages-API mechanics:

  1. Prefill the opening brace. End your request with an assistant turn containing just {. Claude continues from that character, so it never emits a "Here's the JSON:" preamble — the very first token is already inside the object.
  2. Stop on the closing brace. Pass stop_sequences: ["}"]. The moment Claude would emit }, generation halts with stop_reason: "stop_sequence". The stop text itself is not included in the output, so you re-add the braces yourself when parsing.
🔑 stop_sequences is a plain Messages-API parameter (a list of strings). When one fires, stop_reason is "stop_sequence" and the matched string appears in response.stop_sequence — and is stripped from the generated text.

CONCEPT Prefill is now model-gated — know the caveat

⚠️ Assistant-turn prefill returns a 400 on current models (Fable 5, Opus 4.8 / 4.7 / 4.6, Sonnet 4.6). The prefill half of this trick therefore only runs on older models that still accept a trailing assistant message. On current models, use tool use (7.3) or the structured-outputs feature (7.4) instead.

The still-portable no-feature approach on any model is the second flavor: ask for JSON only and parse. Instruct "reply with only valid JSON, no prose", optionally add a stop sequence to trim any trailing chatter, then json.loads() the text with a try/except and a retry on failure.

DIAGRAM How the two mechanics combine

flowchart TD U["User request + schema hint"] --> PRE{"Model allows
assistant prefill?"} PRE -->|"older model: yes"| A["🟢 Prefill assistant turn with '{'
+ stop_sequences=['}']"] A --> OUT["Claude emits object body,
halts at '}' (stripped)"] OUT --> WRAP["Re-add braces → json.loads()"] PRE -->|"current model: no (400)"| B["🟠 Ask for JSON-only + parse
(or escalate to 7.3 / 7.4)"] B --> WRAP classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class A ok; class B gate;

CODE The classic trick vs. the portable fallback

# ── Classic prefill + stop (OLDER models only — 400 on 4.6/4.7/4.8/Fable 5) ──
resp = client.messages.create(
    model="claude-3-5-sonnet-20241022",   # a model that still allows prefill
    max_tokens=1024,
    stop_sequences=["}"],                     # halt at the closing brace
    messages=[
        {"role": "user", "content": "Extract name and email as JSON."},
        {"role": "assistant", "content": "{"},      # prefill the opening brace
    ],
)
# stop_reason == "stop_sequence"; braces are stripped, so wrap them back:
raw  = resp.content[0].text          # e.g.  "name": "Jane", "email": "j@co.com"
data = json.loads("{" + raw + "}")

# ── Portable fallback (ANY model): ask for JSON-only, then parse defensively ──
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    system="Reply with ONLY a valid JSON object. No prose, no code fences.",
    messages=[{"role": "user", "content": "Extract name and email as JSON."}],
)
try:
    data = json.loads(resp.content[0].text)
except json.JSONDecodeError:
    data = retry_or_repair(resp)      # re-ask, or escalate to 7.4
Do not run the prefill variant against Opus 4.8 / Sonnet 4.6 / Fable 5 — the trailing assistant turn is rejected before generation even starts.

TRADE-OFFS No-feature JSON vs. the real feature

✅ Prefill + stop / JSON-only

  • Zero setup — no schema, no beta, no compile step
  • Prefill kills the preamble on models that allow it
  • Portable JSON-only variant works everywhere

⚠️ The cost

  • Not guaranteed — output can still be malformed
  • You own parsing, validation, and retries
  • Prefill path is dead on current models
  • Nested } in strings can trip a naive ["}"] stop

EXAM TRAPS

Trap: "The stop sequence is part of the output." → It is not — the matched string is stripped from the text and reported separately in response.stop_sequence. That's why you re-add the closing brace.
Trap: Using prefill on Opus 4.8 / Sonnet 4.6 / Fable 5. → Those models reject a trailing assistant turn with a 400. Prefill is an older-model-only technique.
Trap: Treating this trick as a guarantee. → It's best-effort. When you need valid JSON every time, that's structured outputs (7.4) or strict tool use (7.3).
Trap: A bare stop_sequences=["}"] on nested JSON. → It fires on the first }, which may be inside a nested object — truncating the response. The trick suits flat objects; for nested shapes, prefer the JSON-only + parse variant.

PRACTICE

Q1 · Describe the classic no-feature JSON trick in two moves.

Prefill the assistant turn with { so Claude skips the preamble and starts inside the object, and set stop_sequences=["}"] so generation halts at the closing brace. Because the stop string is stripped, you re-wrap the result: json.loads("{" + text + "}").

Q2 · Why can't you use the prefill half on Claude Opus 4.8?

Assistant-turn prefill is not supported on Fable 5 and the 4.6/4.7/4.8 family — a trailing assistant message returns a 400. Use tool use, structured outputs, or a JSON-only system instruction instead.

Q3 · What is the portable, any-model version of this technique?

Instruct the model to "reply with only valid JSON, no prose", optionally add a stop sequence to trim trailing text, then json.loads() defensively with a try/except and a retry or repair path. It's still best-effort — escalate to structured outputs for a hard guarantee.