JSON Schema Model (jsm)

Generates TypeScript decorated with class-validator decorators based on a json-schema.

State of Development

This project is envisioned as a way of gaining access to strongly typed definitions/components from the Swagger json-schema dialect, with pure json-schema a nice-to-have. But some differences from Swagger to json-schema were difficult to reconcile and led to headaches. Finally, class-validator accepts json-schema in its validation tools, but the decorators are a disjoint language against Swagger and json-schema. Meaning there are 3 potential sources of validation information. In the end, the specific keywords supported were driven as much by what was possible as what I thought was "right".'

Which might beg the question: why do all this? Well, one answer is that this project makes sense if you consider json-schema/Swagger as a means of validating serialized objects in transit or at rest. But once the JSON was hydrated, there is a role for the object that contains the hydrated instance to continue the original schema's validation with run time checks as well as the values it mutates along its lifetime.

This library does not try to connect the lifetimes of the JSON and the object in any way. If you use Swagger, the swagger-tools will pull these objects out of definitions and paths and return you a plain old JS object - you get it in the request object. You can pass that POJO into one of these constructors and once validated, serialize it again knowing it has to be valid. Anyway, that's the idea.

Contributors: You are welcome! Some of what this thing lacks:

• unit tests
• A means for allowing consumers to substitute their own generation templates
• Code review
• Better documentation

To get a good feel for what this does, check the repo's models/ and out/ directories and consider each file pair *.yaml -> *.ts

Installation

This is a CLI tool, not a library so you will need to install it globally.

sudo npm install @terryweiss/jsm -g

Technical Docs

A description of the internal API for contributors can be found on github or locally.

CLI

This is a static code generator, there is no API, just a CLI. The options are:

• --help Show help
• --version Show version number
• --log-level Sets the logging level for the process. Choices are "trace", "debug", "warn", "data", "log", "info", "warn", "error"
• -i, --infiles The path to your schema files, can be a glob to yaml or json files or a mix thereof. It uses a globbing library, so you can be creative.
• -o, --outpath The path to write the files to. Class paths are appended to this
• -r, --rootName When dealing with a schema that does not contains a root element, you can name the resultant object with this. This is only valuable when you generating from a single file.

Examples

You can find a set of hcard derived models in the models/ folder. Output is found in out/ in the repo.

Validation keywords

json.schema.model supports the common subset of keywords from swagger and jon-schema. Where the interpretations are in conflict, this tends to prefer swagger.

Common keywords

• name This is specific to json.schema.model and is used to name a class from the key of the object definition. it is auto-populated and is available in the template that generates the code.

{
    "MyModel": { // <-- this is the name property of the runtime generator
        "type": "object",
        "properties":{}
    }
}

• title:string as in json-schema
• description:string as in json-schema
• x-is-defined:boolean Extension for class-validator, checks if value is defined (!== undefined, !== null)
• required:array as in json-schema
• const:string as in json-schema. Also as x-equals. Checks if value equals ("===") comparison.
• x-not-equals as in class-validator. Checks if value not equal ("!==") comparison.
• x-empty:boolean as in class-validator. Checks if given value is empty (=== '', === null, === undefined).
• x-not-empty:boolean as in class-validator. Checks if given value is not empty (!== '', !== null, !== undefined).
• x-in:array as in class-validator. Checks if value is in a array of allowed values.
• x-not-in:array as in class-validator. Checks if value is not in a array of disallowed values.
• x-default specify a default value for the property
• string, number, integer, boolean, array, object data type keywords as in json-schema

Object keywords

• x-model-name:string specify a name for the generated class
• x-model-path:string specify a path (starting from outFiles option) that the module should be written
• x-namespace:string Used for documentation only when defining the @module keyword
• x-extends:string If this is a subclass of some other class, put that class path here

Array keywords

• minItems, maxItems, uniqueItems as in json-schema
• x-contains:array as in class-validator. Checks if array contains all values from the given array of values.
• x-not-contains:array as in class-validator. Checks if array does not contain any of the given values.
• items:array as in swagger which is always an array

Date keywords

• x-min-date:Date|string as in class-validator. Checks if the value is a date that's after the specified date.
• x-max-date:Date|string as in class-validator. Checks if the value is a date that's before the specified date.

Integer/Number keywords

• minimum, maximum, multipleOf as json-schema
• x-positive-number:boolean as in class-validator. Checks if the value is a positive number.
• x-negative-number:boolean as in class-validator. Checks if the value is a negative number.

String keywords

• minLength, maxLength, pattern as in json-schema
• x-contains:string as in class-validator. Checks if the string contains the seed.
• x-not-contains as in class-validator. Checks if the string not contains the seed.

String formats

This tool tries to supply the union of what json-schema and class-validator defines for strings. Admittedly, not well. But there it is. json_schema

• hostname
• email
• ipv4
• ipv6
• uri
• date-time, date, time These all create a Date object

class-validator

• base64
• ascii
• alphanumeric
• alpha
• number-string
• date-string
• boolean-string
• iso8601
• militaryTime
• json
• lowerCase
• upperCase
• mongoId
• uuid

Using JSM

As stated above, this is a CLI tool. At it's simplest you can create models from a directory like so:

jsm -f "models/*.yaml" -o ../src/models 

From a swagger file:

jsm -f "api.yaml" -o ../src/models
# or for a json file
jsm -f "api.json" -o ../src/models

Using globs you can get a whole directory and its subdirectories:

jsm -f "models/**/*.yaml" -o ../src/models

When you produce your files, you can access them like any other file:

const {Address} = require("./models/Address");
const adr = new Address();

Let's say you have an existing object you got from a CSV file. You can pass that object in (once it has been shaped) and validate it right away:

const {Address} = require("./models/Address");
const val = someJsonFromSomewhere();
const adr = new Address(val);
adr.validate().then((validationErrors)=>{
	if (validationErrors.length === 0){ 
	// do something cool
	}else{
		console.log("Validation failed:\n", validationErrors);
	}
}).catch((e)=>{
	console.error(e);
})

To get all this delicious sugar in your bloodstream, you must install jsm as above. But you must also install three other dependencies in the project that gets the output:

sudo npm install @scrawl/json.schema.model -g
# then install local runtime dependencies
npm install class-transformer-validator class-transformer class-validator --save

Some more notes

If you are not using TypeScript, you will need to take one further step to use the generated files. You must install the TypeScript compiler and use it turn the generated files into something usable. It does require a few special flags to compile correctly.

tsc --target es2015 --lib 'ES2015' --module 'commonjs' --sourceMap --outDir ./myDir myFile # or files

Add this command to your package.json, webpack, gulp, or grunt file.

Some more more notes

The files that are generated are completely generated every time. Any changes you make to a generated file will be lost the next time you run jsm. But, these are just classes, and simple classes at that. To customize the behavior of these classes, just inherit from them and customize your behavior there.