maas-schemas

MaaS-schemas submodule

This repository contains the JSON schemas used by MaaS.

Features

• Ajv compatible JSON Schemas
• io-ts codecs for TypeScript

JavaScript API

The schemas can be used together with Ajv as follows.

Validate an object by first resolving the corresponding schema by schemaId NOTE: It is recommended to use schema $id instead of raw schema object

import * as mjsv from 'maasglobal-json-schema-validator';
import registry from 'maas-schemas/lib/ajv/registry';

const validator = mjsv.validator([registry]);

const phone = validator.validate(
  'https://schemas.maas.global/core/components/common.json#/definitions/phone',
  '[phone]',
);

TypeScript API

The repostory also contains io-ts codecs that match the JSON Schema definitions. The TypeScript validators should work with any JavaScript compatible code but have the added benefit of producing an output type that match the schema as closely as possible.

Runtime Input Validation

In this basic use example we show how to use the codecs together with the io-ts-validator. The four alternative decode calls are alternative ways suiting different control flow and error handling models. The validator also contains matching encode calls for converting a decoded booking back to raw json.

import { validator } from 'io-ts-validator';
import Booking from 'maas-schemas/lib/io-ts/core/booking';

validator(Booking).decodeSync(json);     // returns Booking, throws on errors
validator(Booking).decodePromise(json);  // returns Promise<Booking>, rejects on errors
validator(Booking).decodeEither(json);   // returns Either<Array<string>, Booking>
validator(Booking).decodeAsync(json, (errors, booking) => { ... });  // returns void

JavaScript Type Signatures

In previous chapter we showed how to use the package for basic runtime input validation. However, the io-ts codecs defined in this package are also compatibile with static type systems. You can use JSDoc comments to add type signatures to your existing JavaScript code. This makes it possible for an IDE to validate the types in realtime as you are typing code in your code editor.

const { validator } = require('io-ts-validator');
const { IdentityId } = require('maas-schemas/lib/io-ts/core/components/units');
/** @typedef {import('maas-schemas/lib/io-ts/core/components/units').IdentityId} IdentityId */

/** Ignores an identity id
 *
 * @param {IdentityId} id
 * @returns {void}
 */
function ignore(id) {
  // Nothing to do
}

const raw = '916715ef-2e04-47e0-b1a5-feece4861c66';
const valid = validator(IdentityId).decodeSync(raw);

ignore(raw); // type error: string !== IdentityId
ignore(valid); // no error

TypeScript Type Signatures

If you end up using static types a lot, you may wish to use the TypeScript compiler for post processing of your JavaScript code. The TypeScript compiler can check your static type signatures at compile time and also lets you create special .ts files with embedded type signatures. For an example of embeded type signatures, see the example below.

import { validator } from 'io-ts-validator';
import { IdentityId } from 'maas-schemas/lib/io-ts/core/components/units';

function ignore(id: IdentityId): void {
  // Nothing to do
}

const raw = '916715ef-2e04-47e0-b1a5-feece4861c66';
const valid = validator(IdentityId).decodeSync(raw);

ignore(raw); // type error: string !== IdentityId
ignore(valid); // no error

Development

Automatic Conversion

Parts of the maas-schemas package are generated automatically. CI won't accept any changes to maas-schemas unless you run the converter. You can run the converter as follows.

yarn              # install dependencies
yarn convert-all  # run the converter

Documentation

Markdown and HTML documentation can be generated from JSON Schemas. To generate documentation from JSON Schemas, execute:

yarn build
yarn docs

After that, documentation will be available in Markdown format in docs/ folder and in HTML format in docs/html folder.