Skip to main content

​
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. 
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: 
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: 
{
  "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. 
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: 
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. 
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: 
// 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

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

import type {
  ResponseSchema,
  ResponseSchemaStructure,
  ResponseSchemaProperty
} from '@adaline/api';

Message Types

Messages in prompts

Tool Types

Similar parameter schemas