json-schema-to-ts

When casting a JSON import to a narrow type to use with FromSchema, TypeScript only provides partial validation.

• What is caught: Errors in object property names (keys) and structural mismatches that prevent the types from overlapping.
• What is NOT caught: Errors in the values of the schema itself (e.g., using type: "number" instead of type: "string" or using const instead of enum) because the widening happens at the value level, not the key level.

import { FromSchema } from "json-schema-to-ts";
import dogRawSchema from "./dog.json";

const dogSchema = dogoRawSchema as {
  type: "object";
  properties: {
    name: { type: "number" }; // UNDETECTED: "number" instead of "string" will go undetected
    years: { type: "integer" }; // DETECTED: "years" instead of "age" will throw an error
    hobbies: { type: "array"; items: { type: "string" } };
    favoriteFood: { const: "pizza" }; // DETECTED: "const" instead of "enum" will throw an error
  };
  required: ["name", "age"];
};

By default, json-schema-to-ts does not work directly with imported .json files because TypeScript treats JSON imports as widened types (e.g., { type: string } instead of the narrow { type: "string" }). FromSchema requires narrow types to perform correct type computations.

To use a .json file, you must manually cast the imported schema to a narrow type using as. While this involves some code duplication, TypeScript provides partial type safety: it will throw an error if the narrow type you provide does not sufficiently overlap with the actual structure of the JSON file (for example, if property names differ).

import { FromSchema } from "json-schema-to-ts";
import dogRawSchema from "./dog.json";

// Cast the raw JSON import to a narrow type to satisfy FromSchema
const dogSchema = dogRawSchema as {
  type: "object";
  properties: {
    name: { type: "string" };
    age: { type: "integer" };
    hobbies: { type: "array"; items: { type: "string" } };
    favoriteFood: { enum: ["pizza", "taco", "fries"] };
  };
  required: ["name", "age"];
};

type Dog = FromSchema<typeof dogSchema>;

In json-schema-to-ts, ExtendedJSONSchema<EXTENSION> is a powerful type that combines the standard JSON Schema structure with a user-defined EXTENSION.

How it works

• Standard Fields: It includes all standard JSON Schema keywords like type, properties, items, allOf, anyOf, etc.
• Custom Fields: It uses the EXTENSION generic to allow any additional properties defined in your custom interface.
• Recursive Support: The extension is applied recursively to nested schemas within properties, items, definitions, and other structural keywords.
• OpenAPI Support: It includes nullable?: boolean as a built-in extension common in OpenAPI specs.

When to use it

Use ExtendedJSONSchema instead of a plain JSON Schema type whenever you are working with schemas that include vendor-specific extensions (like x- properties) or specialized metadata that you want to keep typed within your TypeScript codebase.

When using FromSchema within a generic function (for example, a library function that accepts a schema and returns data inferred from it), TypeScript may throw a type instantiation is excessively deep and possibly infinite error.

To resolve this, you must introduce a second generic parameter to your type definition that explicitly captures the result of FromSchema<SCHEMA> as a default value. This prevents the recursive type instantiation error during the inference process.

import { FromSchema, JSONSchema } from "json-schema-to-ts";

// Use a second generic 'DATA' with a default value of 'FromSchema<SCHEMA>' 
// to avoid 'type instantiation is excessively deep' errors.
type Mocker = <SCHEMA extends JSONSchema, DATA = FromSchema<SCHEMA>>(
  schema: SCHEMA,
) => DATA;

const getMockedData: Mocker = schema => {
  // ... logic here
};

const dogSchema = {
  type: "object",
  // ... schema here
} as const;

// This will now work correctly
const dogMock = getMockedData(dogSchema);

Convert JSON Schema objects to TypeScript interfaces/types.

Defaulted Properties

By default, properties with a default value are treated as required in the resulting TypeScript type. To keep them optional, pass { keepDefaultedPropertiesOptional: true } as the second argument to FromSchema.

Controlling Additional Properties

• Deny extra properties: Use additionalProperties: false or unevaluatedProperties: false (when used with allOf).
• Type unnamed properties: Use additionalProperties or patternProperties to define types for keys not explicitly listed in properties.
• Conflict Resolution: If properties is used alongside additionalProperties or patternProperties, extra properties are typed as unknown to prevent type conflicts.
• Limitation: unevaluatedProperties does not type extra properties when used on its own; use additionalProperties for that purpose.

// Basic Object
const objectSchema = {
  type: "object",
  properties: {
    foo: { type: "string" },
    bar: { type: "number" },
  },
  required: ["foo"],
} as const;

type Object = FromSchema<typeof objectSchema>;
// => { [x: string]: unknown; foo: string; bar?: number; }

// Handling Defaulted Properties
const defaultedProp = {
  type: "object",
  properties: {
    foo: { type: "string", default: "bar" },
  },
  additionalProperties: false,
} as const;

// Default behavior: foo is required
type Object = FromSchema<typeof defaultedProp>;
// => { foo: string; }

// Custom behavior: foo is optional
type Object = FromSchema<
  typeof defaultedProp,
  { keepDefaultedPropertiesOptional: true }
>;
// => { foo?: string; }

// Denying additional properties
const closedObjectSchema = {
  ...objectSchema,
  additionalProperties: false,
} as const;

type Object = FromSchema<typeof closedObjectSchema>;
// => { foo: string; bar?: number; }

// Using unevaluatedProperties with allOf
const closedObjectSchema = {
  type: "object",
  allOf: [
    {
      properties: {
        foo: { type: "string" },
      },
      required: ["foo"],
    },
    {
      properties: {
        bar: { type: "number" },
      },
    },
  ],
  unevaluatedProperties: false,
} as const;

type Object = FromSchema<typeof closedObjectSchema>;
// => { foo: string; bar?: number; }

// Typing unnamed properties via patternProperties/additionalProperties
const openObjectSchema = {
  type: "object",
  additionalProperties: {
    type: "boolean",
  },
  patternProperties: {
    "^S": { type: "string" },
    "^I": { type: "integer" },
  },
} as const;

type Object = FromSchema<typeof openObjectSchema>;
// => { [x: string]: string | number | boolean }

// Conflict: properties + additionalProperties results in unknown for extras
const mixedObjectSchema = {
  type: "object",
  properties: {
    foo: { enum: ["bar", "baz"] },
  },
  additionalProperties: { type: "string" },
} as const;

type Object = FromSchema<typeof mixedObjectSchema>;
// => { [x: string]: unknown; foo?: "bar" | "baz"; }