JSON Schema Artifact Bundler

Common errors

• SyntaxError: Cannot use import statement outside a module

  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.
  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: ...

  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`.
  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'

  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.
  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'

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

Warnings

• breaking 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).
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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`.
  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.

Install

• npm install json-schema-artifact npm
• yarn add json-schema-artifact yarn
• pnpm add json-schema-artifact pnpm

Imports

• defineConfig
  wrong:

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

  correct:

  import { defineConfig } from '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.

Quickstart

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