AJV Command Line Interface

0.12.0 verified Sun Apr 19 auth: no javascript

ajv-cmd provides a robust command-line interface (CLI) for performing essential operations on JSON Schema files, leveraging the powerful AJV (Another JSON Schema Validator) library. It enables users to dereference, validate, transpile, and test JSON Schema definitions directly from the terminal, streamlining schema management and integration into build processes. The current stable version is 0.12.0. While no explicit release cadence is stated, its `0.x.x` versioning coupled with recent GitHub activity suggests active development and potentially rapid iterations. A key differentiator is its modern approach, requiring Node.js 24+, and its commitment to supply chain security standards like SLSA 3 and OpenSSF Scorecard, building upon the foundation of `ajv-cli` with a focus on contemporary JavaScript environments and best practices. It's primarily designed for developers who need to automate schema validation and compilation within CI/CD pipelines or local development workflows, providing a convenient wrapper around AJV's extensive capabilities.

Common errors

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

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

yarn add ajv-cmd

pnpm add ajv-cmd

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/