Structured Outputs TypeScript

A library for working with OpenAI structured outputs.

Overview

Developers compose representations of types.

import { T } from "structured-outputs"

const Contact = T.object({
  name: T.string,
  phone: T.number,
  email: T.string,
})

Full documentation of types →

Context

Schema definitions effectively serve as additional context for the LLM. We may want to attach context per-type to be used by OpenAI's services.

const Contact = T.object({
  name: T.string`
    Ensure normal length for a person's full name.
  `,
  phone: T.number`
    Ensure the format is that of a phone number.
  `,
  email: T.string`
    Ensure the format is that of an email address.
  `,
})`
  A collection of information common in contact cards.
`

Parameterized Context

Placehold context to be filled in later. This simplifies reuse of types for different generation use cases.

const Person = T.object({
  hometown: T.string`An ${"nationality"} city.`,
  favoriteFood: T.string`A delicious ${"nationality"} food.`,
})

const AmericanPerson = Person.fill({
  nationality: "American",
})

ResponseFormat

Create ResponseFormat for use with OpenAI clients.

import { ResponseFormat } from "structured-outputs"

const response_format = ResponseFormat("extract_contact_information", Contact)`
  The contact information extracted from the supplied text.
`

Native TypeScript Types

Refer to the native typescript type.

function sendText(args: typeof Contact["T"]): void {
  // ...
}

Parse Typed Objects

Utilize convenience methods to unwrap typed data directly from chat completion responses.

const contact = await openai.chat.completions
  .create({
    model: "gpt-4o-mini",
    response_format,
    messages: [
      {
        role: "user",
        content: [{
          type: "text",
          text: `
            Extract data from the following message:

            Please call John Doe at 555-123-4567 or email him at john.doe@example.com.
          `,
        }],
      },
    ],
  })
  .then(response_format.parseFirstChoice)

contact

Use Standalone JSON Schema

assertEquals(Contact.schema(), {
  type: "object",
  properties: {
    name: {
      type: "string",
      description: "Ensure normal length for a person's full name.",
    },
    phone: {
      type: "number",
      description: "Ensure the format is that of a phone number.",
    },
    email: {
      type: "string",
      description: "Ensure the format is that of an email address.",
    },
  },
  additionalProperties: false,
  required: ["name", "phone", "email"],
})