io-ts-to-json-schema

io-ts-to-json-schema

Transform io-ts codecs to json schema.

Escape hatch for interfacing io-ts and json schema validations.

usage/examples

npm i io-ts-to-json-schema
# fp-ts and io-ts are package peerDependencies
# so make sure you have these also installed

import * as t from 'io-ts';
import { toJsonSchema } from 'io-ts-to-json-schema';

const codec = t.type({
    a: t.string,
    b: t.union([t.string, t.null]),
});

toJsonSchema(codec);
// {
//     "type": "object",
//     "description": "{ a: string, b: (string | null) }",
//     "properties": {
//         "a": {
//             "type": "string",
//             "description": "string"
//         },
//         "b": {
//             "anyOf": [
//                 {
//                     "type": "string",
//                     "description": "string"
//                 },
//                 {
//                     "type": "null",
//                     "description": "null"
//                 }
//             ],
//             "description": "(string | null)"
//         }
//     },
//     "required": [
//         "a",
//         "b"
//     ]
// }

features

• built-in codec support table

codec	status	comment
t.null	✅	-
t.string	✅	-
t.number	✅	-
t.bigint	⚠️	treated like number
t.boolean	✅	-
t.undefined	⚠️	unrepresentable in JSON, falls back to {}
t.void	⚠️	unrepresentable in JSON, falls back to {}
t.any	⚠️	unrepresentable in JSON, falls back to {}
t.unknown	⚠️	unrepresentable in JSON, falls back to {}
t.UnknownArray	⚠️	unrepresentable in JSON, falls back to { type: 'array', items: {} }
t.UnknownRecord	⚠️	unrepresentable in JSON, falls back to { type: 'object' }
t.Function	⚠️	unrepresentable in JSON, falls back to {}
t.Refinement	⚠️	unrepresentable in JSON, falls back to {}
t.literal	✅	-
t.recursion	✅	due to single top down codec traversal, additional definitions may be placed in other places than root level $deps. see the tests
t.array	✅	-
t.type	✅	-
t.partial	✅	-
t.record	✅	assumes domain is string
t.union	✅	-
t.intersection	✅	-
t.tuple	✅	-
t.readonly	✅	-
t.readonlyArray	✅	-
t.strict	✅	-
t.keyof	✅	-
t.exact	✅	-

• output customization

Each node in the schema can be customized or completely replaced. This allows you to add support for your custom t.Types.

const codec = t.type(
    {
        a: t.string,
        b: t.union([t.string, t.null], 'StringOrNull'),
    },
    'FooBar',
);

const descriptions = {
    FooBar: 'some description for foobar',
    StringOrNull: 'some description for string | null',
};

// e.g. attaching custom descriptions
const schema = toJsonSchema(codec, {
    customizer: (schema, codec, context) => ({
        ...schema,
        description: descriptions[codec.name],
    }),
});
// {
//     "type": "object",
//     "required": [
//         "a",
//         "b"
//     ],
//     "properties": {
//         "a": {
//             "type": "string"
//         },
//         "b": {
//             "anyOf": [
//                 {
//                     "type": "string"
//                 },
//                 {
//                     "type": "null"
//                 }
//             ],
//             "description": "some description for string | null"
//         }
//     },
//     "description": "some description for foobar"
// }

• codec customization

Each entered codec can be manipulated beforehand.

const codec = t.type(
    {
        a: t.string,
        b: t.union([t.string, t.null], 'StringOrNull'),
    },
    'FooBar',
);

const schema = toJsonSchema(codec, {
    codecCustomizer: codec => {
        if (codec.name !== 'FooBar' || !(codec instanceof t.InterfaceType)) return codec;

        // omit single field
        const { a: _, ...props } = codec.props;

        return t.type(props, codec.name);
    },
});
// {
//     "type": "object",
//     "required": [
//         "b"
//     ],
//     "properties": {
//         "b": {
//             "anyOf": [
//                 {
//                     "type": "string"
//                 },
//                 {
//                     "type": "null"
//                 }
//             ]
//         }
//     },
// }