Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ajv-validator/ajv-cli

Command-line interface for Ajv JSON Validator
https://github.com/ajv-validator/ajv-cli
ajv command-line json-schema validator
Last synced: about 1 month ago
JSON representation
Command-line interface for Ajv JSON Validator
Host: GitHub
URL: https://github.com/ajv-validator/ajv-cli
Owner: ajv-validator
License: mit
Created: 2015-07-22T05:12:28.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2023-06-21T22:25:02.000Z (over 1 year ago)
Last Synced: 2024-05-18T00:41:38.514Z (6 months ago)
Topics: ajv, command-line, json-schema, validator
Language: TypeScript
Homepage: https://ajv.js.org
Size: 192 KB
Stars: 254
Watchers: 6
Forks: 63
Open Issues: 80
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project

README

        # ajv-cli

Command line interface for [ajv](https://github.com/epoberezkin/ajv), one of the [fastest json schema validators](https://github.com/ebdrup/json-schema-benchmark).

Supports [JSON](http://json.org/), [JSON5](http://json5.org/), and [YAML](http://yaml.org/).

[![build](https://github.com/ajv-validator/ajv-cli/workflows/build/badge.svg)](https://github.com/ajv-validator/ajv-cli/actions?query=workflow%3Abuild)

[![npm](https://img.shields.io/npm/v/ajv-cli.svg)](https://www.npmjs.com/package/ajv-cli)

[![coverage](https://coveralls.io/repos/github/ajv-validator/ajv-cli/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv-cli?branch=master)

[![gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)

## Contents

- [Installation](#installation)

- [JSON schema version](#json-schema-version)

- Commands

  - [Help](#help-command)

  - [Validate data](#validate-data)

  - [Compile schemas](#compile-schemas)

  - [Migrate schemas](#migrate-schemas)

  - [Test validation result](#test-validation-result)

- [Ajv options](#ajv-options)

- [Version History, License](#version_history)

## Installation

```sh

npm install -g ajv-cli

```

## JSON schema language and version

Parameter `--spec` can be used with all commands (other than help) to choose JSON schema language:

- `--spec=draft7` (default) - support JSON Schema draft-07 (uses `import Ajv from "ajv"`)

- `--spec=draft2019` - support JSON Schema draft-2019-09 (uses `import Ajv from "ajv/dist/2019"`)

- `--spec=draft2020` - support JSON Schema draft-2020-12 (uses `import Ajv from "ajv/dist/2020"`)

- `--spec=jtd` - support [JSON Type Definition](https://ajv.js.org/json-type-definition.html) (uses `import Ajv from "ajv/dist/jtd"`)

## Commands

### Help command

```sh

ajv help

ajv help validate

ajv help compile

ajv help migrate

ajv help test

```

### Validate data

This command validates data files against JSON-schema

```sh

ajv validate -s test/schema.json -d test/valid_data.json

ajv -s test/schema.json -d test/valid_data.json

```

You can omit `validate` command name and `.json` from the [input file names](https://nodejs.org/api/modules.html#modules_file_modules).

#### Parameters

##### `-s` - file name of JSON-schema

Only one schema can be passed in this parameter

##### `-d` - JSON data

Multiple data files can be passed, as in `-r` parameter:

```sh

ajv -s test/schema.json -d "test/valid*.json"

```

If some file is invalid exit code will be 1.

##### `-r` - referenced schemas

The schema in `-s` parameter can reference any of these schemas with `$ref` keyword.

Multiple schemas can be passed both by using this parameter multiple times and with [glob patterns](https://github.com/isaacs/node-glob#glob-primer). Glob pattern should be quoted and extensions cannot be omitted.

##### `-m` - meta-schemas

Schemas can use any of these schemas as a meta-schema (that is the schema used in `$schema` keyword - it is used to validate the schema itself).

Multiple meta-schemas can be passed, as in `-r` parameter.

##### `-c` - custom keywords/formats definitions

You can pass module(s) that define custom keywords/formats. The modules should export a function that accepts Ajv instance as a parameter. The file name should start with ".", it will be resolved relative to the current folder. The package name can also be passed - it will be used in require as is.

These modules can be written in TypeScript if you have `ts-node` installed.

For example, you can use `-c ajv-keywords` to add all keywords from [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package or `-c ajv-keywords/keywords/typeof` to add only typeof keyword.

#### Options

- `--errors=`: error reporting format. Possible values:

  - `js` (default): JavaScript object

  - `json`: JSON with indentation and line-breaks

  - `line`: JSON without indentation/line-breaks (for easy parsing)

  - `text`: human readable error messages with data paths

- `--changes=`: detect changes in data after validation.


  Data can be modified with [Ajv options](#ajv-options) `--remove-additional`, `--use-defaults` and `--coerce-types`).


  The changes are reported in JSON-patch format ([RFC6902](https://tools.ietf.org/html/rfc6902)).


  Possible values are `js` (default), `json` and `line` (see `--errors` option).

### Compile schemas

This command validates and compiles schema without validating any data.

It can be used to check that the schema is valid and to create a standalone module exporting validation function(s).

```sh

ajv compile -s schema

# compile to module file

ajv compile -s schema -o validate.js

## compile to stdout, to allow code formatting (js-beautify has to be installed separately)

ajv compile -s schema -o | js-beautify > validate.js

```

#### Parameters

##### `-s` - file name(s) of JSON-schema(s)

Multiple schemas can be passed both by using this parameter multiple times and with [glob patterns](https://github.com/isaacs/node-glob#glob-primer).

```sh

ajv compile -s "test/schema*.json"

```

##### `-o` - output file for compiled validation function module

If multiple schemas are compiled with this option the module will have multiple exports named as schema $id's or as file names, otherwise the module will export validation function as default export.

```sh

ajv compile -s "schema.json" -o "validate_schema.js"

```

`-o` without parameter should be used to output code to stdout to pass it to some code formatter.

This command also supports parameters `-r`, `-m` and `-c` as in [validate](#validate-data) command.

### Migrate schemas

This command validates and migrates schema from JSON Schema draft-04 to draft-07, draft-2019-09 or draft-2020-12 using [json-schema-migrate](https://github.com/ajv-validator/json-schema-migrate) package.

The [version of JSON Schema](#json-schema-version) is determined by `--spec` parameter (only `"draft7"`, `"draft2019"` or  `"draft2020"`).

```sh

ajv migrate -s schema

# compile to specific file name

ajv migrate -s schema -o migrated_schema.json

```

#### Parameters

##### `-s` - file name(s) of JSON-schema(s)

Multiple schemas can be passed both by using this parameter multiple times and with [glob patterns](https://github.com/isaacs/node-glob#glob-primer).

```sh

ajv migrate -s "test/schema*.json"

```

If parameter `-o` is not specified the migrated schema is written to the same file and the original file is preserved with `.bak` extension.

If migration doesn't change anything in the schema file no changes in files are made.

##### `-o` - output file for migrated schema

Only a single schema can be migrated with this option.

```sh

ajv compile -s "schema.json" -o migrated_schema.json

```

#### Options

- `--indent=`: indentation in migrated schema JSON file, 4 by default

- `--validate-schema=false`: skip schema validation

### Test validation result

This command asserts that the result of the validation is as expected.

```sh

ajv test -s test/schema.json -d test/valid_data.json --valid

ajv test -s test/schema.json -d test/invalid_data.json --invalid

```

If the option `--valid` (`--invalid`) is used for the `test` to pass (exit code 0) the data file(s) should be valid (invalid).

This command supports the same options and parameters as [validate](#validate-data) with the exception of `--changes`.

## Ajv options

You can pass the following [Ajv options](https://ajv.js.org/options.html):

| Option | Description |

| ------ | ----------- |

| Strict mode |

| `--strict=`| `true`/`false`/`log` - set all [strict mode](https://ajv.js.org/strict-mode.html) restrictions |

| `--strict-schema=`| log on (`log`) or ignore (`false`) [strict ](https://ajv.js.org/strict-mode.html#prohibit-ignored-keywords) restrictions (the default is to log) |

| `--strict-tuples=`| throw on (`true`) or ignore (`false`) [strict schema](https://ajv.js.org/strict-mode.html#prohibit-unconstrained-tuples) restrictions (the default is to throw) |

| `--strict-types=`| throw on (`true`) or ignore (`false`) [strict types](https://ajv.js.org/strict-mode.html#strict-types) restrictions (the default is to log) |

| `--strict-required=`| throw on (`true`) or log (`log`) [required properties](https://ajv.js.org/strict-mode.html#defined-required-properties) restrictions (the default is to ignore) |

| `--allow-matching-properties`| allow `properties` [matching patterns](https://ajv.js.org/strict-mode.html#overlap-between-properties-and-patternproperties-keywords) in `patternProperties` |

| `--allow-union-types`| allow [union types](https://ajv.js.org/strict-mode.html#union-types) |

| `--validate-formats=false`| disable format validation |

| Validation and reporting |

| `--data`| use [$data references](https://ajv.js.org/guide/combining-schemas.html#data-reference) |

| `--all-errors`| collect all validation errors |

| `--verbose` | include schema and data in errors |

| `--comment` | log schema `$comment`s |

| `--inline-refs=` | referenced schemas compilation mode (true/false/\) |

| Modify validated data |

| `--remove-additional` | remove additional properties (true/all/failing) |

| `--use-defaults` | replace missing properties/items with the values from default keyword |

| `--coerce-types` | change type of data to match type keyword |

| Advanced |

| `--multiple-of-precision` | precision of multipleOf, pass integer number |

| `--messages=false` | do not include text messages in errors |

| `--loop-required=` | max size of `required` to compile to expression (rather than to loop) |

| `--loop-enum=` | max size of `enum` to compile to expression (rather than to loop) |

| `--own-properties` | only validate own properties (not relevant for JSON, but can have effect for JavaScript objects) |

| Code generation |

| `--code-es5` | generate ES5 code |

| `--code-lines` | generate multi-line code |

| `--code-optimize=` | disable optimization (`false`) or number of optimization passes (1 pass by default) |

| `--code-formats=` | code to require formats object (only needed if you generate standalone code and do not use [ajv-formats](https://github.com/ajv-validator/ajv-formats)) |

Options can be passed using either dash-case or camelCase.

See [Ajv Options](https://ajv.js.org/options.html) for more information.

## Version History

See https://github.com/ajv-validator/ajv-cli/releases

## Licence

[MIT](./LICENSE)