The Complete Guide to Jsonc Validating: Everything You Need to Know

JSONC — JSON with Comments — is a practical extension of JSON that allows developers to annotate configuration files with single-line (//) and multi-line (/* */) comments, as well as trailing commas in objects and arrays. It is the native format of tsconfig.json, VS Code's settings.json, and many modern build tool configuration files. But JSONC introduces ambiguity: a file with a .jsonc extension is not valid JSON, and a file written to be JSONC may still contain structural errors that only appear when the file is parsed by the consuming application.

JSONC validation solves this problem by stripping comments and trailing commas, then feeding the result to a strict JSON parser. This guide explains what JSONC validation is, what the validator checks, how to read its output, and best practices for managing JSONC files in development and production workflows.

Connect on LinkedIn →

What Is JSONC Validation?

JSONC validation is the process of parsing a JSONC file — stripping its comments and trailing commas — and confirming that the resulting structure is valid JSON. A JSONC validator goes beyond a simple JSON parser by first applying JSONC-specific preprocessing rules, then validating the cleaned content, and finally reporting additional structural information such as nesting depth, node counts, duplicate keys, and encoding anomalies.

Browser-based JSONC validation reads the file using the Web File API and processes it entirely in JavaScript. Your configuration data — which may contain API endpoints, feature flags, connection strings, or other environment-specific values — never leaves your device. This makes browser-based validation safe to use with real configuration files from production systems.

Why Validate JSONC Files?

JSONC files fail in specific, predictable ways that are easy to overlook during manual editing. Common scenarios where validation catches real problems:

• Configuration file hand-off. When a JSONC configuration file is passed between developers, build systems, or deployment pipelines, a single malformed comment, an unclosed string, or a missing comma can cause the consuming application to fail at startup — often with a cryptic parser error rather than a clear description of the problem. Validating before committing prevents this class of failure.
• Comment-stripping edge cases. The naive approach to stripping JSONC comments — removing everything after // on a line — breaks string values that contain // as part of a URL or regular expression. A correct JSONC preprocessor must track string boundaries and only strip comments that appear outside of quoted strings. Validation confirms the preprocessing was applied correctly.
• Deep nesting in complex configs. TypeScript project configurations, monorepo build setups, and IDE configuration files can grow to dozens of nesting levels. Extremely deep structures cause stack overflows in some parsers. Validation reports the maximum nesting depth so you can flatten structures before they become a problem.
• Duplicate keys. JSON does not prohibit duplicate keys, but the behavior when they appear is undefined — most parsers use the last value, some use the first, and a few throw an error. A configuration file with duplicate keys is almost always a bug: a setting was added twice, a block was copy-pasted without removing the original, or a merge conflict was resolved incorrectly. Validation catches duplicates at all nesting levels.
• Encoding issues. Configuration files are occasionally saved with a UTF-8 byte order mark (BOM) — a three-byte sequence at the start of the file that is invisible in most editors but causes strict JSON parsers to fail immediately. Validation detects the BOM and null bytes that indicate binary content or wrong encoding.

Comment Stripping

JSONC supports two comment syntaxes inherited from JavaScript:

• Single-line comments: Everything from // to the end of the line is treated as a comment and ignored by the parser. Example: "port": 3000 // default development port
• Multi-line comments: Everything between /* and */ is a comment, spanning as many lines as needed. Example: a block comment above a configuration section explaining its purpose.

The validator's comment-stripping step must handle several edge cases correctly:

• URLs in strings. The string value "homepage": "https://example.com" contains // but it must not be stripped — it is inside a quoted string, not a comment. Correct stripping requires tracking whether the parser is currently inside a string literal.
• Escaped quotes. A string like "message": "say \"hello\"" contains escaped quotes. The comment stripper must correctly handle escape sequences so it does not accidentally treat the character after the escaped quote as outside the string.
• Nested comment syntax in strings. A string value that contains /* or */ as part of a regular expression or code snippet must not be treated as the start or end of a multi-line comment.

After stripping comments, the validator reports the total number of comment tokens removed. This count appears in the file statistics panel and is useful for confirming the stripping step ran at all — a count of zero on a file you know contains comments indicates a problem.

Trailing Commas

Standard JSON forbids trailing commas — a comma after the last element in an array or the last property in an object. JSONC permits them, making it easier to add, remove, and reorder items without hunting for the comma that needs to be added or removed each time:

{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,    // trailing comma — valid JSONC, invalid JSON
  }
}

The validator strips trailing commas before passing the content to the JSON parser. Like comment stripping, trailing comma removal must be aware of string boundaries — a string value that ends with a comma followed by a closing brace should not have that comma removed.

If a file has no trailing commas, the validator still processes it correctly — trailing comma removal is a no-op in that case, and the file is valid as both JSONC and standard JSON.

JSON Structure Validation

After preprocessing, the cleaned content is passed to the native browser JSON parser — the same parser used by JSON.parse() in JavaScript. This is the strictest and most accurate JSON validator available in a browser environment, because it is the actual production parser used by the JavaScript engine.

If the cleaned content is not valid JSON, the parser throws an error with a message and position. Common structural errors the validator surfaces:

• Unexpected token. A character appeared where the parser did not expect it — often a missing colon between a key and value, an extra comma that was not a trailing comma (e.g., a double comma), or a syntax error in a nested object.
• Unexpected end of JSON input. The file ends before the JSON structure is complete — a common result of an unclosed object, array, or string. Often caused by a missing closing brace or bracket at the end of a large configuration file.
• Invalid string. A string contains a control character (such as a newline or tab inserted literally rather than as \n or \t), or the string is not properly terminated before the end of the line.

The validator displays the raw error message from the JSON parser, which includes the character position where the error was detected. This position refers to the cleaned content after comment and trailing comma removal, not the original file — but the validator also reports the original line count to help you locate the error in context.

Encoding Issues

JSON files must be encoded in UTF-8 without a byte order mark (BOM). The BOM is a three-byte sequence (0xEF 0xBB 0xBF) that some text editors — particularly older versions of Microsoft Notepad and certain Windows tools — prepend to UTF-8 files to identify the encoding. Strict JSON parsers treat the BOM as unexpected content and fail immediately.

The validator checks the first bytes of the file for the UTF-8 BOM and reports it as a warning if found. Most JSONC consumers will reject a BOM-prefixed file, so this warning should be resolved by re-saving the file without the BOM.

The validator also checks for null bytes in the file content. Null bytes indicate either binary content mistakenly given a .jsonc extension, or a file that was saved in a wide-character encoding such as UTF-16 or UTF-32 rather than UTF-8. Either situation requires correcting the file before it can be used as a JSONC configuration.

Depth Analysis

The validator measures the maximum nesting depth of the JSON structure — the deepest level of nested objects and arrays. A top-level object containing a key whose value is an array of objects each containing another object would have a depth of 3.

Most JSON parsers handle arbitrary nesting depth, but some environments impose stack depth limits that can cause a parser to crash or throw a range error when parsing deeply nested structures. JavaScript's V8 engine, for example, has a recursion limit that can be exceeded by pathologically nested JSON.

In practice, most configuration files have depths of 3–8. A configuration file with a depth above 15 is unusual and worth reviewing — deep nesting often indicates that the structure could be flattened or reorganized for clarity. The validator flags extremely deep structures (above a configurable threshold) as warnings, not errors, since deep nesting is not technically invalid JSON.

Duplicate Keys

The JSONC and JSON specifications do not prohibit duplicate keys within an object, but the behavior when they appear is implementation-defined. The vast majority of parsers silently use the last value for a duplicated key, discarding all earlier occurrences. A few parsers use the first value. Some parsers throw an error. In all cases, a configuration file with duplicate keys is almost certainly a bug.

Common sources of duplicate keys in real configuration files:

• A setting was added in two different places during development, perhaps by different team members working in the same file.
• A configuration block was copy-pasted from another file without removing the original block.
• A merge conflict was resolved by accepting both sides of the conflict without noticing the keys overlap.
• An automated tool generated or modified the file and produced duplicate output.

The validator checks for duplicate keys at every nesting level — not just the top level. A duplicate key buried inside a nested object is just as likely to cause a silent bug as one at the top level, but is much harder to spot through manual inspection of a large file.

File Statistics and Preview

For valid JSONC files, the validator reports a set of structural statistics in addition to the pass/fail result:

• Root type. Whether the top-level value is an object ({}), an array ([]), a string, a number, a boolean, or null. Most configuration files have an object root — an array root in a configuration file is unusual and may indicate the file was structured incorrectly.
• Total nodes. The count of all JSON values in the structure, including nested objects, arrays, strings, numbers, booleans, and nulls. A high node count in a configuration file may indicate unnecessary complexity.
• Max depth. The maximum nesting level, as described in the depth analysis section above.
• Top-level key count. The number of keys directly in the root object. For configuration files, this gives an immediate sense of the file's scope — a file with 50 top-level keys may be doing too much in one place.
• Comment count. The number of comment tokens found and stripped. Useful for confirming the preprocessing step ran correctly.
• Line count. The total number of lines in the original file, including commented lines.
• File size. The size of the file in bytes or kilobytes.

The structure preview panel renders the top-level keys and their value types (object, array, string, number, boolean, null) in a table. This gives you an immediate visual overview of the file's shape without having to read through the full content — useful for large configuration files where you want to confirm the top-level structure is what you expect before diving into nested sections.

Best Practices

For developers working with JSONC configuration files — whether in TypeScript projects, VS Code workspaces, build tool configs, or custom tooling — these practices reduce the risk of configuration errors reaching production:

• Validate before committing. Add JSONC validation as a pre-commit hook or CI check. A configuration file with a syntax error that reaches the main branch can break builds for everyone on the team. Catching it at commit time costs seconds; catching it after a failed deployment costs much more.
• Use the correct file extension. JSONC files should use the .jsonc extension when they contain JSONC-specific syntax (comments or trailing commas). Using .json for a file with comments is technically incorrect and will cause failures if that file is passed to a strict JSON parser. Conversely, a .jsonc file that contains no JSONC-specific syntax is valid as both JSONC and JSON — the extension does not break anything.
• Validate when onboarding new tools. When a new build tool, linter, or framework adds a configuration file to your project, validate it immediately. Auto-generated configuration files are usually correct, but tools occasionally generate files with encoding issues or structural quirks that are worth catching before the file is customized.
• Check depth after major restructuring. If you reorganize a large configuration file — merging multiple files into one, splitting a flat structure into nested sections, or adding new feature configuration blocks — validate afterward and check the reported depth. A restructuring that accidentally creates deep nesting is easier to fix immediately than after the file has been committed and further modified.
• Resolve duplicate key warnings immediately. Unlike most warnings, duplicate key warnings should be treated as errors. There is no legitimate use case for intentional duplicate keys in a configuration file. When the validator flags a duplicate, find both occurrences, determine which value is correct, and remove the other.
• Re-validate after merging. Merge conflicts in JSON and JSONC files are notoriously difficult to resolve correctly — the conflict markers (<<<<<<<, =======, >>>>>>>) are not valid JSON, and resolving the conflict often leaves structural errors or duplicate keys. Always validate a JSONC file after resolving a merge conflict before committing the result.
• Do not rely on your editor's syntax highlighting. Most editors highlight JSONC syntax but do not perform full validation — they may show no errors for a file that will fail to parse. The visual feedback from syntax highlighting is useful for reading but is not a substitute for running the validator.

Common Use Cases

TypeScript project configuration. The tsconfig.json file is actually a JSONC file — the TypeScript compiler parses it with comment and trailing comma support. Developers frequently add comments to document non-obvious compiler options (strict, moduleResolution, target) and to keep a record of options that were considered and rejected. Validating tsconfig.json files before committing ensures the TypeScript compiler will be able to parse them correctly.

VS Code configuration. VS Code's settings.json, launch.json, tasks.json, and extension configuration files are all JSONC. Teams that store workspace configuration in version control validate these files to catch errors before they prevent colleagues from opening the workspace.

ESLint and Prettier configuration. ESLint supports JSONC configuration files (.eslintrc.jsonc), and Prettier can be configured via a .prettierrc that accepts JSONC syntax. These files are often modified by multiple developers and benefit from validation in CI.

Build tool configuration. Bundlers such as webpack, Rollup, and esbuild can be configured via JSON or JSONC files. Complex build configurations — with multiple entry points, output formats, plugin configurations, and environment-specific overrides — are easier to maintain with comments and trailing commas, making JSONC the natural choice.

API mock and fixture files. Development teams that use static JSON fixture files for API mocking sometimes convert them to JSONC to add inline annotations explaining what each fixture represents, what edge case it tests, and what data it was derived from. Validating these files ensures the annotations haven't introduced syntax errors that would break the mock server.

Configuration management in monorepos. Monorepos with many packages often have root-level JSONC configurations (for TypeScript, ESLint, Prettier, or custom tooling) that govern all packages. A syntax error in a root-level configuration file can break every package in the repository simultaneously. Validation before commit is especially important for these files.