Module 8: Structured Output and Schema Design

Lesson 2: JSON Schema Fundamentals

To the Claude Certified Architect, a JSON Schema is not just a validation tool; it is a Prompt in Mathematical Form. Claude uses the schema to understand the "Boundary" of the response it's allowed to generate.

In this lesson, we master the fundamental building blocks of JSON Schema that are most relevant to AI outputs.

---

1. The "Type" Attribute (The Core)

Every property in your schema must have a type. This tells Claude which "World" of data it is in.

Common AI Types:

• string: For names, summaries, or descriptions.
• number / integer: For prices, counts, or IDs.
• boolean: For flags like is_urgent or has_error.
• array: For lists of items.
• object: For nested structures.

---

2. Nesting: Creating Hierarchy

Good architecture avoids "Flat" data. You should group related fields using the object type with its own properties.

• Flat (Bad): name, age, street, zip.
• Nested (Architect): name, age, address: {street, zip}.

Why Nest?

Because it allows you to provide a Global Description for the group.

• e.g., "The address object should represent the physical location where the event took place."

---

3. The "Properties" Object

Inside an object, the properties field is a dictionary where the Key is the field name and the Value is another schema.

"properties": {
  "user_name": { "type": "string" },
  "user_id": { "type": "integer" }
}

---

4. Metadata: title and description

While these are optional in standard JSON Schema, they are Mandatory in AI design.

• The description field is the "Local Prompt" that Claude reads to understand exactly what to put in that field.
• Never leave a property without a description.

---

5. Visualizing Schema Anatomy

graph TD
    S[Schema Object] --> T[Type: 'object']
    S --> P[Properties]
    P --> C1[Name: string]
    P --> C2[Age: integer]
    S --> R[Required: Array]

---

6. Summary

• Types define the data format.
• Properties define the data content.
• Nesting defines the data hierarchy.
• Descriptions define the data meaning.

In the next lesson, we look at how to enforce the existence of data: Required vs. Optional Fields.

---

Interactive Quiz

1. What is the most important "Optional" field in a JSON schema for an AI? (Hint: it helps with reasoning).
2. What is the difference between number and integer in JSON Schema?
3. Why should you nest related fields into objects?
4. Write a simple schema for a "Book" that has a title (string) and an author (object with first_name and last_name).

---

Reference Video: