search

chris48s / v8r

✔️ A command-line JSON and YAML validator that's on your wavelength
https://www.npmjs.com/package/v8r
MIT License
28 stars 6 forks source link
command-line json-schema validation

readme

v8r

build coverage version license node

v8r is a command-line JSON and YAML validator that uses Schema Store to detect a suitable schema for your input files based on the filename.

Getting Started

One-off:

npx v8r@latest <filename>

Local install:

npm install -g v8r
v8r <filename>

Usage Examples

Validating files

v8r can validate JSON or YAML files. You can pass filenames or glob patterns:

# single filename
$ v8r package.json

# multiple files
$ v8r file1.json file2.json

# glob patterns
$ v8r 'dir/*.yml' 'dir/*.yaml'

DigitalOcean's Glob Tool can be used to help construct glob patterns

Manually specifying a schema

By default, v8r queries Schema Store to detect a suitable schema based on the filename.

# if v8r can't auto-detect a schema for your file..
$ v8r feature.geojson
✖ Could not find a schema to validate feature.geojson

# ..you can specify one using the --schema flag
$ v8r feature.geojson --schema https://json.schemastore.org/geojson
ℹ Validating feature.geojson against schema from https://json.schemastore.org/geojson ...
✔ feature.geojson is valid

Using a custom catlog

Using the --schema flag will validate all files matched by the glob pattern against that schema. You can also define a custom schema catalog. v8r will search any custom catalogs before falling back to Schema Store.

$ cat > my-catalog.json <<EOF
{ "\$schema": "https://json.schemastore.org/schema-catalog.json",
  "version": 1,
  "schemas": [ { "name": "geojson",
                 "description": "geojson",
                 "url": "https://json.schemastore.org/geojson.json",
                 "fileMatch": ["*.geojson"] } ] }
EOF

$ v8r feature.geojson -c my-catalog.json
ℹ Found schema in my-catalog.json ...
ℹ Validating feature.geojson against schema from https://json.schemastore.org/geojson ...
✔ feature.geojson is valid

This can be used to specify different custom schemas for multiple file patterns.

Configuration

v8r uses CosmiConfig to search for a configuration. This means you can specify your configuration in any of the following places:

v8r only searches for a config file in the current working directory.

Example yaml config file:

# - One or more filenames or glob patterns describing local file or files to validate
# - overridden by passing one or more positional arguments
patterns: ['*json']

# - Level of verbose logging. 0 is standard, higher numbers are more verbose
# - overridden by passing --verbose / -v
# - default = 0
verbose: 2

# - Exit with code 0 even if an error was encountered. True means a non-zero exit
#   code is only issued if validation could be completed successfully and one or
#   more files were invalid
# - overridden by passing --ignore-errors
# - default = false
ignoreErrors: true

# - Remove cached HTTP responses older than cacheTtl seconds old.
#   Specifying 0 clears and disables cache completely
# - overridden by passing --cache-ttl
# - default = 600
cacheTtl: 86400

# - Output format for validation results
# - overridden by passing --format
# - default = text
format: "json"

# - A custom schema catalog.
#   This catalog will be searched ahead of any custom catalogs passed using
#   --catalogs or SchemaStore.org
#   The format of this is subtly different to the format of a catalog
#   passed via --catalogs (which matches the SchemaStore.org format)
customCatalog:
    schemas:
        - name: Custom Schema  # The name of the schema (required)
          description: Custom Schema  # A description of the schema (optional)

          # A Minimatch glob expression for matching up file names with a schema (required)
          fileMatch: ["*.geojson"]

          # A URL or local file path for the schema location (required)
          # Unlike the SchemaStore.org format, which has a `url` key,
          # custom catalogs defined in v8r config files have a `location` key
          # which can refer to either a URL or local file.
          # Relative paths are interpreted as relative to the config file location.
          location: foo/bar/geojson-schema.json

          # A custom parser to use for files matching fileMatch
          # instead of trying to infer the correct parser from the filename (optional)
          # This property is specific to custom catalogs defined in v8r config files
          parser: json5

The config file format is specified more formally in a JSON Schema:

Configuring a Proxy

It is possible to configure a proxy via global-agent using the GLOBAL_AGENT_HTTP_PROXY environment variable:

export GLOBAL_AGENT_HTTP_PROXY=http://myproxy:8888

Exit codes

Versioning

v8r follows semantic versioning. For this project, the "API" is defined as:

A "breaking change" also includes:

FAQ

❓ How does v8r decide what schema to validate against if I don't supply one?

💡 v8r queries the Schema Store catalog to try and find a suitable schema based on the name of the input file.

❓ My file is valid, but it doesn't validate against one of the suggested schemas.

💡 v8r is a fairly thin layer of glue between Schema Store (where the schemas come from) and ajv (the validation engine). It is likely that this kind of problem is either an issue with the schema or validation engine.

❓ What JSON schema versions are compatible?

💡 v8r works with JSON schema drafts:

❓ Will 100% of the schemas on schemastore.org work with this tool?

💡 No. There are some with known issues

❓ Can v8r validate against a local schema?

💡 Yes. The --schema flag can be either a path to a local file or a URL. You can also use a config file to include local schemas in a custom catalog.