jirutka / ajv-cli

Command-line interface for Ajv JSON Validator

Ajv CLI

Command line interface for Ajv, a JSON Schema validator.

This is a fork of the original ajv-cli 5 with many improvements (see below).

Changes from ajv-cli 5

Notable changes from the original ajv-cli 5.

New features

• A new human-friendly error format pretty that combines the source file location and JSON path of the invalid value, followed by a code span (a snippet of the validated file) with an in-place error message (see Pretty format in Examples).

• A new error format line: <filepath>:<line>:<column> - <message> (see Line format in Examples).

• Support for the Code Climate Issue format compatible with the Code Quality report in GitLab CI (see Code Climate format in Examples).

• A validate option --merge-errors, enabled by default, to merge related errors per instance path instead of reporting individual schema errors as returned by Ajv (see JSON format without merging errors in Examples).

• A validate option --errors-location to add the source location (filename, line and column number) of each invalid value to validation errors (see JSON format with location in Examples).

• A compile option --code-esm to export the validate function(s) as ECMAScript Modules (ESM) instead of CommonJS (see code.esm in Ajv options).

• Workaround to fix incorrect schemaPath in validation errors (see src/ajv-schema-path-workaround.ts and ajv-validator/ajv#512).

(Breaking) Changes

• -d option has been replaced with positional arguments (ajv validate -s <schema> <data-file>…​).

• --no-<option> no longer works, boolean options can be disabled as --<option>=false or --<option> false.

• The validate command is no longer implicit, it must always be specified (e.g. ajv validate [options], not ajv [options]).

• Limited glob support – The bloated Glob dependency has been replaced by picomatch and a custom implementation to traverse directories. However, it’s a simplified solution that does not support complex nested globs (e.g. alpha/beta/*.{yml,d/**/*.yml}).

• The default error format has been changed from js to pretty.

• The line format has been renamed to json-oneline.

• The text format for errors has been replaced by the jsonpath format.

• Only (structured) validation errors (see --errors) and changes (see --changes) are printed to stdout, all other messages are logged to stderr.

• --strict-schema is disabled by default* (i.e. unknown keywords and formats are ignored) to comply with the JSON Schema specification.

• ajv compile prints the generated code to stdout instead of nowhere if the -o option is not specified.

• The default value of --inline-refs has been changed from true to 8 to speed up schema compilation (and validation).

• If --spec is not provided, it’s determined by the $schema URI in the first passed schema (-s). It will only fallback to draft-07 if it’s not found.

• ajv-cli is now transpiled to ECMAScript Modules (ESM) instead of CommonJS.

Removed features

• The test command (use validate instead).

• The migrate command.

• Support for loading schema and data files via require and omitting the .json extension in file paths.

• Support for loading custom keywords modules in TypeScript.

• Loading schemas and data in the JSON5 format (CJSON is still supported).

Install

Using npm

npm install --global @jirutka/ajv-cli

Download from Releases

ajv-cli is also provided as a single JavaScript file with bundled dependencies, requiring only Node.js (version 20 or later) on the system.

curl -LO  https://github.com/jirutka/ajv-cli/releases/download/v6.0.0-beta.5/ajv.cjs
curl -fsSL https://github.com/jirutka/ajv-cli/releases/download/v6.0.0-beta.5/checksums.txt | sha256sum -c --ignore-missing
install -D -m755 ajv.cjs /usr/local/bin/ajv

Usage

Refer to ajv validate --help and ajv compile --help.

Examples

Pretty format

$ ajv validate -s schema.json data-invalid-1.yml

--> data-invalid-1.yml:6:10
    #/www.encom.com/CNAME

    |   A: 1.2.3.4
    | www.encom.com:
    |   owners: flynnsam
  6 |   CNAME: [ encom.com ]
    |          ^^^^^^^^^^^^^ must be string or object
    | tron.encom.com:
    |   owners: [ flynnkev, bradlala ]
    |   A: 1.2.3.5

Line format

$ ajv validate -s schema.json --errors=line data-invalid-1.yml

data-invalid-1.yml:6:10 - must be string or object

JSON format

$ ajv validate -s schema.json --errors=json data-invalid-1.yml

[
  {
    "message": "must be string or object",
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainObject/properties/CNAME/anyOf"
  }
]

JSON format with location

$ ajv validate -s schema.json --errors=json --errors-location data-invalid-1.yml

[
  {
    "message": "must be string or object",
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainObject/properties/CNAME/anyOf",
    "instanceLocation": {
      "filename": "data-invalid-1.yml",
      "start": {
        "line": 6,
        "col": 10
      },
      "end": {
        "line": 6,
        "col": 23
      }
    }
  }
]

JSON format verbose

$ ajv validate -s schema.json --errors=json --verbose data-invalid-1.yml

[
  {
    "message": "must be string or object",
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainObject/properties/CNAME/anyOf",
    "data": [
      "encom.com"
    ],
    "schema": [
      {
        "$ref": "#/$defs/DomainName"
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rdata"
        ],
        "properties": {
          "rdata": {
            "$ref": "#/$defs/DomainName"
          },
          "ttl": {
            "type": "number"
          }
        }
      }
    ],
    "parentSchema": {
      "anyOf": [
        {
          "$ref": "#/$defs/DomainName"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "rdata"
          ],
          "properties": {
            "rdata": {
              "$ref": "#/$defs/DomainName"
            },
            "ttl": {
              "type": "number"
            }
          }
        }
      ]
    }
  }
]

JSON format without merging errors

$ ajv validate -s schema.json --errors=json --merge-errors=false data-invalid-1.yml

[
  {
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainName/type",
    "keyword": "type",
    "params": {
      "type": "string"
    },
    "message": "must be string"
  },
  {
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainObject/properties/CNAME/anyOf/1/type",
    "keyword": "type",
    "params": {
      "type": "object"
    },
    "message": "must be object"
  },
  {
    "instancePath": "/www.encom.com/CNAME",
    "schemaPath": "#/$defs/DomainObject/properties/CNAME/anyOf",
    "keyword": "anyOf",
    "params": {},
    "message": "must match a schema in anyOf"
  }
]

Code Climate format

$ ajv validate -s schema.json --errors=code-climate data-invalid-1.yml

[
  {
    "description": "[schema] #/www.encom.com/CNAME must be string or object",
    "check_name": "json-schema",
    "fingerprint": "344ef8205ab8c5dea3b0ebd537519dfb005c5f5c",
    "severity": "major",
    "location": {
      "path": "data-invalid-1.yml",
      "positions": {
        "begin": {
          "line": 6,
          "column": 10
        },
        "end": {
          "line": 6,
          "column": 23
        }
      }
    }
  }
]

Credits

• This project is a fork of the original ajv-cli written by Evgeny Poberezkin.

• The code for merging related Ajv validation errors is taken from the vscode-lintlens project by Gabriel McAdams.

License

This project is licensed under MIT License.