JSON Schema Typed

JSON Schema TypeScript definitions with complete inline documentation.

NOTE: This library only supports defining schemas. You will need a separate library for data validation.

There are 4 JSON Schema dialects included in this package:

• json-schema-typed/draft-07
• json-schema-typed/2019-09 (also json-schema-typed/draft-2019-09)
• json-schema-typed/2020-12 (also json-schema-typed/draft-2020-12)
• json-schema-typed/v1 (also json-schema-typed/next)

Install

npm install json-schema-typed

Usage

1. Choose which dialect you'd like to import.

• The main package export points to the latest released specification, currently 2020-12. Future releases that point the main package export to a new specification will always incur a bump to the major semantic version.

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

• Or you can specify the exact dialect you need.

  import { type JSONSchema } from "json-schema-typed/2020-12";

2. Define a schema

   import { Format, type JSONSchema } from "json-schema-typed";
   
   const schema: JSONSchema = {
     properties: {
       email: {
         format: Format.Email,
         type: "string",
       },
     },
     type: "object",
   };
   
   // The JSONSchema namespace also provides type-specific narrowed interfaces
   const stringSchema: JSONSchema.String = {
     // Only { type: "string" } and common keywords are allowed
     maxLength: 100,
     type: "string",
   };

Specification versions

JSON Schema changed how it is versioned after 2020-12. The IETF-style drafts (draft-07, 2019-09, 2020-12) were each incompatible with one another, so this package exposes one module per draft and you pin the one you write against.

The next specification is JSON Schema v1. It is versioned by a major version number plus a release year (v1/2026, v1/2027, ...). Releases within a version are additive and backwards compatible, so a schema written for v1/2026 stays valid for every later v1 release. The $schema value https://json-schema.org/v1 always means "latest v1". This package mirrors that: there is one v1 module, updated additively as yearly releases land (a minor version bump here). A new module would only appear for a breaking v2.

import { type JSONSchema } from "json-schema-typed/v1";

v1 is unreleased. The v1 module is generated from the current main branch of the specification repository and tracks it ahead of the first official release (v1/2026). Keywords may still change until then. The main package export stays on 2020-12 until v1 is published.

json-schema-typed/next

next always points at the newest in-progress specification, whatever it is called — today that is v1. Import it if you want to follow the spec's working copy; import v1 if you want to stay on v1 even after a v2 appears.

import { type JSONSchema } from "json-schema-typed/next";

Legacy import paths

json-schema-typed/draft-2019-09 and json-schema-typed/draft-2020-12 still work and are the same modules as json-schema-typed/2019-09 and json-schema-typed/2020-12 (re-exports, not copies, so the types and enums are identical whichever path you use). New code should use the shorter names.

Type checking

JSONSchema describes any schema. Every keyword is optional and documented inline, so hovering a keyword in your editor shows the specification text.

const schema: JSONSchema = {
  type: "object",
  properties: { count: { type: "number", minimum: 0 } },
};

• JSONSchema<Value> constrains type to the kind of value described: JSONSchema<string> has type?: "string", and JSONSchema<string | null> accepts "string", "null", or ["string", "null"].
• JSONSchema.String, JSONSchema.Object, JSONSchema.Array, ... declare only the keywords that apply to that type.
• JSONSchema.Interface is the object half of JSONSchema; extend it to add custom keywords.
• A schema whose literal types have been widened — imported from a .json file, or built in a variable without as const — is still a JSONSchema.

Every schema in the official JSON-Schema-Test-Suite is checked against JSONSchema as part of the test suite, and hover documentation is tested against the TypeScript language service. The published declarations are tested with TypeScript 4.7 and newer.

JSONSchema is deliberately one object type rather than a union discriminated on type: TypeScript only shows a keyword's documentation on hover when the contextual type is a single declaration, so a union would remove the inline documentation that this package exists to provide. Use JSONSchema.String, JSONSchema.Object, etc. when you want only a type's own keywords offered.

Changelog

Release notes, including breaking changes and upgrade guidance, are in the CHANGELOG.

Exports supported in each module

| Name | Type | Purpose | | ----------------- | ------------------- | ------------------------------------------------------------------- | | $schema | string | Meta-schema URL that can be used with the $schema keyword. | | ContentEncoding | Enum object | String content encoding strategies. | | draft | string | Specification identifier ("7", "2019-09", "2020-12", "v1"). | | Format | Enum object | String formats. | | JSONSchema | TypeScript Type | Used to define a JSON Schema. | | keywords | readonly string[] | All the keywords for the imported specification. | | KeywordByType | TypeScript Type | Keyword names grouped by the type they apply to. | | TypeName | Enum object | Simple type names for the type keyword. |

Versioning

This library follows semantic versioning.

Contributing

The draft modules at the package root are generated from the definitions in src/draft. See src/README.md for how to build and test.

Maintainers

• Remy Rylan

License

BSD-3-Clause