Implementation:Openai Openai node StrictJsonSchema Transform

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

Overview

StrictJsonSchema_Transform transforms JSON Schema objects into the strict format required by the OpenAI API for structured output and function tool parameters.

Description

The toStrictJsonSchema function is the public entry point that takes a standard JSON Schema (which must have type: 'object' at the root) and returns a deep copy that has been mutated to conform to the OpenAI API's strict schema requirements. The transformation is performed by the recursive ensureStrictJsonSchema function, which walks the entire schema tree and applies several key modifications.

For object types, the transform automatically sets additionalProperties: false if not already present and promotes all properties to the required array. It validates that any optional (non-required) property is nullable, throwing an error if a field uses .optional() without .nullable(), since the API requires all fields to be required in strict mode. The transform recursively processes properties, items, anyOf, allOf, $defs, and definitions sub-schemas. For allOf with a single entry, it inlines the schema directly. Null defaults are stripped, and $ref references with additional properties are resolved and inlined, with the inlined schema being re-validated for strictness.

The module includes helper functions: isNullable checks whether a schema admits null values (via type: 'null', oneOf, or anyOf), resolveRef resolves $ref pointers within the root schema, isObject performs runtime type narrowing, and hasMoreThanNKeys efficiently checks object key counts.

Usage

Use toStrictJsonSchema when you need to convert a standard JSON Schema (e.g., one generated from a Zod schema via zod-to-json-schema) into the strict format accepted by the OpenAI API's structured output features. The SDK calls this function internally when processing schemas for response_format with json_schema type and for strict function tool parameters. This is a critical part of the auto-parsing pipeline.

Code Reference

Source Location

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

Signature

export function toStrictJsonSchema(schema: JSONSchema): JSONSchema;

Import

import { toStrictJsonSchema } from 'openai/lib/transform';

I/O Contract

Inputs

Name	Type	Required	Description
schema	JSONSchema	Yes	A JSON Schema object with type: 'object' at the root level. The function throws an error if the root type is not 'object'.

Outputs

Name	Type	Description
strictSchema	JSONSchema	A deep copy of the input schema transformed to comply with the OpenAI API's strict schema requirements: all object properties are required, additionalProperties: false is set on all objects, null defaults are removed, single-entry allOf is inlined, and $ref with extra properties is resolved.

Usage Examples

import { toStrictJsonSchema } from 'openai/lib/transform';

const schema = {
  type: 'object' as const,
  properties: {
    name: { type: 'string' as const },
    age: { type: 'number' as const },
    address: {
      type: 'object' as const,
      properties: {
        street: { type: 'string' as const },
        city: { type: 'string' as const },
      },
    },
  },
};

const strict = toStrictJsonSchema(schema);
// Result:
// {
//   type: 'object',
//   properties: {
//     name: { type: 'string' },
//     age: { type: 'number' },
//     address: {
//       type: 'object',
//       properties: {
//         street: { type: 'string' },
//         city: { type: 'string' },
//       },
//       required: ['street', 'city'],
//       additionalProperties: false,
//     },
//   },
//   required: ['name', 'age', 'address'],
//   additionalProperties: false,
// }

// Typical usage with Zod and the SDK
import { z } from 'zod';
import { zodResponseFormat } from 'openai/helpers/zod';

// The SDK internally calls toStrictJsonSchema when you use zodResponseFormat
const format = zodResponseFormat(
  z.object({
    name: z.string(),
    age: z.number(),
  }),
  'person',
);

// The resulting schema in format.json_schema.schema
// will have additionalProperties: false and all fields required

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime