Using Structured Output

Structured output ensures that model inference returns data in a predictable format you can parse programmatically. By providing a JSON Schema, you constrain the model to return valid JSON matching your specification.

Prerequisites

Familiarity with Running Model Inference
Basic understanding of JSON Schema

Why structured output matters

Without structured output, LLM responses are free-form text that requires parsing and error handling. With structured output:

Without Schema	With Schema
Free-form text response	Guaranteed JSON structure
Manual parsing required	Direct property access
Inconsistent formats	Consistent field names and types
Runtime type errors	TypeScript type safety

Defining a schema

The output_format_schema field accepts a JSON Schema object that defines your expected response structure:

const job = await api.runModelInference({
  data_plane_id: 'dp_your_data_plane_id',
  model: 'anthropic.claude-sonnet-4.5',
  messages: [
    {
      role: 'user',
      content: [{ type: 'text', text: 'Classify this text: "Great product, fast shipping!"' }]
    }
  ],
  inference_config: {
    output_format_schema: {
      type: 'object',
      properties: {
        sentiment: {
          type: 'string',
          enum: ['positive', 'negative', 'neutral']
        },
        confidence: {
          type: 'number',
          minimum: 0,
          maximum: 1
        }
      },
      required: ['sentiment', 'confidence']
    }
  }
});

The model will return:

{
  "sentiment": "positive",
  "confidence": 0.95
}

Handling schema-validation misses

After the model responds, the platform validates the payload against output_format_schema. If validation fails, the job still completes — the non-conforming payload is preserved on failed_structured_output instead of structured_output, so downstream steps run and you can decide how to handle it:

const result = completedJob.result;

if (result.failed_structured_output) {
  // The model returned JSON that did not match the schema. Log or retry.
  console.warn(
    'Schema validation failed:',
    result.failed_structured_output.message
  );
  console.warn('Raw model output:', result.failed_structured_output.raw_output);
  return;
}

// Safe to consume the typed output.
const output = result.structured_output;

structured_output and failed_structured_output are mutually exclusive — at most one is populated on a completed job. Always check failed_structured_output before reading structured_output in code paths where a schema miss is possible.

Common schema patterns

Simple object with required fields

const schema = {
  type: 'object',
  properties: {
    title: { type: 'string' },
    description: { type: 'string' },
    priority: { type: 'integer', minimum: 1, maximum: 5 }
  },
  required: ['title', 'description']
};

Arrays of items

const schema = {
  type: 'object',
  properties: {
    categories: {
      type: 'array',
      items: { type: 'string' },
      minItems: 1,
      maxItems: 5
    }
  },
  required: ['categories']
};

Nested objects

const schema = {
  type: 'object',
  properties: {
    analysis: {
      type: 'object',
      properties: {
        summary: { type: 'string' },
        key_points: {
          type: 'array',
          items: { type: 'string' }
        }
      },
      required: ['summary', 'key_points']
    },
    metadata: {
      type: 'object',
      properties: {
        word_count: { type: 'integer' },
        language: { type: 'string' }
      }
    }
  },
  required: ['analysis']
};

Enum constraints

const schema = {
  type: 'object',
  properties: {
    category: {
      type: 'string',
      enum: ['retail', 'finance', 'healthcare', 'technology', 'other']
    },
    data_type: {
      type: 'string',
      enum: ['pii', 'aggregated', 'anonymous']
    }
  },
  required: ['category', 'data_type']
};

Array of typed objects

const schema = {
  type: 'object',
  properties: {
    entities: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          type: { type: 'string', enum: ['person', 'organization', 'location'] },
          confidence: { type: 'number' }
        },
        required: ['name', 'type']
      }
    }
  },
  required: ['entities']
};

TypeScript integration

Define TypeScript interfaces that match your schema for type-safe access:

// Define the interface matching your schema
interface ClassificationResult {
  category: 'retail' | 'finance' | 'healthcare' | 'technology' | 'other';
  confidence: number;
  reasoning: string;
  tags: string[];
}

// Define the schema (must match the interface)
const schema = {
  type: 'object',
  properties: {
    category: {
      type: 'string',
      enum: ['retail', 'finance', 'healthcare', 'technology', 'other']
    },
    confidence: { type: 'number', minimum: 0, maximum: 1 },
    reasoning: { type: 'string' },
    tags: { type: 'array', items: { type: 'string' } }
  },
  required: ['category', 'confidence', 'reasoning', 'tags']
};

// Submit the request
const job = await api.runModelInference({
  data_plane_id: 'dp_your_data_plane_id',
  model: 'anthropic.claude-sonnet-4.5',
  messages: [
    { role: 'user', content: [{ type: 'text', text: 'Classify this dataset...' }] }
  ],
  inference_config: { output_format_schema: schema }
});

// After polling for completion, cast the result
import { ModelInferenceRunResult } from '@narrative.io/data-collaboration-sdk-ts';

const result = completedJob.result as ModelInferenceRunResult<ClassificationResult>;

// Now you have full type safety
const category: string = result.structured_output.category;  // 'retail' | 'finance' | ...
const confidence: number = result.structured_output.confidence;
const tags: string[] = result.structured_output.tags;

Handling optional fields

Use required array to specify which fields must be present:

const schema = {
  type: 'object',
  properties: {
    title: { type: 'string' },           // Required
    subtitle: { type: 'string' },        // Optional
    author: { type: 'string' },          // Optional
    published_date: { type: 'string' }   // Required
  },
  required: ['title', 'published_date']  // Only these are required
};

// TypeScript interface
interface ArticleInfo {
  title: string;
  subtitle?: string;
  author?: string;
  published_date: string;
}

Validating responses

While the model is constrained to the schema, you may want additional runtime validation:

function validateResult<T>(
  result: ModelInferenceRunResult<T>,
  validate: (output: T) => boolean
): T | null {
  const output = result.structured_output;

  if (!validate(output)) {
    console.error('Validation failed for output:', output);
    return null;
  }

  return output;
}

// Usage
const validated = validateResult(result, (output: ClassificationResult) => {
  return output.confidence >= 0.5 && output.tags.length > 0;
});

if (validated) {
  console.log('Valid classification:', validated.category);
}

Best practices

Practice	Description
Keep schemas focused	Define only the fields you need
Use enums for known values	Constrain strings to valid options
Set numeric bounds	Use `minimum`/`maximum` for numbers
Make fields required explicitly	Don’t rely on defaults
Match TypeScript interfaces	Keep schema and types in sync
Add descriptions	Help the model understand field purpose

Adding descriptions for clarity

const schema = {
  type: 'object',
  properties: {
    sentiment: {
      type: 'string',
      enum: ['positive', 'negative', 'neutral'],
      description: 'Overall sentiment of the text'
    },
    confidence: {
      type: 'number',
      minimum: 0,
      maximum: 1,
      description: 'Confidence score from 0 (uncertain) to 1 (certain)'
    },
    key_phrases: {
      type: 'array',
      items: { type: 'string' },
      description: 'Most important phrases that influenced the sentiment'
    }
  },
  required: ['sentiment', 'confidence', 'key_phrases']
};

Troubleshooting

Issue	Cause	Solution
Missing required fields	Schema mismatch or unclear prompt	Verify required array, improve prompt
Wrong types	Schema not enforced	Check property types match expectations
Empty arrays	Model unsure what to include	Add `minItems` or clearer prompt
Enum violations	Value not in enum list	Verify enum covers all possibilities

JSON Schema Reference

Supported JSON Schema features

Running Model Inference

Complete inference guide

Model Inference API

API reference with all types

Structured Output Concepts

Why structured output matters

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Why structured output matters

Defining a schema

Handling schema-validation misses

Common schema patterns

Simple object with required fields

Arrays of items

Nested objects

Enum constraints

Array of typed objects

TypeScript integration

Handling optional fields

Validating responses

Best practices

Adding descriptions for clarity

Troubleshooting

JSON Schema Reference

Running Model Inference

Model Inference API

Structured Output Concepts

​Prerequisites

​Why structured output matters

​Defining a schema

​Handling schema-validation misses

​Common schema patterns

​Simple object with required fields

​Arrays of items

​Nested objects

​Enum constraints

​Array of typed objects

​TypeScript integration

​Handling optional fields

​Validating responses

​Best practices

​Adding descriptions for clarity

​Troubleshooting

​Related content

JSON Schema Reference

Running Model Inference

Model Inference API

Structured Output Concepts

Prerequisites

Why structured output matters

Defining a schema

Handling schema-validation misses

Common schema patterns

Simple object with required fields

Arrays of items

Nested objects

Enum constraints

Array of typed objects

TypeScript integration

Handling optional fields

Validating responses

Best practices

Adding descriptions for clarity

Troubleshooting

Related content