Registry / devops / json-schema-for-openapi

json-schema-for-openapi

library0.5.0jsnpmunverified

Converts standard JSON Schema (draft-07, 2019-09, 2020-12) to an OpenAPI v3.0.x compatible Schema Object. Current stable version is 0.5.0, released irregularly with breaking changes (v0.3.0 removed built-in $ref handling). Key differentiators: focused solely on v3.0.x compatibility (not v3.1.x), handles specific JSON Schema features unsupported by v3.0.x — converting items from array to object, multiple types to oneOf, const to enum, null type to nullable, and default values to proper OpenAPI types. Does NOT dereference $ref; users must pre-process with a separate dereferencing library. Lightweight with no runtime dependencies.

devops

npm install json-schema-for-openapi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-FOR-OP

json-schema-for-openapi

devopsjavascriptv0.5.0

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.

convertOpenApi

✓ import { convertOpenApi } from 'json-schema-for-openapi'

Default export is deprecated; use named export convertOpenApi.

convertSchemaObj

✓ import { convertSchemaObj } from 'json-schema-for-openapi'

✗ const { convertSchemaObj } = require('json-schema-for-openapi')

Library is ESM-only. CommonJS require may work in some bundlers but is not guaranteed.

convertSchemaObj

✓ import { convertSchemaObj } from 'json-schema-for-openapi'

Returns a Promise; must be awaited.

Converts a JSON Schema with multiple unsupported patterns (array items, null type, const) to OpenAPI v3.0.x compatible schema object.

import { convertOpenApi } from 'json-schema-for-openapi'; const jsonSchema = { type: 'object', properties: { id: { type: 'string' }, price: { type: ['number', 'null'] }, tags: { type: 'array', items: [{ type: 'string' }] }, status: { type: 'string', const: 'active' } } }; async function convert() { const openApiSchema = await convertOpenApi(jsonSchema); console.log(JSON.stringify(openApiSchema, null, 2)); } convert();

Debug

Known issues

breakingAs of v0.3.0, built-in $ref resolution was removed. You must dereference your schema before passing to the converter.

fix

Pre-process your schema with @apidevtools/json-schema-ref-parser: const dereferenced = await $RefParser.dereference(schema);

affects: >=0.3.0

deprecatedDefault export (convertOpenApi) is deprecated in favor of named export convertSchemaObj.

fix

Use import { convertSchemaObj } instead of import convertOpenApi.

affects: >=0.4.0

gotchaWhen converting array items from an array to object, only the first item is used. Multiple item schemas are discarded.

fix

Ensure array items are either a single schema object or only one schema in the array. Manually merge if needed.

affects: >=0.1.0

gotchaThe library does not handle recursive $ref or circular references. Conversion may throw or produce invalid output.

fix

Use a dereferencing library to flatten schemas before conversion, and check for circular refs.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'properties')

Passing an undereferenced schema that still contains unresolved $ref nodes.

fix

Dereference the schema first: const deref = await $RefParser.dereference(schema); then call convertSchemaObj(deref);

TypeError: convertSchemaObj is not a function

Using the deprecated default export import instead of named import.

fix

Change to: import { convertSchemaObj } from 'json-schema-for-openapi';

Error: 'items' must be an object, not an array

The library expects 'items' to be an object, but JSON Schema allows an array (for tuple validation). It converts but logs a warning; if the error occurs, the schema might have been pre-processed incorrectly.

fix

Ensure input is standard JSON Schema; if necessary, manually convert items array to a single object before calling the library.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

@apidevtools/json-schema-ref-parseroptionalRequired to dereference $ref before conversion (since v0.3.0 removed internal resolving)

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/JaredCE/json-schema-to-openAPI-schema-object ↗

packagejson-schema-for-openapi ↗

homepagehttps://github.com/JaredCE/json-schema-to-openAPI-schema-object#readme ↗