eslint-plugin-json

eslint-plugin-json is an ESLint plugin that enables linting of JSON files within ESLint workflows. It leverages the VSCode JSON language service to parse and validate JSON syntax, offering comprehensive error detection including syntax errors, trailing commas, duplicate keys, and structural issues.

Package Information

• Package Name: eslint-plugin-json
• Package Type: npm
• Language: JavaScript
• Installation: npm install --save-dev eslint-plugin-json

Core Imports

For ESM and modern environments:

import plugin from 'eslint-plugin-json';

For CommonJS:

const plugin = require('eslint-plugin-json');

Basic Usage

Flat Config Format (ESLint v9+)

import json from 'eslint-plugin-json';

export default [
  {
    files: ["**/*.json"],
    ...json.configs["recommended"]
  }
];

Legacy Config Format

{
  "extends": ["plugin:json/recommended-legacy"]
}

Running ESLint on JSON files

eslint . --ext .json,.js
eslint example.json

Architecture

eslint-plugin-json is structured around several key components:

• Rules Engine: Individual rules for each type of JSON validation error (syntax, structure, comments)
• JSON Processor: Preprocesses JSON files using VSCode JSON language service for parsing and error detection
• Configuration Presets: Predefined configurations for common usage patterns
• Error Mapping: Maps VSCode JSON service errors to ESLint-compatible messages
• Functional Programming: Built using lodash/fp for functional data transformations and processing

The plugin follows ESLint's plugin architecture, providing rules, processors, and configurations that integrate seamlessly into existing ESLint workflows.

Capabilities

Rules and Configuration

Complete collection of validation rules for JSON files, including syntax errors, structural issues, and comment handling. Supports both global rules and individual error-specific rules.

// Global rules that apply all validations
const rules = {
  'json/*': 'error',        // All validation rules
  'json/json': 'error'      // Alias for all validation rules
};

// Individual validation rules
const specificRules = {
  'json/trailing-comma': 'error',
  'json/duplicate-key': 'error',
  'json/comment-not-permitted': 'error'
};

Rules and Configuration

JSON File Processing

File processor that handles JSON parsing, error detection, and message formatting for ESLint integration.

const processors = {
  '.json': jsonProcessor,  // Legacy processor
  'json': jsonProcessor    // Modern processor
};

interface JsonProcessor {
  preprocess(text: string, fileName: string): string[];
  postprocess(messages: ESLintMessage[][], fileName: string): ESLintMessage[];
}

JSON Processing

Main Plugin Export

interface ESLintPluginJson {
  meta: {
    name: "eslint-plugin-json";
    version: "3.1.0"; // Note: version is hardcoded as "3.1.0" in source code
  };
  rules: Record<string, ESLintRule>;
  configs: Record<string, ESLintConfig>;
  processors: Record<string, ESLintProcessor>;
}

The plugin exports an object conforming to ESLint's plugin interface, containing metadata, rules, predefined configurations, and file processors.

Types

interface ESLintRule {
  meta: {
    schema: JSONSchema[];
  };
  create(context: ESLintContext): ESLintRuleVisitor;
}

interface ESLintConfig {
  plugins?: string[] | Record<string, any>;
  rules?: Record<string, any>;
  files?: string[];
  processor?: string;
}

interface ESLintMessage {
  ruleId: string;
  severity: number;
  message: string;
  line: number;
  column: number;
  endLine: number;
  endColumn: number;
  source?: string;
}

interface RuleOptions {
  allowComments?: boolean;
}