Output Formatting

Why Output Format Matters

In production systems, you need to:

• Parse model output programmatically
• Validate that required fields exist
• Store data in databases
• Feed output to downstream systems

As Anthropic notes:

> "You want your piece of information to be stored in your SQL database. The fancy preamble is great, but you want the nitty-gritty information for your application."

Output Format Options

XML Output Format

Requesting XML Output

Provide your analysis in the following format:

<analysis>
  <summary>Brief overview of findings</summary>
  <details>
    <finding>First finding</finding>
    <finding>Second finding</finding>
  </details>
  <conclusion>Final determination</conclusion>
  <confidence>high/medium/low</confidence>
</analysis>

Real Example: Car Accident

Wrap your final determination in these tags:

<final_verdict>
  <fault>Vehicle A or Vehicle B</fault>
  <reasoning>Why this vehicle is at fault</reasoning>
  <evidence>
    <item>Checkbox evidence</item>
    <item>Sketch evidence</item>
  </evidence>
  <confidence>high/medium/low</confidence>
</final_verdict>

Parsing XML in Code

function parseVerdict(response) {
  const faultMatch = response.match(/<fault>(.*?)<\/fault>/);
  const confidenceMatch = response.match(/<confidence>(.*?)<\/confidence>/);

  return {
    fault: faultMatch ? faultMatch[1] : null,
    confidence: confidenceMatch ? confidenceMatch[1] : null
  };
}

JSON Output Format

Requesting JSON Output

Respond with a JSON object in this exact format:

{
  "sentiment": "positive" | "negative" | "neutral",
  "confidence": 0.0 to 1.0,
  "key_phrases": ["phrase1", "phrase2"],
  "summary": "Brief summary"
}

Output only the JSON, no additional text.

Complex JSON Structures

Analyze the product listing and return:

{
  "product": {
    "name": "string",
    "category": "string",
    "price": number
  },
  "quality_issues": [
    {
      "type": "string",
      "severity": "high" | "medium" | "low",
      "description": "string"
    }
  ],
  "recommendation": "approve" | "reject" | "needs_review"
}

Parsing JSON in Code

function parseAnalysis(response) {
  // Extract JSON from response (may have other text)
  const jsonMatch = response.match(/\{[\s\S]*\}/);
  if (!jsonMatch) return null;

  try {
    return JSON.parse(jsonMatch[0]);
  } catch (e) {
    console.error('Failed to parse JSON:', e);
    return null;
  }
}

Hybrid Formats

Sometimes you want both human-readable and parseable:

<response>
  <human_summary>
    The analysis shows that Vehicle B is at fault due to
    failure to yield at the intersection...
  </human_summary>

  <machine_data>
    <fault>B</fault>
    <fault_code>YIELD_VIOLATION</fault_code>
    <confidence>0.95</confidence>
  </machine_data>
</response>

Important Guidelines Section

Reinforce output format in guidelines:

<important_guidelines>
  <guideline>
    Always wrap your final answer in <final_verdict> tags.
  </guideline>
  <guideline>
    The summary must be clear, concise, and accurate.
  </guideline>
  <guideline>
    Include all required fields, even if empty.
  </guideline>
  <guideline>
    Do not include any text outside the specified tags.
  </guideline>
</important_guidelines>

Ensuring Format Compliance

1. Be Explicit

❌ "Format your response nicely"
✓ "Return a JSON object with these exact keys: ..."

2. Show Examples

Here's an example of the expected output:

<verdict>
  <fault>Vehicle A</fault>
  <confidence>high</confidence>
</verdict>

Now analyze the following and respond in the same format:

3. Validate in Code

function validateOutput(response) {
  const required = ['fault', 'confidence', 'reasoning'];
  const parsed = parseResponse(response);

  for (const field of required) {
    if (!parsed[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }

  return parsed;
}

4. Handle Failures Gracefully

async function getAnalysis(input) {
  const response = await claude.complete(prompt + input);

  try {
    return parseAndValidate(response);
  } catch (e) {
    // Retry with stricter formatting instruction
    const retry = await claude.complete(
      prompt + input + "\n\nIMPORTANT: Output ONLY the JSON, nothing else."
    );
    return parseAndValidate(retry);
  }
}

Production Best Practices

1. Separate Content from Metadata

<response>
  <metadata>
    <model>claude-3-sonnet</model>
    <timestamp>2025-01-15T10:30:00Z</timestamp>
    <confidence>0.92</confidence>
  </metadata>
  <content>
    <!-- The actual response content -->
  </content>
</response>

2. Include Error Handling

<response>
  <status>success | error | partial</status>
  <error_message>Only if status is error</error_message>
  <content>...</content>
</response>

3. Version Your Format

<response version="1.2">
  <!-- Allows backward compatibility -->
</response>

Key Takeaways

• Design for parsing - Structure output for programmatic extraction
• XML or JSON - Both work well, choose based on use case
• Be explicit - Specify exact format, don't assume
• Include examples - Show the expected output structure
• Validate and retry - Handle format failures gracefully
• Guidelines reinforce - Repeat format requirements at the end

Next Lesson

Next, we'll explore Pre-fill Responses - how to start the model's response to guide output format.