UNPKG

json-schema-typed

Version:

JSON Schema TypeScript definitions with complete inline documentation.

180 lines (133 loc) • 7.22 kB
[![npm](https://img.shields.io/npm/v/json-schema-typed.svg?style=flat-square)](https://npmjs.org/package/json-schema-typed) [![downloads-per-month](https://img.shields.io/npm/dm/json-schema-typed.svg?style=flat-square&label=npm%20downloads)](https://npmjs.org/package/json-schema-typed) [![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg?style=flat-square)][license] # 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 ```sh 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. ```ts import { type JSONSchema } from "json-schema-typed"; ``` - Or you can specify the exact dialect you need. ```ts import { type JSONSchema } from "json-schema-typed/2020-12"; ``` 2. Define a schema ```ts 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`. ```ts 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. ```ts 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. ```ts 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](https://github.com/json-schema-org/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](https://github.com/RemyRylan/json-schema-typed/blob/main/CHANGELOG.md). ## 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](https://semver.org). ## Contributing The draft modules at the package root are generated from the definitions in [`src/draft`](https://github.com/RemyRylan/json-schema-typed/tree/main/src/draft). See [`src/README.md`](https://github.com/RemyRylan/json-schema-typed/blob/main/src/README.md) for how to build and test. --- ## Maintainers - [Remy Rylan](https://github.com/RemyRylan) ## License [BSD-3-Clause][license] [license]: https://github.com/RemyRylan/json-schema-typed/blob/main/LICENSE.md