Registry / serialization / json-schema-artifact

json-schema-artifact

library2.0.3jsnpmunverified

json-schema-artifact is a utility designed to bundle and optimize JSON Schemas, facilitating their use in development and production environments. Currently at version 2.0.3, this project shows active development with recent patch releases in the v2 series. Its release cadence appears to follow common open-source practices, with updates occurring as needed to introduce features, fix bugs, and align with evolving JSON Schema specifications. Key differentiators include robust support for multiple configuration formats (ESM, JSON, YAML, TypeScript) via `defineConfig`, built-in optimization options such as minification and dereferencing, and an integrated localization system that supports `t('key')` syntax for dynamic content. It also features a watch mode for development and provides direct integration recommendations for VSCode's schema validation, making it a comprehensive solution for managing complex JSON Schema ecosystems.

serialization devops data

npm install json-schema-artifact

github ↗package ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-ARTIFA

json-schema-artifact

serializationjavascriptv2.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

defineConfig

✓ import { defineConfig } from 'json-schema-artifact';

✗ const defineConfig = require('json-schema-artifact');

Primarily intended for ESM configuration files (e.g., json-schema-artifact.mjs or .ts). The CommonJS `require` syntax is not supported for this export and will result in a runtime error.

This quickstart demonstrates how to configure json-schema-artifact using an ESM file, bundling a main schema, including localized content, applying optimizations like minification and dereferencing, and setting up watch paths for development.

import { defineConfig } from "json-schema-artifact"; import path from "path"; export default defineConfig([ { input: { file: path.resolve(process.cwd(), "src/main-schema.json"), locales: { en: path.resolve(process.cwd(), "locales/en.yaml"), fr: path.resolve(process.cwd(), "locales/fr.yaml") } }, output: { dir: path.resolve(process.cwd(), "dist"), optimize: { minify: true, dereference: "flatten" }, filename: "bundled-schema-[locale].json" }, watch: [path.resolve(process.cwd(), "src"), path.resolve(process.cwd(), "locales")] } ]); // To run this: // 1. Save as json-schema-artifact.mjs in your project root. // 2. Ensure 'src/main-schema.json', 'locales/en.yaml', 'locales/fr.yaml' exist. // 3. Run: npx json-schema-artifact

json-schema-artifact --version

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes. Users upgrading from v1.x should review the project's changelog for specific migration steps. These changes may involve updates to configuration file structure or API calls, similar to how the core JSON Schema specification itself has introduced breaking changes between drafts (e.g., $recursiveRef to $dynamicRef, array-form items to prefixItems in earlier spec versions).

fix

Consult the official `json-schema-artifact` GitHub repository or npm page for a detailed changelog or migration guide for version 2.0.0. Adapt configuration files and schema definitions as necessary.

affects: >=2.0.0

gotchaWhen using localization with the `t('key')` syntax, ensure that the JSONPath expression for 'key' precisely matches a path within your configured locale files (JSON or YAML). Incorrect paths will lead to unresolved localization strings in the output schema.

fix

Verify the `key` string in `t('key')` against the structure of your locale files. Use valid JSONPath expressions. Check console output for warnings about unresolved localization keys during the build process.

affects: >=1.0.0

gotchaWhile `json-schema-artifact` supports multiple configuration file formats (ESM, JSON, YAML, TypeScript), using the `defineConfig` helper is exclusive to ESM or TypeScript files. Attempting to use `defineConfig` in a CommonJS (`.js` without `type: module`) or static JSON/YAML file will cause errors.

fix

For `defineConfig`, ensure your configuration file is named `.mjs` or `.ts` and that your project environment supports ESM imports. For static configurations, use `.json` or `.yaml` files directly without the `defineConfig` wrapper.

affects: >=1.0.0

gotchaWhen integrating generated schemas into VSCode's `settings.json` for validation, always ensure that the `url` property correctly points to the output path of your bundled schema. Changes in the output directory, filename, or `[locale]` placeholders (if used) in your `json-schema-artifact` configuration will require corresponding updates in `settings.json`.

fix

Periodically verify that the `url` in `.vscode/settings.json` matches the actual output path and filename (including any locale suffixes) of the generated schema artifacts. Rebuild your schemas after configuration changes to confirm output paths.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use `import { defineConfig } from 'json-schema-artifact';` in a CommonJS (.js) file without `"type": "module"` in `package.json`, or a file named with a .cjs extension.

fix

Rename your configuration file to `json-schema-artifact.mjs` or `json-schema-artifact.ts`, or ensure your `package.json` contains `"type": "module"` if using a `.js` extension for ESM. If using CommonJS, define your configuration as a plain JSON or YAML file.

Error: Config file not found at path: ...

The `json-schema-artifact` CLI could not locate a configuration file (e.g., `json-schema-artifact.mjs`, `.json`, `.yaml`, `.yml`, `.ts`) in the current working directory or at the path specified by `--config`.

fix

Create a configuration file in the project root with one of the supported names, or explicitly specify its path using `npx json-schema-artifact --config ./path/to/my-config.mjs`.

Error: Failed to resolve schema reference 'some#/path/to/schema.json'

A `$ref` within one of your input JSON Schemas points to a path that the bundler cannot find or resolve, either locally or via a network request if configured for remote resolution.

fix

Verify that all `$ref` paths in your schemas are correct relative to the input file or other known schema locations. Ensure referenced files exist and are accessible by the bundler. Check for typos or incorrect base URIs.

Error: Localization key 'my.missing.key' not found for locale 'en'

The `t('my.missing.key')` syntax was used in a schema, but 'my.missing.key' does not exist in the specified `en` locale file.

fix

Review your locale files (e.g., `locales/en.yaml`) to ensure that the JSONPath `my.missing.key` exists and has a defined value. Correct the key in your schema or add the missing entry to the locale file.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/dongchengjie/json-schema-artifact ↗

packagehttps://www.npmjs.com/package/json-schema-artifact ↗