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";
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 interfacesconst 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.
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.