@ffz/joi-to-schema

NPM Version Node Version Dependency Status Build Status Test Coverage

Convert Joi Schema into JSON Schema. This was written after examining a few other libraries that do this and being dissatisfied with how they're written or how they behave. This library:

  • Throws errors when it doesn't support something. Validation should never do anything silently.
  • Uses Joi.describe() rather than digging into Joi's internals to discover the layout of the Joi schema.
  • Supports Joi.alternatives().try()
  • Supports ordered items and alternative items for Joi.array()
  • In general, supports everything that's reasonable to support.

This library does not support:

  • Joi.alternatives().when() It's theoretically possible to support when() but the code complexity and my lack of any use-cases for it made me shy away for now.

Install

$ npm install @ffz/joi-to-schema --save

Documentation

Basic Usage

import Converter from '@ffz/joi-to-schema';
import Joi from 'joi';

const converter = new Converter();

converter.convert(Joi.object({
    id: Joi.number().integer().positive().required(),
    name: Joi.string(),
    email: Joi.string().email().required(),
    avatar: Joi.string().allow(null),
    verified: Joi.boolean().default(false)
}))

Schema Extraction

This library supports extracting sub-trees from converted schematics and storing them in a central location. To enable this behavior, you need to pass an option to the Converter to allow extraction.

const converter = new Converter({
    extract: true
});

Then, you attach extract metadata to the part of your schema that you would like to extract. This will result in that sub-tree of the output being extracted and stored in converter.schemas while a reference will be saved into the generated schema.

const converter = new Converter({
    extract: true,
    extractPath: '/components/schemas/'
})

converter.convert(Joi.object({
    height: Joi.number().integer().positive().required(),
    width: Joi.number().integer().positive().required(),
    urls: Joi.object({
        '1x': Joi.string().uri().required(),
        '2x': Joi.string().uri(),
        '4x': Joi.string().uri()
    }).required()
}).meta({
    extract: 'HighDPIImage'
}));

// {
//     '$ref': '#/components/schemas/HighDPIImage
// }


converter.schemas

// {
//     components: {
//         schemas: {
//             HighDPIImage: {
//                 ...
//             }
//         }
//     }
// }

Tests

Run tests using npm test.

Contributions and Support

Please submit all issues and pull requests to the FrankerFaceZ/joi-to-schema repository.