Structured Output

Gatelit normalizes structured output across all providers. You configure it once with the outputSchema option, and the gateway handles the provider-specific translation — whether you are using OpenAI, Anthropic, Google, or Mistral.

The `outputSchema` option

Add outputSchema to any client.chat() or client.stream() call:

interface ChatOptions {
  model: string
  messages: ChatMessage[]
  outputSchema?: {
    mode: "json_object" | "json_schema"
    // additional JSON Schema fields when mode is "json_schema"
    [key: string]: unknown
  } | null
  // ...other options
}

There are two modes:

`json_object` mode

The model is instructed to return valid JSON of any shape. Use this when you want JSON output but do not need to enforce a specific schema:

const response = await client.chat({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Return a JSON object with a 'score' (1-10) and a 'reason' for why TypeScript is popular.",
    },
  ],
  outputSchema: { mode: "json_object" },
})

// response.content is a JSON string — parse it yourself
const result = JSON.parse(response.content) as { score: number; reason: string }
console.log(result.score, result.reason)

`json_schema` mode

The model is constrained to match a specific JSON Schema. Provide the schema inline alongside mode: "json_schema":

const response = await client.chat({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Rate the readability of this code snippet on a scale of 1-10 and explain why.",
    },
  ],
  outputSchema: {
    mode: "json_schema",
    type: "object",
    properties: {
      score: { type: "number", minimum: 1, maximum: 10 },
      reason: { type: "string" },
    },
    required: ["score", "reason"],
  },
})

Automatic parsing with `chatJson<T>()`

client.chatJson<T>() is a convenience wrapper around chat() that parses the response content as JSON and returns it typed — no JSON.parse required:

const result = await client.chatJson<{ score: number; reason: string }>({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Rate the readability of this code snippet on a scale of 1-10 and explain why.",
    },
  ],
  outputSchema: { mode: "json_object" },
})

// result is typed as { score: number; reason: string }
console.log(result.score)   // → 8
console.log(result.reason)  // → "Clear variable names and consistent formatting..."

Complete example

Here is a full end-to-end example that asks a model to evaluate a piece of text and return a structured assessment:

import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient({
  gatewayUrl: "https://gateway.yourapp.com",
  getToken: async () => {
    const { token } = await fetch("/api/ai-token").then(r => r.json())
    return { token, scheme: "GatelitSigned" }
  },
})

interface SentimentResult {
  sentiment: "positive" | "negative" | "neutral"
  confidence: number
  summary: string
}

const result = await client.chatJson<SentimentResult>({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "system",
      content: "You are a sentiment analysis assistant. Always respond with valid JSON.",
    },
    {
      role: "user",
      content: `Analyze the sentiment of this review: "The product exceeded my expectations — fast shipping and great quality!"`,
    },
  ],
  outputSchema: {
    mode: "json_schema",
    type: "object",
    properties: {
      sentiment: { type: "string", enum: ["positive", "negative", "neutral"] },
      confidence: { type: "number", minimum: 0, maximum: 1 },
      summary: { type: "string" },
    },
    required: ["sentiment", "confidence", "summary"],
  },
})

console.log(result.sentiment)   // → "positive"
console.log(result.confidence)  // → 0.97
console.log(result.summary)     // → "The reviewer is very satisfied..."

Cross-provider compatibility

Structured output normalization is applied by the gateway, not the SDK. The same outputSchema option works identically whether you target OpenAI, Anthropic, Google, or Mistral — the gateway translates it to each provider’s native format before forwarding the request.

Error handling

If the model returns content that is not valid JSON, chatJson() throws a GatelitError with code: "invalid_json". This can happen when a model ignores the structured output instruction despite being asked for JSON. Always wrap chatJson() calls in a try/catch when building production features:

import { GatelitError } from "@gatelit/sdk"

try {
  const result = await client.chatJson<{ score: number }>({ /* ... */ })
} catch (err) {
  if (err instanceof GatelitError && err.code === "invalid_json") {
    console.error("Model did not return valid JSON:", err.message)
  } else {
    throw err
  }
}

Get Started

Authentication

Guides

Dashboard

Structured Output

The `outputSchema` option

`json_object` mode

`json_schema` mode

Automatic parsing with `chatJson<T>()`

Complete example

Cross-provider compatibility

Error handling

​The outputSchema option

​json_object mode

​json_schema mode

​Automatic parsing with chatJson<T>()

​Complete example

​Cross-provider compatibility

​Error handling

The `outputSchema` option

`json_object` mode

`json_schema` mode

Automatic parsing with `chatJson<T>()`

Complete example

Cross-provider compatibility

Error handling