AJV Command Line Interface

Common errors

• ajv: command not found

  cause The `ajv-cmd` package's executable (`ajv`) is not in your system's PATH. This usually happens when installed locally without using `npx` or without adding `node_modules/.bin` to PATH.
  fix When installed locally, use `npx ajv ...` or add `./node_modules/.bin` to your system's PATH. If installed globally (`npm install -g ajv-cmd`), ensure your global `npm` bin directory is in your PATH.

• Error: This package requires Node.js version >=24.

  cause You are running `ajv-cmd` with an incompatible Node.js version.
  fix Update your Node.js environment to version 24 or higher. Use a Node Version Manager (e.g., `nvm install 24`, `nvm use 24`) to easily switch versions.

• Schema failed validation: keyword 'type' expected string, got object at #/properties/name

  cause Your JSON Schema contains an error preventing successful validation or compilation by AJV.
  fix Carefully review your JSON Schema for syntax errors, incorrect keywords, or violations of the JSON Schema specification. Use a schema linter or online validator to pinpoint issues.

• Error: Cannot find module 'ajv-cmd/src/commands/validate.js'

  cause You are attempting to import an internal module path of `ajv-cmd` that either does not exist, has changed, or is not intended for public consumption.
  fix Avoid importing directly from `ajv-cmd/src/...` paths. This package is designed for command-line use. If programmatic validation or transpilation is required, use the core `ajv` library directly or rely on `ajv-cmd` via `child_process` (e.g., `execa`).

Warnings

• breaking ajv-cmd requires Node.js version >=24. Running it with older Node.js versions will result in an error.
  Fix: Upgrade your Node.js environment to version 24 or newer. Consider using a Node Version Manager (NVM) to manage multiple Node.js installations.
• gotcha The package is in `0.x.x` versioning, indicating that its API and CLI options may undergo breaking changes in minor releases. Always review release notes when upgrading.
  Fix: Pin your `ajv-cmd` dependency to a specific minor version (e.g., `"ajv-cmd": "~0.12.0"`) or explicitly test upgrades across minor versions.
• gotcha When using `ajv-cmd` programmatically via internal paths (e.g., `ajv-cmd/src/commands/validate.js`), these paths are implementation details and not part of the public API. They are highly susceptible to change without notice, leading to import errors.
  Fix: Prefer using `ajv-cmd` strictly as a command-line interface tool, as it is primarily designed for this purpose. If programmatic access is essential, consider using the underlying `ajv` library directly.
• gotcha Using strict validation modes (e.g., `--strict true`) and type coercion (`--coerce-types`) can lead to unexpected validation failures or data transformations if not fully understood, especially with complex schemas.
  Fix: Thoroughly test your schemas and data with these options. Refer to the official AJV documentation for a complete understanding of strict mode and type coercion behavior. Start with less strict options and gradually enable them as needed.

Install

• npm install ajv-cmd npm
• yarn add ajv-cmd yarn
• pnpm add ajv-cmd pnpm

Imports

• validate

  import { validate } from 'ajv-cmd/src/commands/validate.js'

  ajv-cmd is primarily a CLI tool. While the core command logic is exported from internal paths, these are not considered a stable public API and are subject to change between minor versions. Prefer CLI usage (`ajv validate ...`).
• transpile

  import { transpile } from 'ajv-cmd/src/commands/transpile.js'

  Similar to `validate`, the `transpile` function is exported from an internal path. This package's primary interface is its command-line utility. Direct programmatic use via these internal paths is discouraged for stability reasons.
• test

  import { test } from 'ajv-cmd/src/commands/test.js'

  The `test` function, like other command logic, is exported from an internal module path. Relying on these internal paths for programmatic use is not recommended due to potential breaking changes in non-major versions. Use the `ajv test` CLI command instead.

Quickstart

This quickstart demonstrates how to install `ajv-cmd` and use its `validate` and `transpile` commands within a bash script to process multiple JSON Schema files. It shows common `ajv` options for strict validation and transpilation.

#!/usr/bin/env bash

# Install ajv-cmd as a development dependency
npm install -D ajv-cmd

# Define a function to validate and transpile a schema
function bundle_schema {
  # Validate the schema with strict mode, type coercion, all errors, and default values
  ajv validate "${1}" --valid \
    --strict true --coerce-types array --all-errors true --use-defaults empty

  # Transpile the schema to a JavaScript file
  ajv transpile "${1}" \
    --strict true --coerce-types array --all-errors true --use-defaults empty \
    -o "${1%.json}.js"
}

# Create a dummy schema file for demonstration
mkdir -p handlers/user
echo '{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0, "default": 18 }
  },
  "required": ["name"]
}' > handlers/user/schema.create.json

# Loop through all schema files in handlers/ and process them
for file in handlers/*/schema.*.json; do
  echo "Processing: $file"
  if ! bundle_schema "$file"; then
    echo "$file failed processing." >&2
    exit 1
  fi
  echo "Successfully processed $file"
done

echo "\nCheck the 'handlers/' directory for generated JS files."

# Clean up dummy schema file
# rm -rf handlers/