ajv-cmd

library0.12.0jsnpmunverified

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.

devops serialization

npm install ajv-cmd

github ↗package ↗

INSTALL

IMPORT

SIG · AJV-CMD

ajv-cmd

devopsjavascriptv0.12.0

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.

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.

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/

ajv-cmd --version

Debug

Known issues

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

affects: >=0.1.0

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

affects: >=0.1.0

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

affects: >=0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

ajv: command not found

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.

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

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'

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

Upgrade

Version history

0.12.0latest on npm

Audit

Dependencies

ajvrequiredCore JSON Schema validation and compilation engine.

commanderrequiredUsed for parsing command-line arguments and structuring the CLI.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/willfarrell/ajv-cmd ↗

packagehttps://www.npmjs.com/package/ajv-cmd ↗