Claude Structured Output with tool_use and JSON Schema

Structured extraction is a whole exam scenario. You need to know how to guarantee valid JSON, how to design schemas that don’t push Claude to invent data, and when a retry will — and won’t — fix a problem (Task Statements 4.3 and 4.4).

🛠️ tool_use as the structured-output mechanism

Define an “extraction tool” whose input_schema is your output schema. Claude’s tool call arguments are your structured data — syntactically valid and schema-compliant.

{
  "name": "record_invoice",
  "description": "Record fields extracted from ONE supplier invoice.",
  "input_schema": {
    "type": "object",
    "properties": {
      "vendor": {"type": "string"},
      "invoice_date": {"type": ["string", "null"], "description": "ISO-8601; null if absent"},
      "po_number": {"type": ["string", "null"]},
      "category": {"type": "string", "enum": ["hardware", "software", "services", "other", "unclear"]},
      "category_detail": {"type": ["string", "null"]},
      "stated_total": {"type": "number"},
      "calculated_total": {"type": "number"},
      "conflict_detected": {"type": "boolean"}
    },
    "required": ["vendor", "category", "stated_total", "calculated_total", "conflict_detected"]
  }
}

📏 Schema design rules

• Nullable for possibly-absent data. A required field the document doesn’t contain pushes the model to fabricate a value.
• Enum + “other” + detail string for extensible categories, and “unclear” for genuinely ambiguous cases.
• Self-check fields such as calculated_total next to stated_total, plus conflict_detected.
• Format rules in the prompt (dates to ISO-8601, amounts as numbers) alongside the schema.

🔁 Validation and retry loops

When validation fails, send a follow-up with the original document, the failed extraction and the specific validation error.

In review pipelines, add a detected_pattern field to findings so you can analyse which code constructs developers keep dismissing.

🧪 Exam-Style Practice Questions

Try these before opening the answers. They use the same scenario style as the real exam.

Question 1. Which schema design reduces fabrication?

• A. Make fields that may be missing from the source nullable or optional
• B. Remove all enums
• C. Make every field required
• D. Use free-text fields only

Question 2. What can a retry with validation-error feedback **not** fix?

• A. A value that doesn't exist anywhere in the provided document
• B. A date in the wrong format
• C. A string where a number was expected
• D. A missing required key

Question 3. Why use tool_use with a JSON schema for extraction?

• A. It reliably produces schema-compliant, syntactically valid structured output
• B. It removes the need for validation
• C. It's cheaper than text
• D. It makes outputs semantically correct

📝 Assignment

Do these tasks in order. Each one has a Done when check, so you know when it is complete. The stretch task is optional but close to what the exam expects from an architect. Keep your answers in one notes file or Git repository, and revisit them in your final week of revision together with the cheat sheet in the last lesson of this course.

1. Task 1: Define an extraction tool with one nullable field and an enum with other and unclear values.
   ✅ Done when: Your schema has a nullable field, an enum containing other and unclear, and a detail string for the other value.
2. Task 2: Process a document missing one field and confirm you get null, not a made-up value.
   ✅ Done when: The missing field comes back as null in three runs out of three.
3. Stretch: build a validation-retry loop that sends the document, the failed output and the exact error.
   ✅ Done when: A deliberately wrong date format is corrected on the retry, and your log shows the exact error you sent back.

❓ Frequently Asked Questions

🤔 How do I guarantee valid JSON from Claude?

Define a tool whose input schema is your output schema and read Claude's tool_use arguments.

🤔 Does a JSON schema guarantee correct data?

No. It stops syntax errors, but values can still be wrong, such as totals that don't add up.

🤔 Why make fields nullable?

A required field that is missing from the document pushes the model to invent a value.

🤔 When does retrying fail?

When the information is not in the provided source. Return null and route the document to a human.

🏁 Summary

• tool_use + JSON schema = reliable structure; validate semantics separately.
• Nullable fields prevent fabrication; enum “other” + detail keeps categories extensible.
• Retry with specific feedback for format errors; never retry missing information.

Next, continue with Claude Message Batches API and Multi-Pass Review Design.

Independent study material by SQA Tools. Not affiliated with, endorsed by or sponsored by Anthropic. Claude is a trademark of Anthropic. Mock questions are original practice items, not real exam content. Exam facts checked against Anthropic's official exam guides and certification FAQ on 11 November 2026.