Structured Outputs

core-ai generates structured outputs from a schema you provide. Pass a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, to get a validated object with full TypeScript type inference. Pass plain JSON Schema to get the parsed JSON and validate it yourself.

Generate Structured Objects

Use generateObject() to get validated JSON responses:

import { generateObject } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';
import { z } from 'zod';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

const weatherSchema = z.object({
  city: z.string(),
  temperatureC: z.number(),
  summary: z.string(),
});

const result = await generateObject({
  model,
  messages: [
    {
      role: 'user',
      content: 'Return a weather report for Berlin as structured JSON.',
    },
  ],
  schema: weatherSchema,
  schemaName: 'weather_report',
  schemaDescription: 'A structured weather report object.',
});

// result.object is fully typed!
console.log('City:', result.object.city);
console.log('Temperature:', result.object.temperatureC);
console.log('Summary:', result.object.summary);

Stream Structured Objects

Stream JSON as it’s being generated:

import { streamObject } from '@core-ai/core-ai';
import { z } from 'zod';

const extractSchema = z.object({
  headline: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
  tags: z.array(z.string()),
});

const result = await streamObject({
  model,
  messages: [
    {
      role: 'user',
      content: 'Analyze this sentence and return JSON only: "core-ai makes provider integration easier."',
    },
  ],
  schema: extractSchema,
  schemaName: 'text_analysis',
  schemaDescription: 'Structured text analysis output.',
});

for await (const event of result) {
  if (event.type === 'object-delta') {
    process.stdout.write(event.text);
    continue;
  }

  if (event.type === 'object') {
    console.log('\n\nValidated object:', event.object);
  }
}

const response = await result.result;
console.log('\nFinal object:', response.object);
console.log('Finish reason:', response.finishReason);

Schemas

schema accepts two kinds of schemas. Tool parameters accept the same two kinds.

Schema	JSON Schema	Validated by core-ai	`object` type
Standard Schema with JSON Schema support	Converted from the schema’s input type	Yes	The schema’s output type
Plain JSON Schema	Used as is	No	`unknown`

core-ai converts a Standard Schema with its ~standard.jsonSchema.input() method (draft 2020-12), once per schema object. Because the input type is converted, transforms such as z.string().transform(Number) work, and object holds their output. A schema that cannot be converted, such as one containing z.date(), throws a ValidationError before any provider call. Call toJsonSchema() to see the JSON Schema core-ai sends.

Supported libraries

Library	Version	Notes
Zod	4.2+	Not `zod/mini`
ArkType	2.1.28+
Joi	18.1+
VineJS	4.3+
Valibot	With `@valibot/to-json-schema` 1.5+	Wrap schemas with `toStandardJsonSchema()`
Effect Schema	4+	Wrap schemas with its Standard JSON Schema functions

Libraries without Standard JSON Schema support, such as TypeBox, Yup, Superstruct, io-ts, zod/mini, and Zod before 4.2, work through plain JSON Schema. Pass the JSON Schema they produce, for example z.toJSONSchema(schema) for an older Zod version, and validate the result with the library yourself.

Plain JSON Schema

core-ai uses plain JSON Schema as is and never validates the output against it. object is the parsed JSON, typed unknown:

import { generateObject } from '@core-ai/core-ai';

const result = await generateObject({
  model,
  messages: [{ role: 'user', content: 'Return a weather report for Berlin.' }],
  schema: {
    type: 'object',
    properties: {
      city: { type: 'string' },
      temperatureC: { type: 'number' },
    },
    required: ['city', 'temperatureC'],
    additionalProperties: false,
  },
});

const report: unknown = result.object; // validate before use

core-ai does not ship a JSON Schema validator. To have core-ai validate the output, wrap your validator, such as Ajv, in the Standard Schema interface (see JSON Schema tools for an example).

Object stream events

The streamObject() function returns an ObjectStream — an async iterable with .result and .events. It emits these event types:

type ObjectStreamEvent<TSchema extends SchemaInput> =
  | { type: 'object-delta'; text: string }                 // Raw JSON text chunks
  | { type: 'object'; object: InferSchemaOutput<TSchema> } // Final object
  | { type: 'finish'; finishReason: FinishReason; usage: ChatUsage };

The object event is emitted once, when the full object payload has been parsed and, for a Standard Schema, validated. object-delta events carry raw, unvalidated text. Use them for progressive UI updates while JSON is still streaming.

Complex Schema Examples

OpenAI and Anthropic structured outputs accept only closed objects, so they reject open objects such as z.record() or .catchall(). Model key/value data as an array of objects instead.

Nested Objects
Arrays
Unions and Discriminated Types
Optional and Default Values

import { generateObject } from '@core-ai/core-ai';
import { z } from 'zod';

const userProfileSchema = z.object({
  name: z.string(),
  age: z.number(),
  address: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string(),
  }),
  skills: z.array(z.string()),
});

const result = await generateObject({
  model,
  messages: [{
    role: 'user',
    content: 'Create a sample user profile for a software engineer in Berlin.',
  }],
  schema: userProfileSchema,
});

console.log(result.object.name);
console.log(result.object.address.city);
console.log(result.object.skills);

const taskListSchema = z.object({
  tasks: z.array(
    z.object({
      id: z.number(),
      title: z.string(),
      priority: z.enum(['low', 'medium', 'high']),
      completed: z.boolean(),
      tags: z.array(z.string()),
    })
  ),
  totalCount: z.number(),
});

const result = await generateObject({
  model,
  messages: [{
    role: 'user',
    content: 'Generate 5 sample tasks for a project management app.',
  }],
  schema: taskListSchema,
});

result.object.tasks.forEach((task) => {
  console.log(`${task.id}. ${task.title} [${task.priority}]`);
});

const notificationSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('email'),
    to: z.string().email(),
    subject: z.string(),
    body: z.string(),
  }),
  z.object({
    type: z.literal('sms'),
    phoneNumber: z.string(),
    message: z.string(),
  }),
  z.object({
    type: z.literal('push'),
    deviceId: z.string(),
    title: z.string(),
    body: z.string(),
  }),
]);

const result = await generateObject({
  model,
  messages: [{
    role: 'user',
    content: 'Create an email notification about a password reset.',
  }],
  schema: notificationSchema,
});

if (result.object.type === 'email') {
  console.log('Email to:', result.object.to);
  console.log('Subject:', result.object.subject);
}

const configSchema = z.object({
  name: z.string(),
  enabled: z.boolean().default(true),
  timeout: z.number().optional(),
  settings: z.object({
    theme: z.enum(['light', 'dark']).default('light'),
    language: z.string().default('en'),
  }).optional(),
});

const result = await generateObject({
  model,
  messages: [{
    role: 'user',
    content: 'Create a configuration for a web application.',
  }],
  schema: configSchema,
});

console.log(result.object);

Schema Descriptions

Add descriptions to help the model understand your schema:

const productSchema = z.object({
  name: z.string().describe('The product name'),
  price: z.number().describe('Price in USD'),
  category: z.enum(['electronics', 'clothing', 'food'])
    .describe('Product category'),
  inStock: z.boolean().describe('Whether the product is currently available'),
  tags: z.array(z.string()).describe('Relevant tags for searching'),
});

const result = await generateObject({
  model,
  messages: [{
    role: 'user',
    content: 'Create a product listing for a wireless keyboard.',
  }],
  schema: productSchema,
  schemaName: 'product',
  schemaDescription: 'A product listing with name, price, and metadata.',
});

Type Inference

result.object is typed with the Standard Schema’s output type (InferSchemaOutput<TSchema>). For plain JSON Schema it is unknown.

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'guest']),
});

// Type is automatically inferred!
type User = z.infer<typeof userSchema>;
// { id: number; name: string; email: string; role: 'admin' | 'user' | 'guest' }

const result = await generateObject({
  model,
  messages: [{ role: 'user', content: 'Create a user' }],
  schema: userSchema,
});

// result.object is typed as User
const user: User = result.object;

Error Handling

generateObject() and streamObject() throw these structured output errors:

StructuredOutputValidationError when the output does not match a Standard Schema. issues lists the schema library’s messages as path.to.key: message. When the schema’s validator throws instead, such as a transform calling new URL(), its error is the cause.
StructuredOutputParseError when the output is not valid JSON.
StructuredOutputNoObjectGeneratedError when the model returns no object.

Plain JSON Schema output is never validated, so it raises only the parse and no-object errors.

import {
  StructuredOutputError,
  StructuredOutputValidationError,
  StructuredOutputParseError,
} from '@core-ai/core-ai';

try {
  const result = await generateObject({
    model,
    messages,
    schema: mySchema,
  });

  console.log(result.object);
} catch (error) {
  if (error instanceof StructuredOutputValidationError) {
    console.error('Validation failed:', error.message);
    console.error('Validation errors:', error.issues);
  } else if (error instanceof StructuredOutputParseError) {
    console.error('Failed to parse JSON:', error.message);
    console.error('Raw output:', error.rawOutput);
  } else if (error instanceof StructuredOutputError) {
    console.error('Structured output error:', error.message);
  }
}

Streaming with UI Updates

Update your UI as the object is built:

import { streamObject } from '@core-ai/core-ai';
import { z } from 'zod';

const recipeSchema = z.object({
  title: z.string(),
  ingredients: z.array(z.string()),
  instructions: z.array(z.string()),
  prepTime: z.number(),
  cookTime: z.number(),
});

const result = await streamObject({
  model,
  messages: [{ role: 'user', content: 'Give me a pasta recipe' }],
  schema: recipeSchema,
});

for await (const event of result) {
  if (event.type === 'object-delta') {
    updateRecipePreview(event.text);
    continue;
  }

  if (event.type === 'object') {
    // event.object contains the final validated object
    updateRecipeUI(event.object);
    console.log('Title:', event.object.title);
    console.log('Ingredients:', event.object.ingredients.length);
  }
}

const response = await result.result;
console.log('Complete recipe:', response.object);

Configuration Options

Customize structured output generation:

const result = await generateObject({
  model,
  messages,
  schema: mySchema,
  schemaName: 'my_object',
  schemaDescription: 'A description',
  temperature: 0.3,
  maxTokens: 2000,
});

Best Practices

Use descriptive schema names and descriptions

Help the model understand what you want:

const result = await generateObject({
  model,
  messages,
  schema: z.object({
    name: z.string().describe('Full name of the person'),
    age: z.number().describe('Age in years'),
  }),
  schemaName: 'person',
  schemaDescription: 'A person with their basic information',
});

Use lower temperature for consistent structure

Reduce temperature for more predictable JSON structure:

const result = await generateObject({
  model,
  messages,
  schema: mySchema,
  temperature: 0.3,
});

Use object-delta for progressive updates

Build previews from raw JSON chunks, then switch to the validated object when it arrives:

for await (const event of result) {
  if (event.type === 'object-delta') {
    appendJsonPreview(event.text);
  }

  if (event.type === 'object') {
    renderFinalObject(event.object);
  }
}

Validate complex constraints

Add validation for constraints the schema does not express:

const result = await generateObject({
  model,
  messages,
  schema: mySchema,
});

// Additional business logic validation
if (result.object.startDate > result.object.endDate) {
  throw new Error('Start date must be before end date');
}

Next Steps

Chat Completion

Generate text responses without structure

Tool Calling

Combine structured outputs with tool calls

Streaming

Stream regular text responses

Standard Schema

Find schema libraries that implement Standard Schema

Get Started

Core Concepts

Guides

Observability

Examples

Structured Outputs

Generate Structured Objects

Stream Structured Objects

Schemas

Supported libraries

Plain JSON Schema

Object stream events

Complex Schema Examples

Schema Descriptions

Type Inference

Error Handling

Streaming with UI Updates

Configuration Options

Best Practices

Next Steps

Chat Completion

Tool Calling

Streaming

Standard Schema

​Generate Structured Objects

​Stream Structured Objects

​Schemas

​Supported libraries

​Plain JSON Schema

​Object stream events

​Complex Schema Examples

​Schema Descriptions

​Type Inference

​Error Handling

​Streaming with UI Updates

​Configuration Options

​Best Practices

​Next Steps

Chat Completion

Tool Calling

Streaming

Standard Schema

Generate Structured Objects

Stream Structured Objects

Schemas

Supported libraries

Plain JSON Schema

Object stream events

Complex Schema Examples

Schema Descriptions

Type Inference

Error Handling

Streaming with UI Updates

Configuration Options

Best Practices

Next Steps