JSON Schema TypeScript Types

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...json-schema-typed/dist/node/index.js from ... not supported.

  cause Attempting to `require()` the `json-schema-typed` package in a CommonJS environment, but the package is pure ESM since v8.0.0.
  fix Convert your consuming code to use ES module `import` syntax. Ensure your `package.json` includes `"type": "module"` or that your file has an `.mjs` extension.

• Property 'X' does not exist on type 'JSONSchema<...>'

  cause Attempting to use a keyword or property that is either not part of the specified JSON Schema draft, or is defined differently in the selected draft version, or is not allowed on the base `JSONSchema` type.
  fix Review the JSON Schema specification for the draft you are using (e.g., draft-2020-12, draft-07). Ensure the keyword is valid and applied correctly. Also, consider using the type-specific narrowed interfaces like `JSONSchema.String` if applicable, as they provide stricter typing for certain schema types.

• Cannot find name 'JSONSchema' (or 'Format', etc.)

  cause This typically occurs when trying to use an old export name, or when importing from the main package while expecting a specific draft's exports that are now only available via subpath.
  fix For v8.0.0+, ensure you are using the correct, renamed exports (e.g., `JSONSchema` for the main type) and importing from the correct path. If you need Draft 07, import from `json-schema-typed/draft-07`.

Warnings

• breaking Version 8.0.0 and above are pure ESM packages. CommonJS `require()` is no longer supported and will lead to errors.
  Fix: Migrate your project to use ES Modules (ESM) syntax (`import/export`). Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for modules importing `json-schema-typed`.
• breaking Many exports were renamed in v8.0.0. Code using older export names will break.
  Fix: Consult the package's README or documentation for the new export names. The provided export table details the updated naming conventions.
• breaking The `JSONSchema` type changed from an `interface` to a `type` (a mixed union allowing boolean values) in v8.0.0 to better align with the JSON Schema spec. If you were extending the `JSONSchema` interface, your code will break.
  Fix: If you need to extend the interface directly, use `JSONSchema.Interface` which provides the previous interface definition.
• breaking The main package export now points to Draft 2020-12 by default in v8.0.0. Previously it pointed to Draft 07. If your schema relies on Draft 07 behavior, the default import will now provide the wrong draft's types.
  Fix: Explicitly import the desired draft using subpaths, e.g., `import { type JSONSchema } from 'json-schema-typed/draft-07'`.
• gotcha This library only provides TypeScript definitions for JSON Schema. It does NOT include any data validation capabilities. Using it alone will not validate your data against a schema.
  Fix: Pair `json-schema-typed` with a separate JSON Schema validation library (e.g., `ajv`, `zod-to-json-schema`, etc.) to perform actual data validation.

Install

• npm install json-schema-typed npm
• yarn add json-schema-typed yarn
• pnpm add json-schema-typed pnpm

Imports

• JSONSchema
  wrong:

  const { JSONSchema } = require('json-schema-typed')

  correct:

  import { type JSONSchema } from 'json-schema-typed'

  Package is pure ESM since v8.0.0. Use `import type` for type-only imports for better tree-shaking.
• Format
  wrong:

  import { Format } from 'json-schema-typed/draft-07'

  correct:

  import { Format } from 'json-schema-typed'

  Format enum is available directly from the main package export (latest draft) or specific draft paths. Ensure you are importing the correct draft's Format enum if using a non-default version.
• JSONSchema.String

  import { type JSONSchema } from 'json-schema-typed'; const stringSchema: JSONSchema.String = { /* ... */ };

  Narrowed interfaces like `JSONSchema.String` are available under the `JSONSchema` namespace, not as direct named exports.
• JSONSchema (Draft 07)

  import { type JSONSchema } from 'json-schema-typed/draft-07'

  For specific drafts, import directly from the subpath, e.g., 'json-schema-typed/draft-07'. The main export defaults to the latest stable draft (currently 2020-12).

Quickstart

Demonstrates defining a JSON Schema using `JSONSchema` type and `Format` enum, including a type-specific narrowed interface.

import { Format, type JSONSchema } from "json-schema-typed";

// Define a schema for an object with an email property
const userSchema: JSONSchema = {
  type: "object",
  properties: {
    email: {
      format: Format.Email, // Uses the predefined Format enum for 'email' format
      type: "string",
      description: "User's email address in a valid format."
    },
    age: {
      type: "integer",
      minimum: 0,
      description: "User's age, must be a non-negative integer."
    }
  },
  required: ["email", "age"],
  additionalProperties: false
};

// Example of a type-specific narrowed interface for a string schema
const usernameSchema: JSONSchema.String = {
  type: "string",
  maxLength: 50,
  minLength: 3,
  description: "Username must be between 3 and 50 characters long."
};

console.log('User Schema:', JSON.stringify(userSchema, null, 2));
console.log('Username Schema:', JSON.stringify(usernameSchema, null, 2));