{"id":15665,"library":"json-schema-artifact","title":"JSON Schema Artifact Bundler","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/dongchengjie/json-schema-artifact","tags":["javascript","json-schema","bundler"],"install":[{"cmd":"npm install json-schema-artifact","lang":"bash","label":"npm"},{"cmd":"yarn add json-schema-artifact","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-schema-artifact","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const defineConfig = require('json-schema-artifact');","symbol":"defineConfig","correct":"import { defineConfig } from 'json-schema-artifact';"}],"quickstart":{"code":"import { defineConfig } from \"json-schema-artifact\";\nimport path from \"path\";\n\nexport default defineConfig([\n  {\n    input: {\n      file: path.resolve(process.cwd(), \"src/main-schema.json\"),\n      locales: {\n        en: path.resolve(process.cwd(), \"locales/en.yaml\"),\n        fr: path.resolve(process.cwd(), \"locales/fr.yaml\")\n      }\n    },\n    output: {\n      dir: path.resolve(process.cwd(), \"dist\"),\n      optimize: {\n        minify: true,\n        dereference: \"flatten\"\n      },\n      filename: \"bundled-schema-[locale].json\"\n    },\n    watch: [path.resolve(process.cwd(), \"src\"), path.resolve(process.cwd(), \"locales\")]\n  }\n]);\n\n// To run this:\n// 1. Save as json-schema-artifact.mjs in your project root.\n// 2. Ensure 'src/main-schema.json', 'locales/en.yaml', 'locales/fr.yaml' exist.\n// 3. Run: npx json-schema-artifact","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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).","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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`.","cause":"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`.","error":"Error: Config file not found at path: ..."},{"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.","cause":"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.","error":"Error: Failed to resolve schema reference 'some#/path/to/schema.json'"},{"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.","cause":"The `t('my.missing.key')` syntax was used in a schema, but 'my.missing.key' does not exist in the specified `en` locale file.","error":"Error: Localization key 'my.missing.key' not found for locale 'en'"}],"ecosystem":"npm"}