Registry / devops / json-schema-migrate

json-schema-migrate

library2.0.0jsnpmunverified

Migrates JSON Schema between drafts: draft-04 to draft-07, draft-2019-09, or draft-2020-12. Current stable version is 2.0.0. Maintained as part of the Ajv validator ecosystem. Key differentiators: supports multiple target drafts, handles draft-04-specific patterns like boolean exclusiveMinimum, single-value enum to const, and empty/not schemas. Release cadence is low; updates are infrequent. Alternatives include manual schema transformation or using Ajv's own migration utilities, but this package provides a dedicated, focused tool.

devops

npm install json-schema-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-MIGRAT

json-schema-migrate

devopsjavascriptv2.0.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.

default

✓ const migrate = require('json-schema-migrate')

✗ import migrate from 'json-schema-migrate' (CJS-only package, no ESM)

The package does not provide an ESM entry; use require() in Node. For ES modules, use createRequire or dynamic import.

draft7

✓ migrate.draft7(schema)

✗ migrate.draft07(schema) (incorrect function name)

Function names are draft7, draft2019, draft2020 – no leading zeros in draft-07 name.

draft2019

✓ migrate.draft2019(schema)

✗ migrate.draft2019(schema, options) (no second argument)

Functions mutate the schema object in place and return nothing.

Shows migrating a draft-04 schema with boolean exclusiveMinimum to draft-07, using default import and draft7 function.

const migrate = require('json-schema-migrate'); const oldSchema = { id: 'my-schema', type: 'string', minimum: 1, exclusiveMinimum: true }; migrate.draft7(oldSchema); console.log(JSON.stringify(oldSchema, null, 2)); // Output: // { // "$id": "my-schema", // "type": "string", // "exclusiveMinimum": 1 // }

Debug

Known issues

gotchaThe migration mutates the input schema object in place. Do not pass an object you need to keep unchanged.

fix

Clone the schema first: const cloned = JSON.parse(JSON.stringify(original));

affects: >=1.0.0

deprecatedThe 'constant' keyword (non-standard) is replaced with 'const' during migration. If you rely on 'constant', update your schema.

fix

Use 'const' directly in your source schema.

affects: >=1.0.0

gotchadraft2019 migration rewrites 'definitions' to '$defs'. Any code referencing 'schema.definitions' will break after migration.

fix

After migration, use '$defs' instead of 'definitions'.

affects: >=1.0.0

breakingVersion 2.0.0 dropped support for Node < 6.0.0. Also, the package no longer exports a bundled Ajv instance via 'migrate.ajv'; use 'migrate.getAjv()' instead.

fix

Update Node to >=6.0.0 and replace 'migrate.ajv' with 'migrate.getAjv()'.

affects: >=2.0.0

gotchaThe 'draft2020' migration converts array 'items' to 'prefixItems' and renames 'additionalItems' to 'items'. This can break existing consumers expecting the old structure.

fix

After migration, update any logic that accesses schema.items to handle the new prefixItems structure.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot assign to read only property 'type' of object '#'

Trying to migrate a frozen or read-only schema object; migration mutates the schema.

fix

Ensure the schema object is mutable (not frozen or from a read-only source like Object.freeze).

migrate.draft7 is not a function

Incorrect default import; package is CJS-only, so using ESM import may result in an object without the expected functions.

fix

Use const migrate = require('json-schema-migrate'); (CJS) or dynamic import with .default property: const migrate = (await import('json-schema-migrate')).default;

Schema is not valid JSON Schema

The input schema is syntactically invalid according to draft-04. Migration runs validation before transforming.

fix

Ensure the schema is a valid JSON Schema draft-04 object; check for missing required properties or malformed keywords.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

ajvrequiredAjv is used internally to validate and migrate schemas; the package uses a bundled Ajv instance.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/epoberezkin/json-schema-migrate ↗

packagejson-schema-migrate ↗

homepagehttps://github.com/epoberezkin/json-schema-migrate#readme ↗