Claude API - Structured Outputs & Error Prevention Guide

Package: @anthropic-ai/[email protected] Breaking Changes: Oct 2025 - Claude 3.5/3.7 models retired, Nov 2025 - Structured outputs beta Last Updated: 2026-01-09

What's New in v0.69.0+ (Nov 2025)

Major Features:

1. Structured Outputs (v0.69.0, Nov 14, 2025) - CRITICAL ⭐

Guaranteed JSON schema conformance - Claude's responses strictly follow your JSON schema with two modes.

⚠️ ACCURACY CAVEAT: Structured outputs guarantee format compliance, NOT accuracy. Models can still hallucinate—you get "perfectly formatted incorrect answers." Always validate semantic correctness (see below).

JSON Outputs (output_format) - For data extraction and formatting:

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Extract contact info: John Doe, [email protected], 555-1234' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: {
      name: 'Contact',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          email: { type: 'string' },
          phone: { type: 'string' }
        },
        required: ['name', 'email', 'phone'],
        additionalProperties: false
      }
    }
  }
});

// Guaranteed valid JSON matching schema
const contact = JSON.parse(message.content[0].text);
console.log(contact.name); // "John Doe"

Strict Tool Use (strict: true) - For validated function parameters:

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Get weather for San Francisco' }],
  betas: ['structured-outputs-2025-11-13'],
  tools: [{
    name: 'get_weather',
    description: 'Get current weather',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location'],
      additionalProperties: false
    },
    strict: true  // ← Guarantees schema compliance
  }]
});

Requirements:

• Beta header: structured-outputs-2025-11-13 (via betas array)
• Models: Claude Opus 4.5, Claude Sonnet 4.5, Claude Opus 4 (best models only)
• SDK: v0.69.0+ required

Limitations:

• ❌ No recursive schemas
• ❌ No numerical constraints (minimum, maximum)
• ❌ Limited regex support (no backreferences/lookahead)
• ❌ Incompatible with citations and message prefilling
• ⚠️ Grammar compilation adds latency on first request (cached 24hrs)

Performance Characteristics:

• First request: +200-500ms latency for grammar compilation
• Subsequent requests: Normal latency (grammar cached for 24 hours)
• Cache sharing: Only with IDENTICAL schemas (small changes = recompilation)

Pre-warming critical schemas:

// Pre-compile schemas during server startup
const warmupMessage = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 10,
  messages: [{ role: 'user', content: 'warmup' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: YOUR_CRITICAL_SCHEMA
  }
});
// Later requests use cached grammar

Semantic Validation (CRITICAL):

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: [{ role: 'user', content: 'Extract contact: John Doe' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: contactSchema
  }
});

const contact = JSON.parse(message.content[0].text);

// ✅ Format is guaranteed valid
// ❌ Content may be hallucinated

// ALWAYS validate semantic correctness
if (!isValidEmail(contact.email)) {
  throw new Error('Hallucinated email detected');
}
if (contact.age < 0 || contact.age > 120) {
  throw new Error('Implausible age value');
}

When to Use:

• Data extraction from unstructured text
• API response formatting
• Agentic workflows requiring validated tool inputs
• Eliminating JSON parse errors

⚠️ SDK v0.71.1+ Deprecation: Direct .parsed property access is deprecated. Check SDK docs for updated API.

2. Model Changes (Oct 2025) - BREAKING

Retired (return errors):

• ❌ Claude 3.5 Sonnet (all versions)
• ❌ Claude 3.7 Sonnet - DEPRECATED (Oct 28, 2025)

Active Models (Jan 2026):

Note: Claude 3.x models (3.5 Sonnet, 3.7 Sonnet, etc.) are deprecated. Use Claude 4.x+ models.

3. Context Management (Oct 28, 2025)

Clear Thinking Blocks - Automatic thinking block cleanup:

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Solve complex problem' }],
  betas: ['clear_thinking_20251015']
});
// Thinking blocks automatically managed

4. Agent Skills API (Oct 16, 2025)

Pre-built skills for Office files