typescript-json-schema
Generate json-schemas from your Typescript sources.
Features
- Compiles your Typescript program to get complete type information.
- Translates required properties, extends, annotation keywords, property initializers as defaults. You can find examples for these features in the test examples.
Usage
Command line
- Install with
npm install typescript-json-schema -g
- Generate schema from a typescript type:
typescript-json-schema project/directory/tsconfig.json TYPE
To generate files for only some types in tsconfig.json
specify
filenames or globs with the --include
option. This is especially useful for large projects.
In case no tsconfig.json
is available for your project, you can directly specify the .ts files (this in this case we use some built-in compiler presets):
- Generate schema from a typescript type:
typescript-json-schema "project/directory/**/*.ts" TYPE
The TYPE
can either be a single, fully qualified type or *
to generate the schema for all types.
Usage: typescript-json-schema <path-to-typescript-files-or-tsconfig> <type>
Options:
--refs Create shared ref definitions. [boolean] [default: true]
--aliasRefs Create shared ref definitions for the type aliases. [boolean] [default: false]
--topRef Create a top-level ref definition. [boolean] [default: false]
--titles Creates titles in the output schema. [boolean] [default: false]
--defaultProps Create default properties definitions. [boolean] [default: false]
--noExtraProps Disable additional properties in objects by default. [boolean] [default: false]
--propOrder Create property order definitions. [boolean] [default: false]
--required Create required array for non-optional properties. [boolean] [default: false]
--strictNullChecks Make values non-nullable by default. [boolean] [default: false]
--useTypeOfKeyword Use `typeOf` keyword (https://goo.gl/DC6sni) for functions. [boolean] [default: false]
--out, -o The output file, defaults to using stdout
--validationKeywords Provide additional validation keywords to include [array] [default: []]
--include Further limit tsconfig to include only matching files [array] [default: []]
--ignoreErrors Generate even if the program has errors. [boolean] [default: false]
--excludePrivate Exclude private members from the schema [boolean] [default: false]
--uniqueNames Use unique names for type symbols. [boolean] [default: false]
--id Set schema id. [string] [default: ""]
Programmatic use
; ; // optionally pass argument to schema generator; // optionally pass ts compiler options // optionally pass a base path; ; // We can either get the schema for one file and one type...; // ... or a generator that lets us incrementally get more schemas ; // all symbols; // Get symbols for different types from generator.generator.getSchemaForSymbol"MyType";generator.getSchemaForSymbol"AnotherType";
// In larger projects type names may not be unique,// while unique names may be enabled.; ; // A list of all types of a given name can then be retrieved.; // Choose the appropriate type, and continue with the symbol's unique name.generator.getSchemaForSymbolsymbolList.name; // Also it is possible to get a list of all symbols.;
getSymbols('<SymbolName>')
and getSymbols()
return an array of SymbolRef
, which is of the following format:
;
getUserSymbols
and getMainFileSymbols
return an array of string
.
Annotations
The schema generator converts annotations to JSON schema properties.
For example
will be translated to
Note that we needed to use @TJS-type
instead of just @type
because of an issue with the typescript compiler.
Background
Inspired and builds upon Typson, but typescript-json-schema is compatible with more recent Typescript versions. Also, since it uses the Typescript compiler internally, more advanced scenarios are possible.
Debugging
npm run debug -- test/programs/type-alias-single/main.ts --aliasRefs true MyString
And connect via the debugger protocol.