tselect-npm/schema

Typed, programmatic JSON schemas.

Schema

Typed, composable JSON schemas. This module consumes and produces JSON schemas with little to no processing.

Installation

npm i @tselect/schema [--save]

Disclaimer

This module takes the following positions:

• additionalProperties for object schemas is false unless you specify a value
• additionalItems for array schemas is false unless you specify a value

Motivation

Writing JSON schemas for large applications can be pretty time consuming. Having to type double quotes and "additionalProperties" for each new object by hand is no fun.

This module has been created with the intention of reducing the overhead of describing JSON by providing simple wrappers and utilities to manage common use cases with easiness.

It is also fully typed and will allow you to benefit from your favorite IDE's auto-completion, making typing a lot easier.

Usage

Building a schema

import { object, email } from '@tselect/schema';

const schema = object({
  foo: email()
});

Produces:

schema = {
  type: 'object',
  additionalProperties: false, // Default, see disclaimer
  properties: {
    foo: {
      type: 'string',
      format: 'email'
    }
  }
}

Manipulating a schema

import { object, email, integer, omitProperties } from '@tselect/schema';

const schema = object({
  foo: email(),
  bar: integer()
}, {
  required: ['foo', 'bar']
});

const modified = omitProperties(schema, ['bar']);

Produces:

modified = {
 type: 'object',
 required: ['foo'], // Only foo is kept as required
 additionalProperties: false, // Default, see disclaimer
 properties: {
   foo: { // No bar property anymore
     type: 'string',
     format: 'email'
   }
 }
}

Nullable types

import { string } from '@tselect/schema';

const schema = string({ nullable: true });

Produces:

schema = {
  type: ['string', 'null']
}

JSON schema compatibility

Any JSON schema you already wrote can be manipulated using this module.

import { object } from '@tselect/schema';

const schema = object({}, {
  type: 'object',
  required: ['foo'],
  additionalProperties: true,
  properties: {
    foo: {
      type: 'string',
      format: 'email'
    }
  }
}) 

Produces the exact same schema :

schema = {
  type: 'object',
  required: ['foo'],
  additionalProperties: true,
  properties: {
    foo: {
      type: 'string',
      format: 'email'
    }
  } 
};

schema's Issues

🔧 Remove additionalProperties defaulting to false

Not explicitly defaulting it to false makes it align with the JSONSchema spec:

Spec:

The additionalProperties keyword is used to control the handling of extra stuff, that is, properties whose names are not listed in the properties keyword. By default any additional properties are allowed.

Relevant code: https://github.com/bluebirds-blue-jay/schema/blob/master/src/factories/object.ts#L11

🐛 Insufficient isJSONSchema check

The isJSONSchema function ( https://github.com/bluebirds-blue-jay/inversify-controller/blob/master/src/utils/is-json-schema.ts ) is insufficient and delivers a false return value when passing in at least anyOf or oneOf schema.

The check is used in at least 3 locations (listed end of issue) like this:

const jsonSchema = isJSONSchema(options) ? options : options.jsonSchema;

This results in an undefined jsonSchema being used when passing in said anyOf or oneOf schemas.

Very poor fix: (Turn the condition around... 🙃 )
const jsonSchema = isJSONSchema(options.jsonSchema) ? options.jsonSchema : options;

Proper fix:
Have the isJSONSchema return true for all types of Schemas (at least but not limited to anyOf and oneOf).

https://github.com/bluebirds-blue-jay/inversify-controller/blob/master/src/decorators/body.ts#L14
https://github.com/bluebirds-blue-jay/inversify-controller/blob/master/src/decorators/query.ts#L14
https://github.com/bluebirds-blue-jay/inversify-controller/blob/master/src/decorators/params.ts#L14