8.0.0 • Published 5 years ago
@cappasityinc/json-schema-to-typescript v8.0.0
json-schema-to-typescript
Compile json schema to typescript typings
Example
Input:
{
"title": "Example Schema",
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"description": "Age in years",
"type": "integer",
"minimum": 0
},
"hairColor": {
"enum": ["black", "brown", "blue"],
"type": "string"
}
},
"additionalProperties": false,
"required": ["firstName", "lastName"]
}
Output:
export interface ExampleSchema {
firstName: string;
lastName: string;
/**
* Age in years
*/
age?: number;
hairColor?: "black" | "brown" | "blue";
}
Installation
# Using Yarn:
yarn add json-schema-to-typescript
# Or, using NPM:
npm install json-schema-to-typescript --save
Usage
import { compile, compileFromFile } from 'json-schema-to-typescript'
// compile from file
compileFromFile('foo.json')
.then(ts => fs.writeFileSync('foo.d.ts', ts))
// or, compile a JS object
let mySchema = {
properties: [...]
}
compile(mySchema, 'MySchema')
.then(ts => ...)
See server demo and browser demo for full examples.
Options
compileFromFile
and compile
accept options as their last argument (all keys are optional):
key | type | default | description |
---|---|---|---|
bannerComment | string | "/* tslint:disable */\n/**\n* This file was automatically generated by json-schema-to-typescript.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,\n* and run json-schema-to-typescript to regenerate this file.\n*/" | Disclaimer comment prepended to the top of each generated file |
cwd | string | process.cwd() | Root directory for resolving $ref s |
declareExternallyReferenced | boolean | true | Declare external schemas referenced via $ref ? |
enableConstEnums | boolean | true | Prepend enums with const ? |
style | object | { bracketSpacing: false, printWidth: 120, semi: true, singleQuote: false, tabWidth: 2, trailingComma: 'none', useTabs: false } | A Prettier configuration |
unreachableDefinitions | boolean | false | Generates code for definitions that aren't referenced by the schema. |
strictIndexSignatures | boolean | false | Append all index signatures with | undefined so that they are strictly typed. |
$refOptions | object | {} | $RefParser Options, used when resolving $ref s |
CLI
A simple CLI utility is provided with this package.
cat foo.json | json2ts > foo.d.ts
# or
json2ts foo.json > foo.d.ts
# or
json2ts foo.json foo.d.ts
# or
json2ts foo.json --output foo.d.ts
# or
json2ts -i foo.json -o foo.d.ts
You can pass any of the options described above (including style options) as CLI flags. Boolean values can be set to false using the no-
prefix.
# generate code for definitions that aren't referenced
json2ts -i foo.json -o foo.d.ts --unreachableDefinitions
# use single quotes and disable trailing semicolons
json2ts -i foo.json -o foo.d.ts --style.singleQuote --no-style.semi
Tests
npm test
Features
title
=>interface
- Primitive types:
- array
- homogeneous array
- boolean
- integer
- number
- null
- object
- string
- homogeneous enum
- heterogeneous enum
- Non/extensible interfaces
- Custom JSON-schema extensions
- Nested properties
- Schema definitions
- Schema references
- Local (filesystem) schema references
- External (network) schema references
- Add support for running in browser
- default interface name
- infer unnamed interface name from filename
allOf
("intersection")anyOf
("union")oneOf
(treated likeanyOf
)maxItems
(eg)minItems
(eg)additionalProperties
of typepatternProperties
(partial support)extends
required
properties on objects (eg)validateRequired
(eg)- literal objects in enum (eg)
- referencing schema by id (eg)
- custom typescript types via
tsType
Not expressible in TypeScript:
dependencies
(single, multiple)divisibleBy
(eg)format
(eg)multipleOf
(eg)maximum
(eg)minimum
(eg)maxProperties
(eg)minProperties
(eg)not
/disallow
oneOf
("xor", useanyOf
instead)pattern
(string, regex)uniqueItems
(eg)
Further Reading
- JSON-schema spec: https://tools.ietf.org/html/draft-zyp-json-schema-04
- JSON-schema wiki: https://github.com/json-schema/json-schema/wiki
- JSON-schema test suite: https://github.com/json-schema/JSON-Schema-Test-Suite/blob/node
- TypeScript spec: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
Projects That Use JSON-Schema-to-TypeScript
8.0.0
5 years ago