1 | # ajv-cli
|
2 |
|
3 | Command line interface for [ajv](https://github.com/epoberezkin/ajv), one of the [fastest json schema validators](https://github.com/ebdrup/json-schema-benchmark).
|
4 | Supports [JSON](http://json.org/), [JSON5](http://json5.org/), and [YAML](http://yaml.org/).
|
5 |
|
6 | [](https://github.com/ajv-validator/ajv-cli/actions?query=workflow%3Abuild)
|
7 | [](https://www.npmjs.com/package/ajv-cli)
|
8 | [](https://coveralls.io/github/ajv-validator/ajv-cli?branch=master)
|
9 | [](https://gitter.im/ajv-validator/ajv)
|
10 |
|
11 | ## Contents
|
12 |
|
13 | - [Installation](#installation)
|
14 | - [JSON schema version](#json-schema-version)
|
15 | - Commands
|
16 | - [Help](#help-command)
|
17 | - [Validate data](#validate-data)
|
18 | - [Compile schemas](#compile-schemas)
|
19 | - [Migrate schemas](#migrate-schemas)
|
20 | - [Test validation result](#test-validation-result)
|
21 | - [Ajv options](#ajv-options)
|
22 | - [Version History, License](#version_history)
|
23 |
|
24 | ## Installation
|
25 |
|
26 | ```sh
|
27 | npm install -g ajv-cli
|
28 | ```
|
29 |
|
30 | ## JSON schema language and version
|
31 |
|
32 | Parameter `--spec` can be used with all commands (other than help) to choose JSON schema language:
|
33 |
|
34 | - `--spec=draft7` (default) - support JSON Schema draft-07 (uses `import Ajv from "ajv"`)
|
35 | - `--spec=draft2019` - support JSON Schema draft-2019-09 (uses `import Ajv from "ajv/dist/2019"`)
|
36 | - `--spec=draft2020` - support JSON Schema draft-2020-12 (uses `import Ajv from "ajv/dist/2020"`)
|
37 | - `--spec=jtd` - support [JSON Type Definition](https://ajv.js.org/json-type-definition.html) (uses `import Ajv from "ajv/dist/jtd"`)
|
38 |
|
39 | ## Commands
|
40 |
|
41 | ### Help command
|
42 |
|
43 | ```sh
|
44 | ajv help
|
45 | ajv help validate
|
46 | ajv help compile
|
47 | ajv help migrate
|
48 | ajv help test
|
49 | ```
|
50 |
|
51 | ### Validate data
|
52 |
|
53 | This command validates data files against JSON-schema
|
54 |
|
55 | ```sh
|
56 | ajv validate -s test/schema.json -d test/valid_data.json
|
57 | ajv -s test/schema.json -d test/valid_data.json
|
58 | ```
|
59 |
|
60 | You can omit `validate` command name and `.json` from the [input file names](https://nodejs.org/api/modules.html#modules_file_modules).
|
61 |
|
62 | #### Parameters
|
63 |
|
64 | ##### `-s` - file name of JSON-schema
|
65 |
|
66 | Only one schema can be passed in this parameter
|
67 |
|
68 | ##### `-d` - JSON data
|
69 |
|
70 | Multiple data files can be passed, as in `-r` parameter:
|
71 |
|
72 | ```sh
|
73 | ajv -s test/schema.json -d "test/valid*.json"
|
74 | ```
|
75 |
|
76 | If some file is invalid exit code will be 1.
|
77 |
|
78 | ##### `-r` - referenced schemas
|
79 |
|
80 | The schema in `-s` parameter can reference any of these schemas with `$ref` keyword.
|
81 |
|
82 | 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.
|
83 |
|
84 | ##### `-m` - meta-schemas
|
85 |
|
86 | 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).
|
87 |
|
88 | Multiple meta-schemas can be passed, as in `-r` parameter.
|
89 |
|
90 | ##### `-c` - custom keywords/formats definitions
|
91 |
|
92 | 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.
|
93 | These modules can be written in TypeScript if you have `ts-node` installed.
|
94 |
|
95 | 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.
|
96 |
|
97 | #### Options
|
98 |
|
99 | - `--errors=`: error reporting format. Possible values:
|
100 |
|
101 | - `js` (default): JavaScript object
|
102 | - `json`: JSON with indentation and line-breaks
|
103 | - `line`: JSON without indentation/line-breaks (for easy parsing)
|
104 | - `text`: human readable error messages with data paths
|
105 |
|
106 | - `--changes=`: detect changes in data after validation.<br>
|
107 | Data can be modified with [Ajv options](#ajv-options) `--remove-additional`, `--use-defaults` and `--coerce-types`).<br>
|
108 | The changes are reported in JSON-patch format ([RFC6902](https://tools.ietf.org/html/rfc6902)).<br>
|
109 | Possible values are `js` (default), `json` and `line` (see `--errors` option).
|
110 |
|
111 | ### Compile schemas
|
112 |
|
113 | This command validates and compiles schema without validating any data.
|
114 |
|
115 | It can be used to check that the schema is valid and to create a standalone module exporting validation function(s).
|
116 |
|
117 | ```sh
|
118 | ajv compile -s schema
|
119 |
|
120 | # compile to module file
|
121 | ajv compile -s schema -o validate.js
|
122 |
|
123 | ## compile to stdout, to allow code formatting (js-beautify has to be installed separately)
|
124 | ajv compile -s schema -o | js-beautify > validate.js
|
125 | ```
|
126 |
|
127 | #### Parameters
|
128 |
|
129 | ##### `-s` - file name(s) of JSON-schema(s)
|
130 |
|
131 | Multiple schemas can be passed both by using this parameter multiple times and with [glob patterns](https://github.com/isaacs/node-glob#glob-primer).
|
132 |
|
133 | ```sh
|
134 | ajv compile -s "test/schema*.json"
|
135 | ```
|
136 |
|
137 | ##### `-o` - output file for compiled validation function module
|
138 |
|
139 | 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.
|
140 |
|
141 | ```sh
|
142 | ajv compile -s "schema.json" -o "validate_schema.js"
|
143 | ```
|
144 |
|
145 | `-o` without parameter should be used to output code to stdout to pass it to some code formatter.
|
146 |
|
147 | This command also supports parameters `-r`, `-m` and `-c` as in [validate](#validate-data) command.
|
148 |
|
149 | ### Migrate schemas
|
150 |
|
151 | 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.
|
152 |
|
153 | The [version of JSON Schema](#json-schema-version) is determined by `--spec` parameter (only `"draft7"`, `"draft2019"` or `"draft2020"`).
|
154 |
|
155 | ```sh
|
156 | ajv migrate -s schema
|
157 |
|
158 | # compile to specific file name
|
159 | ajv migrate -s schema -o migrated_schema.json
|
160 | ```
|
161 |
|
162 | #### Parameters
|
163 |
|
164 | ##### `-s` - file name(s) of JSON-schema(s)
|
165 |
|
166 | Multiple schemas can be passed both by using this parameter multiple times and with [glob patterns](https://github.com/isaacs/node-glob#glob-primer).
|
167 |
|
168 | ```sh
|
169 | ajv migrate -s "test/schema*.json"
|
170 | ```
|
171 |
|
172 | If parameter `-o` is not specified the migrated schema is written to the same file and the original file is preserved with `.bak` extension.
|
173 |
|
174 | If migration doesn't change anything in the schema file no changes in files are made.
|
175 |
|
176 | ##### `-o` - output file for migrated schema
|
177 |
|
178 | Only a single schema can be migrated with this option.
|
179 |
|
180 | ```sh
|
181 | ajv compile -s "schema.json" -o migrated_schema.json
|
182 | ```
|
183 |
|
184 | #### Options
|
185 |
|
186 | - `--indent=`: indentation in migrated schema JSON file, 4 by default
|
187 | - `--validate-schema=false`: skip schema validation
|
188 |
|
189 | ### Test validation result
|
190 |
|
191 | This command asserts that the result of the validation is as expected.
|
192 |
|
193 | ```sh
|
194 | ajv test -s test/schema.json -d test/valid_data.json --valid
|
195 | ajv test -s test/schema.json -d test/invalid_data.json --invalid
|
196 | ```
|
197 |
|
198 | If the option `--valid` (`--invalid`) is used for the `test` to pass (exit code 0) the data file(s) should be valid (invalid).
|
199 |
|
200 | This command supports the same options and parameters as [validate](#validate-data) with the exception of `--changes`.
|
201 |
|
202 | ## Ajv options
|
203 |
|
204 | You can pass the following [Ajv options](https://ajv.js.org/options.html):
|
205 |
|
206 | | Option | Description |
|
207 | | ------ | ----------- |
|
208 | | Strict mode |
|
209 | | `--strict=`| `true`/`false`/`log` - set all [strict mode](https://ajv.js.org/strict-mode.html) restrictions |
|
210 | | `--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) |
|
211 | | `--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) |
|
212 | | `--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) |
|
213 | | `--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) |
|
214 | | `--allow-matching-properties`| allow `properties` [matching patterns](https://ajv.js.org/strict-mode.html#overlap-between-properties-and-patternproperties-keywords) in `patternProperties` |
|
215 | | `--allow-union-types`| allow [union types](https://ajv.js.org/strict-mode.html#union-types) |
|
216 | | `--validate-formats=false`| disable format validation |
|
217 | | Validation and reporting |
|
218 | | `--data`| use [$data references](https://ajv.js.org/guide/combining-schemas.html#data-reference) |
|
219 | | `--all-errors`| collect all validation errors |
|
220 | | `--verbose` | include schema and data in errors |
|
221 | | `--comment` | log schema `$comment`s |
|
222 | | `--inline-refs=` | referenced schemas compilation mode (true/false/\<number\>) |
|
223 | | Modify validated data |
|
224 | | `--remove-additional` | remove additional properties (true/all/failing) |
|
225 | | `--use-defaults` | replace missing properties/items with the values from default keyword |
|
226 | | `--coerce-types` | change type of data to match type keyword |
|
227 | | Advanced |
|
228 | | `--multiple-of-precision` | precision of multipleOf, pass integer number |
|
229 | | `--messages=false` | do not include text messages in errors |
|
230 | | `--loop-required=` | max size of `required` to compile to expression (rather than to loop) |
|
231 | | `--loop-enum=` | max size of `enum` to compile to expression (rather than to loop) |
|
232 | | `--own-properties` | only validate own properties (not relevant for JSON, but can have effect for JavaScript objects) |
|
233 | | Code generation |
|
234 | | `--code-es5` | generate ES5 code |
|
235 | | `--code-lines` | generate multi-line code |
|
236 | | `--code-optimize=` | disable optimization (`false`) or number of optimization passes (1 pass by default) |
|
237 | | `--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)) |
|
238 |
|
239 | Options can be passed using either dash-case or camelCase.
|
240 |
|
241 | See [Ajv Options](https://ajv.js.org/options.html) for more information.
|
242 |
|
243 | ## Version History
|
244 |
|
245 | See https://github.com/ajv-validator/ajv-cli/releases
|
246 |
|
247 | ## Licence
|
248 |
|
249 | [MIT](./LICENSE)
|