dotschema

Import JSON Schemas into TypeScript. Fully typed, scary fast.

If you have a JSON Schema like this:

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "role": { "enum": ["admin", "member"] }
  },
  "required": ["name"],
  "additionalProperties": false
}

You can import it directly from a TypeScript file, and get its type and a validator:

import user from "./user.schema.jsonc";

const data = await request.json();

if (user.is(data)) {
  data; // hover over data to see its type
}

It's powered by TypeScript's content mappers (introduced in TypeScript 7.1), which let a package give tsc the types of a file it imports. The validator is compiled by ajv when the module is built, so a bundle carries the validator and no validator library.

Setup

Install dotschema, then add it to TypeScript and to each tool that loads your code.

Install

You'll need:

• TypeScript 7.1 (currently in beta). The first release with content mappers.
• Node 24 or later.

npm install -D dotschema typescript@beta

If your app runs under the preload, not as a bundle, dotschema builds each schema's module at run time, so install it as a dependency:

npm install dotschema
npm install -D typescript@beta

TypeScript

Add dotschema to tsconfig.json as a content mapper:

{
  "compilerOptions": { /* ... */ },
  "contentMappers": [ 
    { "package": "dotschema", "extensions": [".schema.jsonc"] } 
  ] 
}

Then type-check with --runExternalCode, which lets tsc run content mappers:

{
  "scripts": {
    "typecheck": "tsc --noEmit --runExternalCode"
  }
}

Plugins

Install the plugin for your runtime or framework of choice:

node --import dotschema/register main.ts

preload = ["dotschema/register"]

[test]
preload = ["dotschema/register"]

import dotschema from "dotschema/esbuild";

await Bun.build({
  entrypoints: ["main.ts"],
  target: "bun",
  plugins: [dotschema()],
  outdir: "dist",
});

{
  "preload": ["dotschema/register"]
}

import { defineConfig } from "vite";
import dotschema from "dotschema/vite";

export default defineConfig({
  plugins: [dotschema()],
});

import dotschema from "dotschema/vite";

export default {
  input: "main.js",
  plugins: [dotschema()],
  output: { file: "dist/main.mjs", format: "es" },
};

import type { NextConfig } from "next";
import { withDotschema } from "dotschema/next";

const nextConfig: NextConfig = {
  // ...
};

export default withDotschema(nextConfig);

{
  "scripts": {
    "typecheck": "next typegen && tsc --noEmit --runExternalCode"
  }
}

export default withMotherload(withDotschema(nextConfig));

import * as esbuild from "esbuild";
import dotschema from "dotschema/esbuild";

await esbuild.build({
  entryPoints: ["main.ts"],
  bundle: true,
  platform: "node",
  format: "esm",
  plugins: [dotschema()],
  outfile: "dist/main.mjs",
});

export default {
  // ...
  module: {
    rules: [
      { test: /\.schema\.(jsonc|json5)$/, use: "dotschema/webpack" },
    ],
  },
};

export default {
  // ...
  module: {
    rules: [
      { test: /\.schema\.(jsonc|json5)$/, use: "dotschema/webpack" },
    ],
  },
};

import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
import dotschema from "dotschema/vite";

export default defineConfig({
  plugins: [dotschema(), cloudflare()],
});

export default {
  transform: { "\\.schema\\.(jsonc|json5)$": "dotschema/jest" },
  extensionsToTreatAsEsm: [".jsonc", ".json5"],
};

# Jest runs ES modules only behind this Node flag
NODE_OPTIONS=--experimental-vm-modules npx jest

export default {
  transform: {
    "\\.schema\\.(jsonc|json5)$": "dotschema/jest",
    "\\.(jsonc|json5)$": "motherload/jest",
  },
};

Editors

Set up your editor to use the TypeScript 7.1 language server, with content mappers on.

Schema files

A schema file is a JSON Schema written as JSONC, so it can hold comments and trailing commas:

{
  // who can sign in
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "role": { "enum": ["admin", "member"] },
  },
  "required": ["name"],
  "additionalProperties": false,
}

The $schema keyword picks the draft, 06, 07, 2019-09 or 2020-12, and a schema without it is draft-07:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
}

A $ref can point to another schema file, by a path relative to this one:

{
  "type": "object",
  "properties": {
    "members": {
      "type": "array",
      "items": { "$ref": "./user.schema.jsonc" }
    }
  },
  "required": ["members"],
  "additionalProperties": false
}

The type imports the other file's, by its name:

import team from "./team.schema.jsonc";

type Members = team.Type["members"];
      
type Members = User[]

A $ref with a fragment points into the other file, to a definition or an anchor:

{ "$ref": "./place.schema.jsonc#/$defs/address" }

A keyword the schema's draft doesn't define is ignored, by the type and by the validator, so a schema written for another validator still compiles:

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "x-internal": true, "tsType": "AccountId" }
  },
  "required": ["id"],
  "additionalProperties": false
}

import account from "./account.schema.jsonc";

type Id = account.Type["id"];
    
type Id = string

The type

The type admits every value the schema allows. A keyword no TypeScript type can express, such as minLength or format, leaves the type as it is, and the validator checks it.

The type is .Type on the import:

import user from "./user.schema.jsonc";

const ada: user.Type = { name: "Ada", role: "admin" };
const bob: user.Type = { name: "Bob", role: "owner" };
                                      
Type '"owner"' is not assignable to type '"admin" | "member" | undefined'. ts(2322)

A /** */ comment above a property is its doc comment, which an editor shows on hover:

{
  "type": "object",
  "properties": {
    /** The name the user signs in with. */
    "name": { "type": "string", "minLength": 1 },
    "role": { "enum": ["admin", "member"] }
  },
  "required": ["name"],
  "additionalProperties": false
}

import user from "./user.schema.jsonc";

if (user.is(input)) {
  input.name;
        
name: string
The name the user signs in with.
}

An enum or a const is a literal type:

{
  "type": "object",
  "properties": {
    "status": { "enum": ["draft", "published"] },
    "version": { "const": 1 }
  },
  "required": ["status", "version"],
  "additionalProperties": false
}

import post from "./post.schema.jsonc";

if (post.is(input)) {
  input;
  
const input: {
    status: "draft" | "published";
    version: 1;
}
}

A schema in additionalProperties types every other key:

{
  "type": "object",
  "additionalProperties": { "type": "number" }
}

import scores from "./scores.schema.jsonc";

if (scores.is(input)) {
  input;
  
const input: {
    [key: string]: number;
}
}

A prefixItems list is a tuple, its items required up to minItems:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "prefixItems": [{ "type": "number" }, { "type": "number" }],
  "minItems": 2,
  "items": false
}

import point from "./point.schema.jsonc";

type Point = point.Type;
     
type Point = [number, number]

A oneOf whose variants a const tells apart is a union that narrows:

{
  "type": "object",
  "oneOf": [
    {
      "properties": { "kind": { "const": "click" }, "x": { "type": "number" } },
      "required": ["kind", "x"]
    },
    {
      "properties": { "kind": { "const": "visit" }, "url": { "type": "string" } },
      "required": ["kind", "url"]
    }
  ]
}

import event from "./event.schema.jsonc";

if (event.is(input)) {
  if (input.kind === "click") {
    input.x;
        
x: number
  } else {
    input.url;
         
url: string
  }
}

An if that tests a property's listed values narrows the same way:

{
  "type": "object",
  "properties": { "method": { "enum": ["card", "bank"] } },
  "required": ["method"],
  "if": { "properties": { "method": { "const": "card" } } },
  "then": { "properties": { "last4": { "type": "string" } }, "required": ["last4"] },
  "else": { "properties": { "iban": { "type": "string" } }, "required": ["iban"] }
}

import payment from "./payment.schema.jsonc";

if (payment.is(input) && input.method === "card") {
  input.last4;
        
last4: string
}

Validating

The validator is compiled by ajv when the module is built. Nothing on the module throws.

.validate()

The .validate() method returns the value, or every issue, each with its message, its path and the keyword that failed:

import user from "./user.schema.jsonc";

const result = user.validate(input);
if (result.issues) {
  console.log(result.issues);
  // for { name: "" }:
  // [{
  //   message: "must NOT have fewer than 1 characters",
  //   path: ["name"],
  //   keyword: "minLength",
  // }]
} else {
  result.value;
         
value: {
    name: string;
    role?: "admin" | "member";
}
}

.is()

The .is() method is a type guard, which stops at the first failure:

import user from "./user.schema.jsonc";

const users = values.filter(user.is);
      
const users: {
    name: string;
    role?: "admin" | "member";
}[]

Definitions

Each entry of $defs is a validator of its own, imported by its key:

{
  "type": "object",
  "properties": { "home": { "$ref": "#/$defs/address" } },
  "$defs": {
    "address": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"],
      "additionalProperties": false
    }
  }
}

import { address } from "./place.schema.jsonc";

if (address.is(input)) {
  input;
  
const input: {
    city: string;
}
}

.pick() and .omit()

The .pick() method gives the schema with only the properties named, and .omit() the schema without them:

import user from "./user.schema.jsonc";

const named = user.pick("name");
named.validate({ name: "Ada", role: "admin" });
// { issues: [{
//   message: "must NOT have additional properties",
//   path: ["role"],
//   keyword: "additionalProperties",
// }] }

Its type is the output of a Standard Schema:

import type { StandardSchemaV1 } from "dotschema";
import user from "./user.schema.jsonc";

const named = user.pick("name");
type Named = StandardSchemaV1.InferOutput<typeof named>;
     
type Named = {
    name: string;
}

A schema that is more than an object of properties, such as a oneOf, has neither method.

Formats

Zod's string formats are checked as Zod checks them, jwt among them:

{
  "type": "object",
  "properties": {
    "token": { "type": "string", "format": "jwt" }
  }
}

import session from "./session.schema.jsonc";

session.validate({ token: "not a token" });
// { issues: [{
//   message: "must match format \"jwt\"",
//   path: ["token"],
//   keyword: "format",
// }] }

JSON Schema's own formats, each passing every test of the JSON Schema Test Suite:

Zod's formats, by the names z.toJSONSchema gives them:

OpenAPI's formats, and four more of ajv-formats':

A format no table names is not checked.

Standard Schema

The module is a Standard Schema, so a library that accepts one accepts it:

import user from "./user.schema.jsonc";

user["~standard"].validate(input); // the same function as user.validate

It's a Standard JSON Schema too, which gives the schema as one document in draft-07 or 2020-12, with every file it refers to folded in:

import team from "./team.schema.jsonc";

team["~standard"].jsonSchema.input({ target: "draft-2020-12" });
// {
//   $schema: "https://json-schema.org/draft/2020-12/schema",
//   type: "object",
//   properties: {
//     members: { type: "array", items: { $ref: "#/$defs/user" } },
//   },
//   required: ["members"],
//   additionalProperties: false,
//   $defs: { user: { type: "object", properties: { ... }, ... } },
// }

Errors

An invalid schema is a type error, at its place in the file:

{
  "type": "object",
  "properties": {
    "members": {
      "type": "array",
      "items": { "$ref": "./member.schema.jsonc" }
                          
The $ref "./member.schema.jsonc" names a file that does not exist. dotschema(4)
    }
  },
  "required": ["members"]
}

The type check prints it with its line and column:

$ tsc --noEmit --runExternalCode
team.schema.jsonc:6:27 - error dotschema4: The $ref "./member.schema.jsonc" names a file that does not exist.

6       "items": { "$ref": "./member.schema.jsonc" }
                            ~~~~~~~~~~~~~~~~~~~~~


Found 1 error in team.schema.jsonc:6

Bundles

Each schema's module is built with its validator compiled, so it imports nothing, and a bundle carries the validator and no validator library. A bundled app needs dotschema only to build, as a devDependency.

The opening example's main.ts, bundled and minified by esbuild, has two inputs:

  dist/main.mjs         5.9kb  100.0%
   ├ user.schema.jsonc  5.9kb   99.4%
   └ main.ts             35b     0.6%

A module carries the code of only the formats it uses, and esbuild leaves out a definition nothing imports.

Limits