Implementation:Openai Openai node JSONSchema Types

Knowledge Sources	Openai_Openai_node
Domains	SDK, JSON Schema, Type System
Last Updated	2026-02-15 12:00 GMT

Overview

JSONSchema_Types provides TypeScript type definitions for JSON Schema Draft 07, used throughout the SDK for tool parameter schemas and structured output definitions.

Description

This module is a streamlined adaptation of the @types/json-schema package, providing essential TypeScript type definitions for JSON Schema Draft 07. The types are used by the SDK to define function tool parameter schemas, validate structured outputs, and perform schema transformations for the OpenAI API's strict mode.

The module defines the following key types: JSONSchemaTypeName for the seven primitive type names (string, number, integer, boolean, object, array, null), JSONSchemaType for actual JSON values, and JSONSchemaDefinition as the union of JSONSchema | boolean used in subschema positions. The main JSONSchema interface covers all standard Draft 07 keywords including type constraints (multipleOf, maximum, minimum), string constraints (maxLength, minLength, pattern), array constraints (items, additionalItems, maxItems, minItems, uniqueItems), object constraints (properties, additionalProperties, required, patternProperties), composition keywords (allOf, anyOf, oneOf, not), conditional keywords (if, then, else), references ($ref, $defs, definitions), and annotation keywords (title, description, default, examples).

Helper interfaces JSONSchemaObject and JSONSchemaArray serve as workarounds for TypeScript's infinite type recursion limitations when modeling the recursive nature of JSON values.

Usage

Use these types when defining JSON Schema objects for function tool parameters in RunnableFunction definitions, when constructing schemas programmatically for structured outputs, or when working with the schema transformation utilities in transform.ts. These types are also used internally by the Zod-to-JSON-Schema conversion helpers.

Code Reference

Source Location

• Repository: openai-node
• File: src/lib/jsonschema.ts

Signature

export type JSONSchemaTypeName =
  | ({} & string)
  | 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';

export type JSONSchemaType = string | number | boolean | JSONSchemaObject | JSONSchemaArray | null;

export interface JSONSchemaObject { [key: string]: JSONSchemaType; }
export interface JSONSchemaArray extends Array<JSONSchemaType> {}

export type JSONSchemaVersion = string;
export type JSONSchemaDefinition = JSONSchema | boolean;

export interface JSONSchema {
  $id?: string;
  $comment?: string;
  type?: JSONSchemaTypeName | JSONSchemaTypeName[];
  enum?: JSONSchemaType[];
  const?: JSONSchemaType;
  multipleOf?: number;
  maximum?: number;
  exclusiveMaximum?: number;
  minimum?: number;
  exclusiveMinimum?: number;
  maxLength?: number;
  minLength?: number;
  pattern?: string;
  items?: JSONSchemaDefinition | JSONSchemaDefinition[];
  additionalItems?: JSONSchemaDefinition;
  maxItems?: number;
  minItems?: number;
  uniqueItems?: boolean;
  contains?: JSONSchemaDefinition;
  maxProperties?: number;
  minProperties?: number;
  required?: string[];
  properties?: { [key: string]: JSONSchemaDefinition };
  patternProperties?: { [key: string]: JSONSchemaDefinition };
  additionalProperties?: JSONSchemaDefinition;
  propertyNames?: JSONSchemaDefinition;
  if?: JSONSchemaDefinition;
  then?: JSONSchemaDefinition;
  else?: JSONSchemaDefinition;
  allOf?: JSONSchemaDefinition[];
  anyOf?: JSONSchemaDefinition[];
  oneOf?: JSONSchemaDefinition[];
  not?: JSONSchemaDefinition;
  $defs?: { [key: string]: JSONSchemaDefinition };
  definitions?: { [key: string]: JSONSchemaDefinition };
  $ref?: string;
  format?: string;
  title?: string;
  description?: string;
  default?: JSONSchemaType;
  readOnly?: boolean;
  writeOnly?: boolean;
  examples?: JSONSchemaType;
}

Import

import type { JSONSchema, JSONSchemaDefinition, JSONSchemaTypeName } from 'openai/lib/jsonschema';

I/O Contract

Inputs

Name	Type	Required	Description
N/A	N/A	N/A	This module exports only type definitions and interfaces. There are no runtime functions or inputs.

Outputs

Name	Type	Description
JSONSchema	interface	The main JSON Schema Draft 07 interface with all standard validation, composition, and annotation keywords.
JSONSchemaDefinition	boolean	Union type used in subschema positions where a boolean schema is permitted.
JSONSchemaTypeName	string literal union	The seven primitive JSON Schema type names plus a general string fallback.

Usage Examples

import type { JSONSchema } from 'openai/lib/jsonschema';

const weatherParams: JSONSchema = {
  type: 'object',
  properties: {
    location: {
      type: 'string',
      description: 'The city and state, e.g., San Francisco, CA',
    },
    unit: {
      type: 'string',
      enum: ['celsius', 'fahrenheit'],
    },
  },
  required: ['location'],
};

// Use in a tool definition
const tool = {
  type: 'function' as const,
  function: {
    name: 'get_weather',
    description: 'Get the current weather',
    parameters: weatherParams,
  },
};

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime