I have been using joi a lot in different Node.js projects to guard the API. It's The most powerful schema description language and data validator for JavaScript. as it said.
Many times, we need to utilize this schema description to produce other output, such as Swagger OpenAPI doc. That is why I build joi-route-to-swagger in the first place.
At the beginning, joi-route-to-swagger
relies on joi-to-json-schema which utilizes many joi internal api or properties. Maybe joi did not provide the describe
api way before, but I always feel uncomfortable of relying on internal api.
The intention of joi-to-json
is to support converting different version's joi schema to JSON Schema using describe
api.
The implementation of this JOI to JSON conversion tool is simply a pipeline of two components:
Convertors
joi.describe()
output to the baseline format (currently the v16 and v17 one)Parsers
Although the versions chosen are the latest one for each major version, It should support other minor versions as well.
npm install joi-to-json
Only one API parse
is available.
Its signature is parse(joiObj, type = 'json', definitions = {}, parserOptions = {})
json
- Default. Stands for JSON Schema Draft 07open-api
- Stands for OpenAPI 3.0 Schema - an extended subset of JSON Schema Specification Wright Draft 00 (aka Draft 5)open-api-3.1
- Stands for OpenAPI 3.1 Schema - a superset of JSON Schema Specification Draft 2020-12json-draft-04
- Stands for JSON Schema Draft 04json-draft-2019-09
- Stands for JSON Schema Draft 2019-09The output schema format are in outputs under specific folders for different types.
Sample code is as below:
const parse = require('joi-to-json')
const joiSchema = joi.object().keys({
nickName: joi.string().required().min(3).max(20).example('鹄思乱想').description('Hero Nickname')
.regex(/^[a-z]+$/, { name: 'alpha', invert: true }),
avatar: joi.string().required().uri(),
email: joi.string().email(),
ip: joi.string().ip({ version: ['ipv4', 'ipv6'] }),
hostname: joi.string().hostname().insensitive(),
gender: joi.string().valid('Male', 'Female', '').default('Male'),
height: joi.number().precision(2).positive().greater(0).less(200),
birthday: joi.date().iso(),
birthTime: joi.date().timestamp('unix'),
skills: joi.array().items(joi.alternatives().try(
joi.string(),
joi.object().keys({
name: joi.string().example('teleport').alphanum().lowercase().required().description('Skill Name'),
level: joi.number().integer().min(10).max(100).default(50).multiple(10).example(10).description('Skill Level')
})
).required()).min(1).max(3).unique().description('Skills'),
tags: joi.array().items(joi.string().required()).length(2),
retired: joi.boolean().truthy('yes').falsy('no').insensitive(false),
certificate: joi.binary().encoding('base64'),
notes: joi.any().meta({ 'x-supported-lang': ['zh-CN', 'en-US'], deprecated: true })
})
const jsonSchema = parse(joiSchema)
// Or parsing to OpenAPI schema through:
// const openApiSchema = parse(joiSchema, 'open-api')
This should be a JSON object containing all schemas referenced by the joiObj
definition. It's useful if Named Link case is used but the referenced schemas are provided externally. This object uses the schema id as key and schema itself as value.
includeSchemaDialect
: Default to be false
. true
makes the parsed schema containing $schema
field automatically. Value of the $schema
is default for different output JSON format if it's not provided in options together.logicalOpParser
: Refer to Special Joi Operator Support below for detail usage.Supports named link for schema reuse, such as .link('#person')
. For open-api
conversion, as the shared schemas are located in #/components/schemas
which is not self-contained, the conversion result contains an extra schemas
field so that you can extract it when required.
Starting from Draft 7, JSON Specification supports If-Then-Else
style expression. Before that, we can also use something called Implication using Schema Composition Approach to simulate that.
By default, the If-Then-Else
approach is used if the output spec supports it. However, if the joi conditional expression (alternatives
or when
) is annotated using Meta .meta({ 'if-style': false })
, the JSON schema conversion will use the Composition approach using allOf
and/or anyOf
instead.
Limitation: Currently, if the joi condition definition is referring to another field, the If-Then-Else
style output is not supported. Instead, it simply uses the anyOf
composing the then
and otherwise
on the defined field.
Most Joi specifications result in the expected OpenAPI schema.
E.g.,
const joi = require('joi')
const { dump } = require('js-yaml')
const { writeFile } = require('fs/promises')
const joiSchema = joi.object().keys({
uuid: joi.string().uuid({ version: ['uuidv3', 'uuidv5'] }),
nickName: joi.string().required().example('鹄思乱想').description('Hero Nickname').min(3).max(20).pattern(/^[a-z]+$/, { name: 'alpha', invert: true }),
avatar: joi.string().required().uri(),
email: joi.string().email(),
ip: joi.string().ip({ version: ['ipv4', 'ipv6'] }),
hostname: joi.string().hostname().insensitive(),
gender: joi.string().valid('Male', 'Female', '', null).default('Male'),
isoDateString: joi.string().isoDate(),
isoDurationString: joi.string().isoDuration(),
birthday: joi.date().iso(),
certificate: joi.binary().encoding('base64'),
tags: joi.array().items(joi.string().required()).length(2),
nested: joi.object().keys({
key: joi.string()
}).unknown(true)
}).unknown(false)
async function writeYAML(targetPath) {
const openApiSchema = parse(joiSchema, 'open-api')
const openApiSchemaYAML = dump(openApiSchema, {lineWidth: 120, noCompatMode: true})
await writeFile(targetPath, openApiSchemaYAML)
}
results in
type: object
required:
- nickName
- avatar
properties:
uuid:
type: string
format: uuid
nickName:
description: Hero Nickname
type: string
pattern: ^[a-z]+$
minLength: 3,
maxLength: 20,
example: 鹄思乱想
avatar:
type: string
format: uri
email:
type: string
format: email
ip:
type: string
oneOf:
- format: ipv4
- format: ipv6
hostname:
type: string
format: hostname
gender:
type: string
default: Male
enum:
- Male
- Female
- ''
- null
nullable: true
isoDateString:
type: string
format: date-time
isoDurationString:
type: string
format: duration
birthday:
type: string
format: date-time
certificate:
type: string
format: binary
tags:
type: array
items:
type: string
minItems: 2
maxItems: 2
nested:
type: object
properties:
key:
type: string
additionalProperties: true
additionalProperties: false
Some OpenAPI features are not supported directly in Joi, but Joi schemas can be annotated with joi.any().meta({…})
to get them in the OpenAPI schema:
…
const joiSchema = joi.object().keys({
deprecatedProperty: joi.string().meta({ deprecated: true }).required(),
readOnlyProperty: joi.string().meta({ readOnly: true }),
writeOnlyProperty: joi.string().meta({ writeOnly: true }),
xMeta: joi.string().meta({ 'x-meta': 42 }),
unknownMetaProperty: joi.string().meta({ unknownMeta: 42 })
}).unknown(true)
…
begets:
type: object
required:
- deprecatedProperty
properties:
deprecatedProperty:
type: string
deprecated: true
readOnlyProperty:
type: string
readOnly: true
writeOnlyProperty:
type: string
writeOnly: true
xMeta:
type: string
x-meta: 42
unknownMetaProperty:
type: string
# unknownMeta is not exported
additionalProperties: true
For generating JSON Schema in a browser you should use below import syntax for joi
library in order to work because the joi
browser minimized build does not have describe
api which the joi-to-json
relies on.
import Joi from 'joi/lib/index';
import joi from 'joi';
import * as Joi2Json from 'joi-to-json';
import parse from 'joi-to-json';
const logicalOpParser: Joi2Json.LogicalOpParserOpts = {
with: function (a) {}
};
parse(joi.string()); // Default call
parse(joi.string(), 'json', {}, { logicalOpParser: false }); // Completely disable Logical Relation Operator
parse(joi.string(), 'open-api', {}, { logicalOpParser }); // Partially override Logical Relation Operator
npm run test
fixtures-conversion
folder stores each JOI version's supported keyword for different data types.
In case any data type or keyword is not supported in historical JOI version, we can just create customized file to override the base
version, such as v15/link.js
.
Standard converted results are stored in outputs-conversion
folder.
test/conversion.spec.js
Test Spec handles all supported JOI versions' conversion verificaiton.
outputs-parsers
folder stores different output formats base on the JOI Standard Representation in outputs-conversion
folder.
The Test Spec under test/parser/
are responsible for these area.
For special Logical Relation Operator and Conditional Expression, some Unit Tests are created to verify the JOI Spec and corresponding JSON Spec are valid of the same verification intention.
When running conversion.spec.js
, below environment variables can be set:
TEST_CONVERTOR
: control which version of joi to test.
Example: TEST_CONVERTOR=v17
TEST_CASE
: control which test cases to verify. Name of the test cases is the key of the return object in fixtures-conversion
.
Example: TEST_CASE=conditional,match_all
verifies the case in alternatives.js
TEST_UPDATE_CONVERSION_BASELINE
: control whether writes the baseline file generated from the latest-version convertor (Currently v17
).
It is activated when setting to true
.When runninng Test Spec under test/parser
, below environment variables can be set:
TEST_CASE
: control which test cases to verify.
For example, when running json.spec.js
, and set TEST_CASE=conditional,match_all
, it verifies the corresponding JSON files in outputs-parsers/json/alternatives
.TEST_UPDATE_PARSER_BASELINE
: control whether writes the baseline file for the corresponding parser.
It is activated when setting to true
. For example, when running json.spec.js
, it writes the baseline files under outputs-parsers/json
.object.pattern
usage in Joi, pattern
parameter can only be a regular expression now as I cannot convert Joi object to regex yet.If-Then-Else
style output is not applicable for the condition referring to the other field.MIT