> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ResponseSchema

> JSON schema types for constraining and validating LLM structured outputs.

## Overview

Response schema types define the structure that LLM outputs must conform to, enabling structured data extraction.

***

## ResponseSchema

JSON schema definition for constraining and validating LLM response format.

```typescript theme={null}
interface ResponseSchema {
  name: string;                    // pattern: ^[a-zA-Z0-9_]{1,64}$
  description: string;             // max 4096 chars
  strict?: boolean | null;
  schema: ResponseSchemaStructure;
}
```

**Properties**:

* `name` - Schema name (alphanumeric + underscore, 1-64 chars)
* `description` - Schema description (up to 4096 chars)
* `strict` - Whether to enforce strict schema adherence
* `schema` - The JSON schema structure

**Example**:

```typescript theme={null}
const responseSchema: ResponseSchema = {
  name: 'user_extraction',
  description: 'Extract user information from conversation',
  strict: true,
  schema: {
    type: 'object',
    required: ['name', 'email'],
    properties: {
      name: {
        type: 'string',
        description: 'User full name'
      },
      email: {
        type: 'string',
        description: 'Email address'
      },
      phone: {
        type: 'string',
        description: 'Phone number'
      }
    },
    additionalProperties: false
  }
};
```

**JSON**:

```json theme={null}
{
  "name": "user_info",
  "description": "Extract user information",
  "strict": true,
  "schema": {
    "type": "object",
    "required": ["name", "email"],
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string" }
    },
    "additionalProperties": false
  }
}
```

***

## ResponseSchemaStructure

Root JSON schema structure for validating LLM structured outputs.

```typescript theme={null}
interface ResponseSchemaStructure {
  type: 'object';
  required: string[];
  $defs?: Record<string, any> | null;
  properties: Record<string, ResponseSchemaProperty>;
  additionalProperties: false;
}
```

**Properties**:

* `type` - Must be 'object'
* `required` - Array of required property names
* `$defs` - Schema definitions for reuse (optional)
* `properties` - Object properties
* `additionalProperties` - Must be false for strict schemas

**Example**:

```typescript theme={null}
const schema: ResponseSchemaStructure = {
  type: 'object',
  required: ['title', 'summary'],
  properties: {
    title: {
      type: 'string',
      maxLength: 100,
      description: 'Article title'
    },
    summary: {
      type: 'string',
      maxLength: 500,
      description: 'Brief summary'
    },
    tags: {
      type: 'array',
      items: { type: 'string' },
      maxItems: 5,
      description: 'Topic tags'
    },
    score: {
      type: 'number',
      minimum: 0,
      maximum: 10,
      description: 'Quality score'
    }
  },
  additionalProperties: false
};
```

***

## ResponseSchemaProperty

JSON schema property definition for structured response validation.

```typescript theme={null}
interface ResponseSchemaProperty {
  anyOf?: object[] | null;
  type?: string | string[] | null;
  default?: any | null;
  title?: string | null;
  description?: string | null;     // max 4096 chars
  properties?: Record<string, any> | null;
  required?: string[] | null;
  minItems?: number | null;
  maxItems?: number | null;
  items?: object | null;
  enum?: (string | number | boolean | null)[] | null;
  minimum?: number | null;
  maximum?: number | null;
  minLength?: number | null;
  maxLength?: number | null;
  $ref?: string | null;
}
```

**Properties**: Standard JSON Schema property fields

**Example**:

```typescript theme={null}
// String property
const nameProperty: ResponseSchemaProperty = {
  type: 'string',
  description: 'User full name',
  minLength: 1,
  maxLength: 100
};

// Number property
const ageProperty: ResponseSchemaProperty = {
  type: 'number',
  description: 'User age',
  minimum: 0,
  maximum: 120
};

// Enum property
const statusProperty: ResponseSchemaProperty = {
  type: 'string',
  enum: ['active', 'inactive', 'pending'],
  description: 'Account status'
};

// Array property
const tagsProperty: ResponseSchemaProperty = {
  type: 'array',
  items: { type: 'string' },
  minItems: 0,
  maxItems: 10,
  description: 'User tags'
};

// Object property
const addressProperty: ResponseSchemaProperty = {
  type: 'object',
  properties: {
    street: { type: 'string' },
    city: { type: 'string' },
    zip: { type: 'string' }
  },
  required: ['street', 'city'],
  description: 'Mailing address'
};

// Use in schema
const schema: ResponseSchemaStructure = {
  type: 'object',
  required: ['name', 'age'],
  properties: {
    name: nameProperty,
    age: ageProperty,
    status: statusProperty,
    tags: tagsProperty,
    address: addressProperty
  },
  additionalProperties: false
};
```

***

## Complete Example

```typescript theme={null}
import type {
  ResponseSchema,
  ResponseSchemaStructure,
  ResponseSchemaProperty
} from '@adaline/api';

// Define properties
const properties: Record<string, ResponseSchemaProperty> = {
  name: {
    type: 'string',
    description: 'Full name',
    minLength: 1,
    maxLength: 100
  },
  email: {
    type: 'string',
    description: 'Email address',
    pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
  },
  age: {
    type: 'number',
    description: 'Age in years',
    minimum: 0,
    maximum: 120
  },
  interests: {
    type: 'array',
    items: { type: 'string' },
    description: 'User interests',
    maxItems: 10
  },
  isPremium: {
    type: 'boolean',
    description: 'Premium account status',
    default: false
  }
};

// Build structure
const structure: ResponseSchemaStructure = {
  type: 'object',
  required: ['name', 'email'],
  properties,
  additionalProperties: false
};

// Complete schema
const schema: ResponseSchema = {
  name: 'user_profile',
  description: 'Extract user profile from conversation',
  strict: true,
  schema: structure
};

// Use with Adaline Gateway
import { Gateway } from '@adaline/gateway';
import { OpenAI } from '@adaline/openai';

const gateway = new Gateway();
const openaiProvider = new OpenAI();

const model = openaiProvider.chatModel({
  modelName: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY!
});

const gatewayResponse = await gateway.completeChat({
  model,
  messages: [
    { role: 'system', content: [{ modality: 'text', value: 'Extract user info as JSON' }] },
    { role: 'user', content: [{ modality: 'text', value: 'I am John Doe, email john@example.com, 35 years old' }] }
  ],
  responseSchema: schema
});

const extracted = JSON.parse(String(gatewayResponse.response.messages[0].content[0].value) || '{}');
// { name: 'John Doe', email: 'john@example.com', age: 35 }
```

***

## Import

```typescript theme={null}
import type {
  ResponseSchema,
  ResponseSchemaStructure,
  ResponseSchemaProperty
} from '@adaline/api';
```

***

## Related

<CardGroup cols={2}>
  <Card title="Message Types" icon="message" href="/docs/reference/sdk/v2/typescript/types/PromptMessage">
    Messages in prompts
  </Card>

  <Card title="Tool Types" icon="wrench" href="/docs/reference/sdk/v2/typescript/types/ToolFunction">
    Similar parameter schemas
  </Card>
</CardGroup>