json-schema-to-ts

What is json-schema-to-ts?

The json-schema-to-ts npm package is a utility that converts JSON Schema definitions into TypeScript types. This allows developers to ensure type safety and consistency between their JSON data and TypeScript code.

What are json-schema-to-ts's main functionalities?

Convert JSON Schema to TypeScript Types

This feature allows you to convert a JSON Schema into a TypeScript type. The `FromSchema` utility type takes a JSON Schema object and infers the corresponding TypeScript type.

import { FromSchema } from 'json-schema-to-ts';

const userSchema = {
  type: 'object',
  properties: {
    id: { type: 'string' },
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['id', 'name']
} as const;

type User = FromSchema<typeof userSchema>;

const user: User = {
  id: '123',
  name: 'John Doe',
  age: 30
};

Type Validation

This feature ensures that the TypeScript types derived from JSON Schema are validated at compile time, reducing runtime errors and improving code reliability.

import { FromSchema } from 'json-schema-to-ts';

const productSchema = {
  type: 'object',
  properties: {
    productId: { type: 'string' },
    price: { type: 'number' }
  },
  required: ['productId', 'price']
} as const;

type Product = FromSchema<typeof productSchema>;

const product: Product = {
  productId: 'abc123',
  price: 19.99
};

Other packages similar to json-schema-to-ts

typescript-json-schema

The typescript-json-schema package generates JSON Schema from your TypeScript types. It works in the opposite direction compared to json-schema-to-ts, which converts JSON Schema to TypeScript types. This package is useful if you start with TypeScript types and need to generate JSON Schema for validation or documentation purposes.

ajv

Ajv is a JSON Schema validator that can also generate TypeScript types from JSON Schema using additional plugins. While its primary focus is on validation, it offers similar functionality to json-schema-to-ts when combined with the appropriate plugins.

zod

Zod is a TypeScript-first schema declaration and validation library. It allows you to define schemas in TypeScript and infer types from them. While it doesn't convert JSON Schema to TypeScript types directly, it provides a similar type-safe experience for defining and validating data structures.

README

Stop typing twice 🙅‍♂️

A lot of projects use JSON schemas for runtime data validation along with TypeScript for static type checking.

Their code may look like this:

const dogSchema = {
  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 = {
  name: string;
  age: number;
  hobbies?: string[];
  favoriteFood?: "pizza" | "taco" | "fries";
};

Both objects carry similar if not exactly the same information. This is a code duplication that can annoy developers and introduce bugs if not properly maintained.

That's when json-schema-to-ts comes to the rescue 💪

FromSchema

The FromSchema method lets you infer TS types directly from JSON schemas:

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

const dogSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "integer" },
    hobbies: { type: "array", items: { type: "string" } },
    favoriteFood: { enum: ["pizza", "taco", "fries"] },
  },
  required: ["name", "age"],
} as const;

type Dog = FromSchema<typeof dogSchema>;
// => Will infer the same type as above

Schemas can even be nested, as long as you don't forget the as const statement:

const catSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "integer" },
    favoriteThings: { enum: ["playing", "sleeping", "moreSleeping"] },
  },
  required: ["name", "age"],
} as const;

const petSchema = {
  anyOf: [dogSchema, catSchema],
} as const;

type Pet = FromSchema<typeof petSchema>;
// => Will work 🙌

The as const statement is used so that TypeScript takes the schema definition to the word (e.g. true is interpreted as the true constant and not widened as boolean). It is pure TypeScript and has zero impact on the compiled code.

Why use json-schema-to-ts ?

There are many librearies out there like zod (type first validation) our . Feel free to check them, they may suit your needs better!

However, if you prefer to stick to JSON schemas (and there are good reasons to do so) AND if you can define your schemas in TS (the as const statement doesn't work on JSON imports... for now !), then json-schema-to-ts is made for you !

Doesn't impact, what's lighter than a dev-only library ?

Let's face it, making small errors in JSON schemas is easy!

Which has the benefits:

• 0 impact on compiled code: What's lighter than a dev dependancy ?
• 📝 Reduce redundancy: Writing less code is always nice!
• 🤝 Enforce consistency: Spot typos, string instead of enum or confusing additionalItems and additionalProperties...
• ⚡️ Be right first-time: With instantaneous feedback given by TS !
• Types are easier to read than shemas. Help you write better schemas

Helps you write complex schemas !

For instance, is it obvious that the following schema can never be validated ?

const addressSchema = {
  type: "object",
  allOf: [
    {
      properties: {
        street: { type: "string" },
        city: { type: "string" },
        state: { type: "string" },
      },
      required: ["street", "city", "state"],
    },
    {
      properties: {
        type: { enum: ["residential", "business"] },
      },
    },
  ],
  additionalProperties: false,
} as const;

Well, it is with FromSchema !

type Address = FromSchema<typeof addressSchema>;
// => never 🙌

Extensively tested against the ajv library. Trust!

Docs

Installation

# npm
npm install --save-dev json-schema-to-ts

# yarn
yarn add --dev json-schema-to-ts

Use cases

Const

const fooSchema = {
  const: "foo",
} as const;

type Foo = FromSchema<typeof fooSchema>;
// => "foo"

Enums

const enumSchema = {
  enum: [true, 42, { foo: "bar" }],
} as const;

type Enum = FromSchema<typeof enumSchema>;
// => true | 42 | { foo: "bar"}

You can also go full circle with typescript enums.

enum Food {
  Pizza = "pizza",
  Taco = "taco",
  Fries = "Fries",
}

const enumSchema = {
  enum: Object.values(Food),
} as const;

type Enum = FromSchema<typeof enumSchema>;
// => Food

Litterals

const litteralSchema = {
  type: "null", // "boolean", "string", "integer", "number"
} as const;

type Litteral = FromSchema<typeof litteralSchema>;
// => null, boolean, string or number

const litteralsSchema = {
  type: ["null", "string"],
} as const;

type Litterals = FromSchema<typeof litteralsSchema>;
// => null | string

(For object and array types, properties like required or additionalItems will work 🙌)

Arrays

const arraySchema = {
  type: "array",
  items: { type: "string" },
} as const;

type Array = FromSchema<typeof arraySchema>;
// => string[]

Tuples

const tupleSchema = {
  type: "array",
  items: [{ type: "boolean" }, { type: "string" }],
} as const;

type Tuple = FromSchema<typeof tupleSchema>;
// => [] | [boolean] | [boolean, string] | [boolean, string, ...unknown[]]

FromSchema supports the additionalItems specifications:

const tupleSchema = {
  type: "array",
  items: [{ type: "boolean" }, { type: "string" }],
  additionalItems: false,
} as const;

type Tuple = FromSchema<typeof tupleSchema>;
// => [] | [boolean] | [boolean, string]

const tupleSchema = {
  type: "array",
  items: [{ type: "boolean" }, { type: "string" }],
  additionalItems: { type: "number" },
} as const;

type Tuple = FromSchema<typeof tupleSchema>;
// => [] | [boolean] | [boolean, string] | [boolean, string, ...number[]]

...as well as the minItems and maxItems specifications:

const tupleSchema = {
  type: "array",
  items: [{ type: "boolean" }, { type: "string" }],
  minItems: 1,
  maxItems: 2,
} as const;

type Tuple = FromSchema<typeof tupleSchema>;
// => [boolean] | [boolean, string]

Additional items will only work if Typescript's strictNullChecks option is activated

Objects

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; }

FromSchema partially supports the additionalProperties and patternProperties specifications:

• additionalProperties can be used to deny additional items.

const closedObjectSchema = {
  ...objectSchema,
  additionalProperties: false,
} as const;

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

• Used on their own, additionalProperties and/or patternProperties can be used to type unnamed properties.

const objectSchema = {
  type: "object",
  additionalProperties: {
    type: "boolean",
  },
  patternProperties: {
    "^S": { type: "string" },
    "^I": { type: "integer" },
  },
} as const;

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

• However, when used in combination with the properties keyword, extra properties will always be typed as unknown to avoid conflicts.

AnyOf

const anyOfSchema = {
  anyOf: [
    { type: "string" },
    {
      type: "array",
      items: { type: "string" },
    },
  ],
} as const;

type AnyOf = FromSchema<typeof fooSchema>;
// => string | string[]

FromSchema will correctly infer factored schemas:

const factoredSchema = {
  type: "object",
  properties: {
    bool: { type: "boolean" },
  },
  required: ["bool"],
  anyOf: [
    {
      properties: {
        str: { type: "string" },
      },
      required: ["str"],
    },
    {
      properties: {
        num: { type: "number" },
      },
    },
  ],
} as const;

type Factored = FromSchema<typeof factoredSchema>;
// => {
//  [x:string]: unknown;
//  bool: boolean;
//  str: string;
// } | {
//  [x:string]: unknown;
//  bool: boolean;
//  num?: number;
// }

OneOf

Because TypeScript doesn't have refinment types, oneOf will behave strictly the same as anyOf.

const catSchema = {
  type: "object",
  oneOf: [
    { properties: { name: { type: "string" } }, required: ["name"] },
    { properties: { color: { enum: ["black", "brown", "white"] } } },
  ],
} as const;

type Cat = FromSchema<typeof catSchema>;
// => {
//  [x: string]: unknown;
//  name: string;
// } | {
//  [x: string]: unknown;
//  color?: "black" | "brown" | "white";
// }

// => FromSchema cannot detect the following invalid obj 😱
const invalidCat: Cat = { name: "Garfield" };

AllOf

...Coming soon 😃

If/Else

...Coming soon 😃