npmpackage.info

Gathering detailed insights and metrics for joi-to-json

Other packages similar to joi-to-json

joi-to-json-schema

5.1.0

Joi -> JSON Schema Converter

superstruct

2.0.2

A simple and composable way to validate data in JavaScript (and TypeScript).

ut-joi

1.4.11

joi to JSON Schema Converter

@metamask/superstruct

3.1.0

A simple and composable way to validate data in JavaScript (and TypeScript).

joi-to-json

Capable of converting different versions' joi object to json schema

4.3.1

MIT

JavaScript

29.57 kB

4,736,197 2.9

Installations

npm install joi-to-json

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

20.10.0

NPM Version

10.2.3 Score

98.7

Supply Chain

99.6

Quality

82.5

Maintenance

100

Vulnerability

99.6

License

Pull Requests

Open

3

Total

24

Closed

8

Merged

13

Issues

Open

4

Total

30

Closed

26

Releases

Unable to fetch releases

Contributors

View all 9 contributors

Languages

JavaScript

JavaScript (100%)

Developer

kenspirit

Download Statistics

Total Downloads

4,736,197

Last Day

8,031

Last Week

36,423

Last Month

175,263

Last Year

3,054,672

GitHub Statistics

40 Stars

76 Commits

19 Forks

5 Watching

5 Branches

9 Contributors

Bundle Size

88.56 kB

Minified

29.57 kB

Minified + Gzipped

Bundlephobia

Maintainers

Package Meta Information

Latest Version

4.3.1

Package Id

joi-to-json@4.3.1

Unpacked Size

61.46 kB

Size

15.53 kB

File Count

NPM Version

10.2.3

Node Version

20.10.0

Publised On

14 Jan 2025

Total Downloads

Cumulative downloads

Total Downloads

4,736,197

Last day

-23.8%

8,031

Compared to previous day

Last week

-26.5%

36,423

Compared to previous week

Last month

3.5%

175,263

Compared to previous month

Last year

208.2%

3,054,672

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

combinations lodash semver-compare

Dev Dependencies

@jest/transform ajv ajv-draft-04 eslint jest joi-12 joi-13 joi-14 joi-15 joi-16 joi-17

Versions

joi-to-json

Objective

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

Each JOI version has one convertor implementation.
It converts the joi.describe() output to the baseline format (currently the v16 and v17 one)

Parsers

Each supported output JSON format (e.g. JSON Draft 07, OpenAPI) has one parser implementation.
All parsers converts the baseline format into its own format

Joi Version Support

@commercial/joi
- v12.1.0
joi
- 13.7.0
- 14.3.1
@hapi/joi
- 15.1.1
- 16.1.8
joi
- 17.9.2

Although the versions chosen are the latest one for each major version, It should support other minor versions as well.

Installation

npm install joi-to-json

Usage

Only one API parse is available.

Its signature is parse(joiObj, type = 'json', definitions = {}, parserOptions = {})

Output Type

json - Default. Stands for JSON Schema Draft 07
open-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-12
json-draft-04 - Stands for JSON Schema Draft 04
json-draft-2019-09 - Stands for JSON Schema Draft 2019-09

The output schema format are in outputs under specific folders for different types.

Sample code is as below:

1const parse = require('joi-to-json')
2
3const joiSchema = joi.object().keys({
4  nickName: joi.string().required().min(3).max(20).example('鹄思乱想').description('Hero Nickname')
5    .regex(/^[a-z]+$/, { name: 'alpha', invert: true }),
6  avatar: joi.string().required().uri(),
7  email: joi.string().email(),
8  ip: joi.string().ip({ version: ['ipv4', 'ipv6'] }),
9  hostname: joi.string().hostname().insensitive(),
10  gender: joi.string().valid('Male', 'Female', '').default('Male'),
11  height: joi.number().precision(2).positive().greater(0).less(200),
12  birthday: joi.date().iso(),
13  birthTime: joi.date().timestamp('unix'),
14  skills: joi.array().items(joi.alternatives().try(
15    joi.string(),
16    joi.object().keys({
17      name: joi.string().example('teleport').alphanum().lowercase().required().description('Skill Name'),
18      level: joi.number().integer().min(10).max(100).default(50).multiple(10).example(10).description('Skill Level')
19    })
20  ).required()).min(1).max(3).unique().description('Skills'),
21  tags: joi.array().items(joi.string().required()).length(2),
22  retired: joi.boolean().truthy('yes').falsy('no').insensitive(false),
23  certificate: joi.binary().encoding('base64'),
24  notes: joi.any().meta({ 'x-supported-lang': ['zh-CN', 'en-US'], deprecated: true })
25})
26
27const jsonSchema = parse(joiSchema)
28// Or parsing to OpenAPI schema through:
29// const openApiSchema = parse(joiSchema, 'open-api')

definitions

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.

parserOptions

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.

Features

Special Joi Operator Support

Logical Relation Operator

Named Link

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.

Conditional Expression

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.

YAML File Generation

Most Joi specifications result in the expected OpenAPI schema.

E.g.,

1const joi = require('joi')
2const { dump } = require('js-yaml')
3const { writeFile } = require('fs/promises')
4
5const joiSchema = joi.object().keys({
6  uuid: joi.string().uuid({ version: ['uuidv3', 'uuidv5'] }),
7  nickName: joi.string().required().example('鹄思乱想').description('Hero Nickname').min(3).max(20).pattern(/^[a-z]+$/, { name: 'alpha', invert: true }),
8  avatar: joi.string().required().uri(),
9  email: joi.string().email(),
10  ip: joi.string().ip({ version: ['ipv4', 'ipv6'] }),
11  hostname: joi.string().hostname().insensitive(),
12  gender: joi.string().valid('Male', 'Female', '', null).default('Male'),
13  isoDateString: joi.string().isoDate(),
14  isoDurationString: joi.string().isoDuration(),
15  birthday: joi.date().iso(),
16  certificate: joi.binary().encoding('base64'),
17  tags: joi.array().items(joi.string().required()).length(2),
18  nested: joi.object().keys({
19    key: joi.string()
20  }).unknown(true)
21}).unknown(false)
22
23async function writeYAML(targetPath) {
24  const openApiSchema = parse(joiSchema, 'open-api')
25
26  const openApiSchemaYAML = dump(openApiSchema, {lineWidth: 120, noCompatMode: true})
27  await writeFile(targetPath, openApiSchemaYAML)
28}

results in

1type: object
2required:
3  - nickName
4  - avatar
5properties:
6  uuid:
7    type: string
8    format: uuid
9  nickName:
10    description: Hero Nickname
11    type: string
12    pattern: ^[a-z]+$
13    minLength: 3,
14    maxLength: 20,
15    example: 鹄思乱想
16  avatar:
17    type: string
18    format: uri
19  email:
20    type: string
21    format: email
22  ip:
23    type: string
24    oneOf:
25      - format: ipv4
26      - format: ipv6
27  hostname:
28    type: string
29    format: hostname
30  gender:
31    type: string
32    default: Male
33    enum:
34      - Male
35      - Female
36      - ''
37      - null
38    nullable: true
39  isoDateString:
40    type: string
41    format: date-time
42  isoDurationString:
43    type: string
44    format: duration
45  birthday:
46    type: string
47    format: date-time
48  certificate:
49    type: string
50    format: binary
51  tags:
52    type: array
53    items:
54      type: string
55    minItems: 2
56    maxItems: 2
57  nested:
58    type: object
59    properties:
60      key:
61        type: string
62    additionalProperties: true
63additionalProperties: 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:

1…
2
3const joiSchema = joi.object().keys({
4  deprecatedProperty: joi.string().meta({ deprecated: true }).required(),
5  readOnlyProperty: joi.string().meta({ readOnly: true }),
6  writeOnlyProperty: joi.string().meta({ writeOnly: true }),
7  xMeta: joi.string().meta({ 'x-meta': 42 }),
8  unknownMetaProperty: joi.string().meta({ unknownMeta: 42 })
9}).unknown(true)
10
11…

begets:

1type: object
2required:
3  - deprecatedProperty
4properties:
5  deprecatedProperty:
6    type: string
7    deprecated: true
8  readOnlyProperty:
9    type: string
10    readOnly: true
11  writeOnlyProperty:
12    type: string
13    writeOnly: true
14  xMeta:
15    type: string
16    x-meta: 42
17  unknownMetaProperty:
18    type: string
19    # unknownMeta is not exported
20additionalProperties: true

Browser support

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.

1  import Joi from 'joi/lib/index';

TypeScript support

1import joi from 'joi';
2import * as Joi2Json from 'joi-to-json';
3import parse from 'joi-to-json';
4
5const logicalOpParser: Joi2Json.LogicalOpParserOpts = {
6  with: function (a) {}
7};
8
9parse(joi.string()); // Default call
10parse(joi.string(), 'json', {}, { logicalOpParser: false }); // Completely disable Logical Relation Operator
11parse(joi.string(), 'open-api', {}, { logicalOpParser }); // Partially override Logical Relation Operator

Test

npm run test

Categories of Test Cases

JOI Standard Representation Conversion

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.

JSON output format Conversion

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.

JSON schema (Draft 07) Validity Unit Test

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.

Test Debug Approach

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.

Known Limitation

For 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.

License

MIT

No vulnerabilities found.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

6

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

2

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

1

Maintained

Determines if the project is "actively maintained".

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

Score

2.9

/10

Last Scanned on 2025-01-27

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More