Llm Json Schema

Make any JSON Schema work with every LLM provider. No dependencies.

Every provider accepts a different, stricter subset of JSON Schema, and the rules differ between models from the same provider. A schema from Zod, Pydantic, TypeBox or an MCP server fails with errors like these:

• Invalid schema for function (OpenAI strict mode)
• 400 INVALID_ARGUMENT and Unknown name "additionalProperties" (Gemini)
• a rejected input_schema (Anthropic)

llm-json-schema rewrites the schema into the form the target model accepts, reports exactly what it changed, and converts the model's output back into your original shape.

Status: 0.7. OpenAI, Anthropic, Gemini (both schema dialects), Groq, xAI, DeepSeek, Mistral and Ollama are supported.

npm install llm-json-schema

Usage

import { convert } from "llm-json-schema";

const r = convert(schema, { target: "openai/gpt-4.1", use: "tool" });

// Send r.schema in r.field ("tools[].function.parameters") with strict: true.
const value = r.decode(JSON.parse(toolCall.function.arguments)); // back in your original shape
const { valid, errors } = r.check(value); // includes the constraints OpenAI couldn't enforce

r.losses;
// [{ path: "#/properties/name", keyword: "minLength", value: 3, action: "described",
//    note: "minLength isn't enforced by openai/gpt-4.1; stated in the description and enforced by check()" }]

To use the schema as the model's final output instead, pass use: "output". r.field then names the right place, for example response_format.json_schema.schema for OpenAI or output_config.format.schema for Anthropic.

Provider strict mode is the default. For OpenAI or Anthropic tools sent with strict: false, pass strict: false here too. The schema is then sent as written, except where the provider rejects it outright: tool parameters must be an object at the root.

• A root anyOf/oneOf whose variants are all objects is merged into one object, so the model's arguments keep their shape and need no decoding. That suits proxies that stream tool arguments.
• A root allOf of objects is merged.
• Any other root is wrapped as {"value": …}, and decode() unwraps it.

From Zod, or any Standard JSON Schema library

import { convert, fromAny } from "llm-json-schema";

const r = convert(fromAny(zodSchema), { target: "openai" });
const data = zodSchema.parse(r.decode(output)); // optional fields come back absent, so defaults apply

fromAny() reads schema["~standard"].jsonSchema, which Zod 4 implements, so llm-json-schema never imports your schema library. Plain JSON Schema (draft-07 or 2020-12) is passed through.

What it changes

losses lists every change. The only exception is spelling-only rewrites from draft-07 to 2020-12 (definitions → $defs, array items → prefixItems), which are listed only for targets that send the schema as written. Each entry has one of these action values:

If no faithful version of the schema exists for the target, convert() throws UnsupportedSchemaError with the path and a suggested fix. Examples are an allOf whose parts contradict each other, an external $ref, a recursive schema for a target without recursion (Anthropic strict), and a schema over the target's limits. Pass lossless: true to throw on any change other than rewritten.

Targets

How the rules were verified. Gemini's rules were checked against the live API on 2026-11-02 (gemini-3.5-flash-lite). OpenAI's and Anthropic's come from their documentation (checked 2026-11-02). Where the docs say nothing about a keyword, it's treated as unsupported and rewritten, so the output stays on the safe side. The worst case is a change that wasn't needed, not a rejected request. The test suite checks every converted schema against those documented rules. See the compatibility table for what was tested and how each keyword is handled per target. A converted schema that a provider rejects is a bug: please open an issue with the schema and the error, and corrections ship as patch releases.

Stability

The output is meant to be accepted by the target and to decode back to your original shape. A rejection is a bug, so please report it. The exact output schema is not guaranteed to stay the same between releases.

• Patch release: the rules got stricter, fixing a rejection.
• Minor release: the rules got looser, so fewer changes are made.
• Major release: the API changed.

ESM and CJS with types. Node 18 or later. MIT license.