1 | # json-schema-to-typescript [![Build Status][build]](https://github.com/bcherny/json-schema-to-typescript/actions?query=branch%3Amaster+workflow%3ACI) [![npm]](https://www.npmjs.com/package/json-schema-to-typescript) [![mit]](https://opensource.org/licenses/MIT)
|
2 |
|
3 | [build]: https://img.shields.io/github/workflow/status/bcherny/json-schema-to-typescript/CI/master?style=flat-square
|
4 | [npm]: https://img.shields.io/npm/v/json-schema-to-typescript.svg?style=flat-square
|
5 | [mit]: https://img.shields.io/npm/l/json-schema-to-typescript.svg?style=flat-square
|
6 |
|
7 | > Compile json schema to typescript typings
|
8 |
|
9 | ## Example
|
10 |
|
11 | Input:
|
12 | ```json
|
13 | {
|
14 | "title": "Example Schema",
|
15 | "type": "object",
|
16 | "properties": {
|
17 | "firstName": {
|
18 | "type": "string"
|
19 | },
|
20 | "lastName": {
|
21 | "type": "string"
|
22 | },
|
23 | "age": {
|
24 | "description": "Age in years",
|
25 | "type": "integer",
|
26 | "minimum": 0
|
27 | },
|
28 | "hairColor": {
|
29 | "enum": ["black", "brown", "blue"],
|
30 | "type": "string"
|
31 | }
|
32 | },
|
33 | "additionalProperties": false,
|
34 | "required": ["firstName", "lastName"]
|
35 | }
|
36 | ```
|
37 |
|
38 | Output:
|
39 | ```ts
|
40 | export interface ExampleSchema {
|
41 | firstName: string;
|
42 | lastName: string;
|
43 | /**
|
44 | * Age in years
|
45 | */
|
46 | age?: number;
|
47 | hairColor?: "black" | "brown" | "blue";
|
48 | }
|
49 | ```
|
50 |
|
51 | ## Installation
|
52 |
|
53 | ```sh
|
54 | # Using Yarn:
|
55 | yarn add json-schema-to-typescript
|
56 |
|
57 | # Or, using NPM:
|
58 | npm install json-schema-to-typescript --save
|
59 | ```
|
60 |
|
61 | ## Usage
|
62 |
|
63 | ```js
|
64 | import { compile, compileFromFile } from 'json-schema-to-typescript'
|
65 |
|
66 | // compile from file
|
67 | compileFromFile('foo.json')
|
68 | .then(ts => fs.writeFileSync('foo.d.ts', ts))
|
69 |
|
70 | // or, compile a JS object
|
71 | let mySchema = {
|
72 | properties: [...]
|
73 | }
|
74 | compile(mySchema, 'MySchema')
|
75 | .then(ts => ...)
|
76 | ```
|
77 |
|
78 | See [server demo](example) and [browser demo](https://github.com/bcherny/json-schema-to-typescript-browser) for full examples.
|
79 |
|
80 | ## Options
|
81 |
|
82 | `compileFromFile` and `compile` accept options as their last argument (all keys are optional):
|
83 |
|
84 | | key | type | default | description |
|
85 | |-|-|-|-|
|
86 | | 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 |
|
87 | | cwd | string | `process.cwd()` | Root directory for resolving [`$ref`](https://tools.ietf.org/id/draft-pbryan-zyp-json-ref-03.html)s |
|
88 | | declareExternallyReferenced | boolean | `true` | Declare external schemas referenced via `$ref`? |
|
89 | | enableConstEnums | boolean | `true` | Prepend enums with [`const`](https://www.typescriptlang.org/docs/handbook/enums.html#computed-and-constant-members)? |
|
90 | | format | boolean | `true` | Format code? Set this to `false` to improve performance. |
|
91 | | ignoreMinAndMaxItems | boolean | `false` | Ignore maxItems and minItems for `array` types, preventing tuples being generated. |
|
92 | | style | object | `{ bracketSpacing: false, printWidth: 120, semi: true, singleQuote: false, tabWidth: 2, trailingComma: 'none', useTabs: false }` | A [Prettier](https://prettier.io/docs/en/options.html) configuration |
|
93 | | unknownAny | boolean | `true` | Use `unknown` instead of `any` where possible |
|
94 | | unreachableDefinitions | boolean | `false` | Generates code for `definitions` that aren't referenced by the schema. |
|
95 | | strictIndexSignatures | boolean | `false` | Append all index signatures with `\| undefined` so that they are strictly typed. |
|
96 | | $refOptions | object | `{}` | [$RefParser](https://github.com/BigstickCarpet/json-schema-ref-parser) Options, used when resolving `$ref`s |
|
97 | ## CLI
|
98 |
|
99 | A CLI utility is provided with this package.
|
100 |
|
101 | ```sh
|
102 | cat foo.json | json2ts > foo.d.ts
|
103 | # or
|
104 | json2ts foo.json > foo.d.ts
|
105 | # or
|
106 | json2ts foo.json foo.d.ts
|
107 | # or
|
108 | json2ts --input foo.json --output foo.d.ts
|
109 | # or
|
110 | json2ts -i foo.json -o foo.d.ts
|
111 | # or (quote globs so that your shell doesn't expand them)
|
112 | json2ts -i 'schemas/**/*.json'
|
113 | # or
|
114 | json2ts -i schemas/ -o types/
|
115 | ```
|
116 |
|
117 | 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.
|
118 |
|
119 | ```sh
|
120 | # generate code for definitions that aren't referenced
|
121 | json2ts -i foo.json -o foo.d.ts --unreachableDefinitions
|
122 | # use single quotes and disable trailing semicolons
|
123 | json2ts -i foo.json -o foo.d.ts --style.singleQuote --no-style.semi
|
124 | ```
|
125 |
|
126 | ## Tests
|
127 |
|
128 | `npm test`
|
129 |
|
130 | ## Features
|
131 |
|
132 | - [x] `title` => `interface`
|
133 | - [x] Primitive types:
|
134 | - [x] array
|
135 | - [x] homogeneous array
|
136 | - [x] boolean
|
137 | - [x] integer
|
138 | - [x] number
|
139 | - [x] null
|
140 | - [x] object
|
141 | - [x] string
|
142 | - [x] homogeneous enum
|
143 | - [x] heterogeneous enum
|
144 | - [x] Non/extensible interfaces
|
145 | - [ ] Custom JSON-schema extensions
|
146 | - [x] Nested properties
|
147 | - [x] Schema definitions
|
148 | - [x] [Schema references](http://json-schema.org/latest/json-schema-core.html#rfc.section.7.2.2)
|
149 | - [x] Local (filesystem) schema references
|
150 | - [x] External (network) schema references
|
151 | - [x] Add support for running in browser
|
152 | - [x] default interface name
|
153 | - [x] infer unnamed interface name from filename
|
154 | - [x] `allOf` ("intersection")
|
155 | - [x] `anyOf` ("union")
|
156 | - [x] `oneOf` (treated like `anyOf`)
|
157 | - [x] `maxItems` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L166))
|
158 | - [x] `minItems` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L165))
|
159 | - [x] `additionalProperties` of type
|
160 | - [x] `patternProperties` (partial support)
|
161 | - [x] [`extends`](https://github.com/json-schema/json-schema/wiki/Extends/014e3cd8692250baad70c361dd81f6119ad0f696)
|
162 | - [x] `required` properties on objects ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L130))
|
163 | - [ ] `validateRequired` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L124))
|
164 | - [x] literal objects in enum ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L236))
|
165 | - [x] referencing schema by id ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L331))
|
166 | - [x] custom typescript types via `tsType`
|
167 |
|
168 | ## Custom schema properties:
|
169 |
|
170 | - `tsType`: Overrides the type that's generated from the schema. Useful for forcing a type to `any` or when using non-standard JSON schema extensions ([eg](https://github.com/sokra/json-schema-to-typescript/blob/f1f40307cf5efa328522bb1c9ae0b0d9e5f367aa/test/e2e/customType.ts)).
|
171 | - `tsEnumNames`: Overrides the names used for the elements in an enum. Can also be used to create string enums ([eg](https://github.com/johnbillion/wp-json-schemas/blob/647440573e4a675f15880c95fcca513fdf7a2077/schemas/properties/post-status-name.json)).
|
172 |
|
173 | ## Not expressible in TypeScript:
|
174 |
|
175 | - `dependencies` ([single](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L261), [multiple](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L282))
|
176 | - `divisibleBy` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L185))
|
177 | - [`format`](https://github.com/json-schema/json-schema/wiki/Format) ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L209))
|
178 | - `multipleOf` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L186))
|
179 | - `maximum` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L183))
|
180 | - `minimum` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L182))
|
181 | - `maxProperties` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L113))
|
182 | - `minProperties` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L112))
|
183 | - `not`/`disallow`
|
184 | - `oneOf` ("xor", use `anyOf` instead)
|
185 | - `pattern` ([string](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L203), [regex](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L207))
|
186 | - `uniqueItems` ([eg](https://github.com/tdegrunt/jsonschema/blob/67c0e27ce9542efde0bf43dc1b2a95dd87df43c3/examples/all.js#L172))
|
187 |
|
188 | ## FAQ
|
189 |
|
190 | ### JSON-Schema-to-TypeScript is crashing on my giant file. What can I do?
|
191 |
|
192 | Prettier is known to run slowly on really big files. To skip formatting and improve performance, set the `format` option to `false`.
|
193 |
|
194 | ## Further Reading
|
195 |
|
196 | - JSON-schema spec: https://tools.ietf.org/html/draft-zyp-json-schema-04
|
197 | - JSON-schema wiki: https://github.com/json-schema/json-schema/wiki
|
198 | - JSON-schema test suite: https://github.com/json-schema/JSON-Schema-Test-Suite/blob/node
|
199 | - TypeScript spec: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md
|
200 |
|
201 | ## Who uses JSON-Schema-to-TypeScript?
|
202 |
|
203 | - [AWS](https://github.com/aws/aws-toolkit-vscode), [AWSLabs](https://github.com/awslabs/cdk8s)
|
204 | - [FormatJS](https://github.com/formatjs/formatjs)
|
205 | - [Microsoft](https://github.com/microsoft/mixed-reality-extension-sdk)
|
206 | - [Sourcegraph](https://github.com/sourcegraph/sourcegraph)
|
207 | - [Stryker](https://github.com/stryker-mutator/stryker)
|
208 | - [Webpack](https://github.com/webpack/webpack)
|
209 | - [See more](https://github.com/bcherny/json-schema-to-typescript/network/dependents?package_id=UGFja2FnZS0xNjUxOTM5Mg%3D%3D)
|