Skip to content

Latest commit

 

History

History
106 lines (86 loc) · 3.75 KB

README.md

File metadata and controls

106 lines (86 loc) · 3.75 KB
Raw

@spec2ts/jsonschema

NPM version NPM download Build Status

@spec2ts/jsonschema is an utility to create TypeScript types from JSON schemas. Unlike other code generators @spec2ts/jsonschema does not use templates to generate code but uses TypeScript's built-in API to generate and pretty-print an abstract syntax tree (AST).

Features

  • AST-based: Unlike other code generators @spec2ts/jsonschema does not use templates to generate code but uses TypeScript's built-in API to generate and pretty-print an abstract syntax tree.
  • Tree-shakeable: Individually exported types allows you to bundle only the ones you actually use.
  • YAML or JSON: Use YAML or JSON for your JSON Schemas.
  • External references: Resolves automatically external references and bundle or import them in generated files.
  • Implementation agnostic: Use generated types in any projet or framework.

Installation

Install in your project:

npm install @spec2ts/jsonschema

CLI Usage

jsonschema2ts [options] <input..>

Generate TypeScript types from JSON Schemas

Positionals:
  input  Path to JSON Schema(s) to convert to TypeScript                [string]

Options:
  --version     Show version number                                    [boolean]
  --help        Show help usage                                        [boolean]
  --output, -o  Output directory for generated types                    [string]
  --cwd, -c     Root directory for resolving $refs                      [string]
  --avoidAny    Avoid the `any` type and use `unknown` instead         [boolean]
  --enableDate  Build `Date` for format `date` and `date-time`         [boolean]
  --banner, -b  Comment prepended to the top of each generated file     [string]

Programmatic Usage

import { printer } from "@spec2ts/core";
import { parseSchema, JSONSchema } from "@spec2ts/jsonschema";

async function generateSchema(schema: JSONSchema): Promise<string> {
    const result = await parseSchema(schema);
    return printer.printNodes(result);
}

Implementations

  • Primitive types:
    • array
    • boolean
    • integer
    • number
    • null
    • object
    • string
    • homogeneous enum
    • heterogeneous enum
  • Special types:
    • Date (date and date-time formats)
    • Blob (binary format)
  • Automatic type naming:
    • From id
    • From path
    • From title
  • Custom JSON-schema extensions
  • Nested properties
  • Schema definitions
  • Schema references
    • Local (filesystem) schema references
    • External (network) schema references
  • Modular architecture
    • Import local references
    • Embed external references
  • allOf ("intersection")
  • anyOf ("union")
  • oneOf (treated like anyOf)
  • maxItems
  • minItems
  • additionalProperties of type
  • patternProperties (partial support)
  • extends (with allOf)
  • required properties on objects
  • validateRequired
  • literal objects in enum
  • referencing schema by id

Compatibility Matrix

TypeScript version spec2ts version
v3.x.x v1
v4.x.x v2

License

This project is under MIT License. See the LICENSE file for the full license text.