joi-to-json

library5.0.5jsnpmunverified

A library to convert Joi validation schemas to JSON Schema (Draft 04, 07, 2019-09, 2020-12) and OpenAPI 3.0/3.1 formats. Current stable version v5.0.5, released Nov 2024, supports Joi v17.13.3 and v18.0.0. Built on Joi's public describe() API, avoiding internal dependencies. Offers multiple output types via a single parse() function. Key differentiator: official Joi describe-based conversion with broad output standard support, unlike older libraries relying on private APIs.

testing

npm install joi-to-json

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JOI-TO-JSON

joi-to-json

testingjavascriptv5.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import parse from 'joi-to-json'

✗ import { parse } from 'joi-to-json'

Default export. Named import 'parse' is incorrect.

default

✓ const parse = require('joi-to-json')

✗ const { parse } = require('joi-to-json')

CommonJS require returns the default export directly.

parse (TypeScript)

✓ import parse from 'joi-to-json'

✗ import * as parse from 'joi-to-json'

TypeScript finds no named exports; use default import.

Shows basic usage converting a Joi schema to JSON Schema and OpenAPI, including custom definitions and options.

import Joi from 'joi'; import parse from 'joi-to-json'; const schema = Joi.object({ name: Joi.string().min(2).max(100).required(), age: Joi.number().integer().min(0).max(150).default(30), email: Joi.string().email({ tlds: { allow: false } }) }); // JSON Schema Draft 07 (default) const jsonSchema = parse(schema); console.log(JSON.stringify(jsonSchema, null, 2)); // OpenAPI 3.0 const openApiSchema = parse(schema, 'open-api'); console.log(JSON.stringify(openApiSchema, null, 2)); // With definitions and options const definitions = { MyType: Joi.string().uri() }; const options = { includeSchemaDialect: true }; const schemaWithDefs = parse(schema, 'json', definitions, options); console.log(JSON.stringify(schemaWithDefs, null, 2));

Debug

Known issues

breakingv4 dropped support for Joi v16 and below. Only Joi v17.13.3+ and v18.0.0 are supported.

fix

Upgrade Joi to v17.13.3+ or v18.0.0.

affects: >=4.0.0

gotchaJoi's describe() output changed in minor versions (e.g., 17.13.3 vs 17.11). Always use Joi versions listed in peerDependencies.

fix

Pin joi-to-json and Joi to exact versions during development.

affects: *

gotchaCircular Joi schemas (e.g., self-referencing links) may cause infinite recursion in parse(). Not detected or handled.

fix

Avoid circular references or manually break the cycle with a maxDepth option (not available).

affects: *

gotchaJoi.any() with no type constraints converts to a generic empty schema ({}), which may not validate as expected in JSON Schema validators.

fix

Add explicit Joi constraints (e.g., .valid(), .allow()) to produce meaningful schema.

affects: *

deprecatedOutput type 'open-api' (for OpenAPI 3.0) is labeled as 'Standalone for OpenAPI 3.0 Schema - an extended subset of JSON Schema Specification Wright Draft 00'. New projects should use 'open-api-3.1'.

fix

Use 'open-api-3.1' for modern OpenAPI.

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: parse is not a function

Using named import instead of default import: import { parse } from 'joi-to-json'

fix

Use default import: import parse from 'joi-to-json'

Cannot find module 'joi-to-json'

Package not installed from npm, or version mismatch when using older Node.js (CJS resolution fails for ESM-only projects)

fix

Run 'npm install joi-to-json'. If using ESM, ensure package.json has 'type': 'module' or use .mjs extension.

joi-to-json: Unsupported Joi version. Please use joi@17.13.3 or above.

Installed Joi version is below 17.13.3

fix

Upgrade Joi: npm install joi@latest (at least 17.13.3)

TypeError: joiObj.describe is not a function

Passed a non-Joi object (e.g., plain object) to parse()

fix

Ensure first argument is a Joi schema created via Joi.object(), Joi.string(), etc.

Upgrade

Version history

5.0.5latest on npm

Audit

Dependencies

joirequiredPeer dependency - used to describe schemas. Works with v17.x and v18.x.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/kenspirit/joi-to-json ↗

packagejoi-to-json ↗

homepagehttps://github.com/kenspirit/joi-to-json#readme ↗