npm package: @prantlf/grunt-jsonlint
Description: Validate JSON files from grunt.
Author: Ferdinand Prantl
Latest version: 3.0.1

# @prantlf/grunt-jsonlint

[![Latest version](https://img.shields.io/npm/v/@prantlf/grunt-jsonlint)
 ![Dependency status](https://img.shields.io/librariesio/release/npm/@prantlf/grunt-jsonlint)
](https://www.npmjs.com/package/@prantlf/grunt-jsonlint)
[![Code coverage](https://codecov.io/gh/prantlf/grunt-jsonlint/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/grunt-jsonlint)

Validates [JSON]/[JSON5] files from [`Grunt`] using [`JSONLint`].

This is a fork of the original package with the following enhancements:

* Supports [JSON Schema] drafts 04, 06, 07, 2019-09 and 2020-12.
* Supports [JSON Type Definition].
* Optionally recognizes JavaScript-style comments and single quoted strings.
* Optionally ignores trailing commas and reports duplicate object keys as an error.
* Can sort object keys alphabetically.
* Offers pretty-printing including comment-stripping and object keys without quotes (JSON5).
* Prefers using the 10x faster native JSON parser, if possible.
* Formats column number of error occurrences too, does not report error location twice.
* Prints the same rich error information for schema validation.
* Depends on up-to-date npm modules with no installation warnings.

Requires Grunt 1.0+ and node 14.0+.

## Installation

    npm i @prantlf/grunt-jsonlint -D

## Configuration

Add the following (multi-)task to your Gruntfile:

    jsonlint: {
      sample: {
        src: [ 'some/valid.json' ],
        options: {
          formatter: 'prose'
        }
      }
    }

Add the following to load the task into your Gruntfile:

    grunt.loadNpmTasks('@prantlf/grunt-jsonlint');

An error will be thrown if the JSON file contains syntax errors.  To prefer an error format compatible with Visual Studio, change the formatter to 'msbuild'.

## Customizing

There is a couple of options, which can support non-standard JSON syntax, usually used in configuration files for convenience:

    jsonlint: {
      all: {
        src: [ 'some/settings.json' ],
        options: {
          ignoreComments: false,
          ignoreTrailingCommas: false,
          allowSingleQuotedStrings: false,
          allowDuplicateObjectKeys: true,
          mode: 'json'
        }
      }
    }

* `ignoreComments`, when `true` JavaScript-style single-line and multiple-line comments will be recognised and ignored
* `ignoreTrailingCommas`, when `true` trailing commas in objects and arrays will be ignored
* `allowSingleQuotedStrings`, when `true` single quotes will be accepted as alternative delimiters for strings
* `allowDuplicateObjectKeys`, when `false` duplicate keys in objects will be reported as an error
* `mode`, when set to "cjson" or "json5", enables some other flags automatically

| Mode    | Enabled Options   |
| ------- | ----------------- |
| "json"  | (none)            |
| "cjson" | `ignoreComments`  |
| "json5" | `ignoreComments`, `ignoreTrailingCommas`, `allowSingleQuotedStrings` and other JSON5 specifics |

## Formatting

Add the following (multi-)task to your `Gruntfile`:

    jsonlint: {
      all: {
        src: [ 'some/valid.json' ],
        options: {
          format: true,
          prettyPrint: false,
          indent: 2,
          sortKeys: false,
          pruneComments: false,
          stripObjectKeys: false,
          enforceDoubleQuotes: false,
          enforceSingleQuotes: false,
          trimTrailingCommas: false
        }
      }
    }

Add [parsing options](#customizing) to these formatting options as you need.

* `format`, when `true` `JSON.stringify` will be used to format the JavaScript (if it is valid)
* `prettyPrint`, when `true` `JSON.stringify` will be used to format the JavaScript (if it is valid)
* `indent`, the value passed to `JSON.stringify`, it can be the number of spaces, or string like "\t"
* `sortKeys`, when `true` keys of objects in the output JSON will be sorted alphabetically (`format` has to be set to `true`)
* `pruneComments`, when `true` comments will be omitted from the prettified output (CJSON feature, `prettyPrint` has to be set to `true`)
* `stripObjectKeys`, when `true` quotes surrounding object keys will be stripped if the key is a JavaScript identifier name (JSON5 feature, `prettyPrint` has to be set to `true`)
* `enforceDoubleQuotes`, when `true` string literals will be consistently surrounded by double quotes (JSON5 feature, `prettyPrint` has to be set to `true`)
* `enforceSingleQuotes`, when `true` string literals will be consistently surrounded by single quotes (JSON5 feature, `prettyPrint` has to be set to `true`)
* `trimTrailingCommas`, when `true` trailing commas after all array items and object entries will be omitted (JSON5 feature, `prettyPrint` has to be set to `true`)

## Schema Validation

You can validate JSON files using [JSON Schema] drafts 04, 06, 07, 2019-09 or 2020-12, or using [JSON Type Definition]:

    jsonlint: {
      all: {
        src: [ 'some/manifest.json' ],
        options: {
          schema: {
            src: 'some/manifest-schema.json',
            environment: 'draft-04'
          }
        }
      }
    }

* `schema`, when set the source file will be validated using ae JSON Schema in addition to the syntax checks
* `src`, when filled with one or more file paths, the files will be used as a source of the JSON Schema
* `environment`, can specify the version of the JSON Schema draft to use for validation: "draft-04", "draft-06", "draft-07", "draft-2019-09", "draft-2020-12" or "jtd" (if not set, the supported schema draft versions will be 06 and 07)

## Reporting

There are a few options available for reporting errors:

### Error Message Format

The standard error message format (`prose`) is optimized for human reading and looks like:

    >> File "test/invalid.json" failed JSON validation at line 10, column 9.

This is customizable to conform to the Visual Studio style by specifying the `formatter` option as `msbuild`, like:

    jsonlint: {

      visualStudioExample: {
        src: [ 'test/invalid.json' ],
        options: {
          formatter: 'msbuild'
        }
      }

    }

The output will look like:

    >> test/invalid.json(10,9): error: failed JSON validation

### Error Reporting

By default, the raw error from the underlying `jsonlint` library comes through to the grunt output.  It looks like:

    ...        "2"        "3",      ],      ...
    ----------------------^
    Unexpected string

To customize this, change the `reporter` option to `jshint` (the format is inspired by how `jshint` formats their output, hence the name):

    jsonlint: {

      jshintStyle: {
        src: [ 'test/invalid.json' ],
        options: {
          reporter: 'jshint'
        }
      }

    }

The output will look like:

    10 | ..."        "3",    ...
                     ^ Unexpected string

The default reporter is called `exception` since it simply relays the raw exception message.

## Running Tests

Unit tests are provided for automated regression testing. The easiest way
to run them is with:

    npm test

Alternatively, if you have `grunt-cli` installed, you could use grunt directly:

    grunt test

Which does the same thing.

## License

Copyright (C) 2013-2023 Brandon Ramirez, Ferdinand Prantl

Licensed under the [MIT License].

[MIT License]: http://en.wikipedia.org/wiki/MIT_License
[`Grunt`]: https://gruntjs.com/
[`JSONLint`]: https://prantlf.github.io/jsonlint/
[JSON]: https://tools.ietf.org/html/rfc8259
[JSON5]: https://spec.json5.org
[JSON Schema]: https://json-schema.org
[JSON Type Definition]: https://jsontypedef.com/