Structured Outputs That Don't Break

When you're building applications with AI, you need predictable output formats. A prompt that sometimes returns JSON and sometimes returns prose is useless for automation.

**The Problem:** - AI models are trained on natural language, not strict formats - Without constraints, outputs are inconsistent - Parsing failures crash your applications

**The Solution:** - Explicit format instructions - Schema definitions - Validation patterns

The most reliable way to get structured JSON is to provide both the schema AND an example.

**Template:** ``` You are a data extraction assistant. Extract information from the text below and return ONLY valid JSON matching this exact schema:

{ "name": string, "email": string | null, "topics": string[], "sentiment": "positive" | "negative" | "neutral" }

Example output: { "name": "John Doe", "email": "john@example.com", "topics": ["pricing", "features"], "sentiment": "positive" }

Text to analyze: {{input_text}}

Return ONLY the JSON object, no other text. ```

**Why this works:** 1. Clear role definition 2. Exact schema with types 3. Concrete example 4. Explicit "no other text" instruction

Complex structures need more explicit constraints.

**For arrays:** ``` Return an array of exactly 5 items. Each item must have: - id: unique integer starting from 1 - title: string, max 50 characters - priority: "high" | "medium" | "low"

Format: [{"id": 1, "title": "...", "priority": "..."}, ...] ```

**For nested objects:** ``` Return a JSON object with this structure: { "user": { "profile": { "name": string, "age": number }, "settings": { "theme": string, "notifications": boolean } }, "metadata": { "created": ISO8601 date string } } ```

**Pro tip:** Always specify the exact number of items when possible. "Return 3-5 items" is better than "return some items."

Even perfect prompts can produce invalid output. Build in validation.

**Client-side validation:** ```typescript function parseAIResponse(response: string) { // Strip markdown code blocks if present const cleaned = response .replace(/```json\n?/g, '') .replace(/```\n?/g, '') .trim(); try { const parsed = JSON.parse(cleaned); // Validate against your schema if (!parsed.name || typeof parsed.name !== 'string') { throw new Error('Invalid name field'); } return { success: true, data: parsed }; } catch (e) { return { success: false, error: e.message, raw: response }; } } ```

**Retry pattern:** If parsing fails, send a follow-up prompt: ``` Your previous response was not valid JSON. The error was: {{error}}

Please try again, returning ONLY the JSON object with no markdown formatting. ```

Different models have different quirks with structured output.

**GPT-4/5:** - Use `response_format: { type: "json_object" }` when available - Very reliable with explicit schemas - Sometimes adds helpful comments - use "no explanations" instruction

**Claude:** - Excellent at following exact formats - Use XML tags for complex structures: `<json>...</json>` - Responds well to "be precise" instructions

**Gemini:** - Include "respond in JSON format" in system prompt - More likely to add markdown code blocks - always strip them - Benefits from numbered step instructions

**LLaMA/Open Source:** - Be extra explicit about format - Include multiple examples - Use simpler schemas when possible

Now it's your turn. Use the JSON Builder lab to create a structured output prompt.

**Your challenge:** 1. Define a schema for extracting product information 2. Include: name, price, category, features (array), inStock (boolean) 3. Test with sample product descriptions 4. Handle edge cases (missing data, invalid formats)

The lab will guide you through each step and let you test with real AI.