How to Use the Jsonc Validator: Step-by-Step Tutorial

The Jsonc Validator runs entirely in your browser — your configuration file is never sent to any server, no account is required, and nothing leaves your machine. This tutorial walks through every step of using the tool: loading a JSONC file, reading each results panel, understanding what the validator checks, and diagnosing the issues it reports.

Connect on LinkedIn →

Step 1 — Open the Tool

Navigate to /developer-tools/jsonc-validator/. The tool loads entirely in the browser — after the initial page load, validating a file makes zero outbound network requests. You can confirm this in your browser's DevTools Network panel: drop a file and watch the network tab remain idle.

The tool is accessible from the Developer Tools hub, the command palette (press Ctrl+K or ⌘K and type "JSONC Validator"), or directly via the URL above.

Step 2 — Load Your JSONC File

There are two ways to load a file. The easiest is drag and drop: drag your .jsonc or .json file from your file manager and drop it anywhere on the drop zone. A full-page overlay appears when you drag a file over the browser window, making it easy to drop the file accurately. The drop zone accepts both .jsonc and .json files up to 50 MB.

Alternatively, click the "browse" link inside the drop zone to open a file picker dialog. Select your file and the tool loads it immediately.

If you drop a file with an unsupported extension, the tool displays a type error message identifying the extension and explaining why it was rejected. Common configuration file extensions that are not supported: .yaml, .toml, .env. Only .jsonc and .json files are accepted.

Once a file is loaded, its name appears in a bar above the buttons. To clear the file and load a different one, click the ✕ button in the filename bar.

Step 3 — Click Validate

After loading your file, click the Validate JSONC button. Validation runs in JavaScript in your browser tab — for most configuration files (under a few megabytes), results appear instantly. The button also clears any previous results from a prior validation run, so you can validate multiple files in sequence without reloading the page.

Clicking Clear removes the loaded file and resets the tool to its initial state.

Step 4 — Read the Status Bar

After clicking Validate, a status bar appears below the buttons. It is colour-coded to give you an immediate answer:

• Green — "Valid JSONC — no issues found." The file passed all checks: comment stripping succeeded, trailing commas were removed, the resulting JSON is structurally valid, no encoding issues were detected, no duplicate keys were found, and the nesting depth is within normal limits.
• Yellow — "Valid JSONC — N warning(s). See details below." The file is structurally valid but the validator detected one or more conditions worth noting. See the Warnings panel for details.
• Red — error message. The file failed a required check. The status bar shows a concise description of the first fatal error. The Error panel below provides more detail.

Step 5 — Review the Error Panel

If validation fails, a red Error panel appears below the status bar. It contains the full error message from the JSON parser or from the preprocessing step. Common error messages and what they mean:

"Unexpected token X in JSON at position N"

This is the native JSON parser's error for a structural problem in the cleaned content (after comments and trailing commas have been stripped). The token X is the character the parser found, and position N is the byte offset in the cleaned string where the parser stopped. Common causes:

• A missing colon between a key and its value: "key" "value" instead of "key": "value"
• A missing comma between two properties or array elements
• A double comma — two commas in a row — that the trailing comma stripper treated as a single trailing comma but leaves an extra comma in the output
• An unquoted key: {key: "value"} — JSON requires all object keys to be quoted strings

To locate the error, divide position N by the approximate line length to estimate the line number, then look in that area of your file for the structural issue.

"Unexpected end of JSON input"

The file ends before the JSON structure is complete. The most common cause is an unclosed object or array — a missing closing } or ] at the end of the file. In large configuration files, this is easy to miss. Count your opening and closing braces and brackets at the top level to find the imbalance.

"UTF-8 BOM detected"

The file begins with a UTF-8 byte order mark. While this is flagged as an error because it will cause strict JSON parsers to fail, some consumers may tolerate it. Re-save the file without the BOM using your editor's encoding settings (in VS Code: click the encoding indicator in the status bar and choose "Save with Encoding" → UTF-8 without BOM).

"Null bytes detected — binary content or wrong encoding"

The file contains null bytes, which are not valid in a text file. This usually means the file is binary content mistakenly given a .jsonc extension, or it was saved in UTF-16 or UTF-32 encoding rather than UTF-8. Open the file in a hex editor to confirm the encoding, then re-save as UTF-8.

Step 6 — Review the Warnings Panel

If warnings were detected, a yellow Warnings panel lists each one. Warnings do not prevent the file from being used — the JSONC structure is valid — but they flag conditions that may cause problems in specific contexts:

"Duplicate key 'X' in object at path Y"

A key appears more than once in the same object. The path Y identifies which object contains the duplicate — for a top-level duplicate it may be root, for a nested duplicate it shows the key path like compilerOptions. Find both occurrences of the key in your file, determine which value is correct, and remove the other. Do not leave this warning unresolved — duplicate keys produce silent, hard-to-diagnose bugs.

"Max nesting depth N exceeds recommended limit"

The structure is nested N levels deep, which is above the threshold the validator considers unusual (typically 10 or more). Review the deeply nested section and consider whether the structure can be flattened. If the depth is intentional and your JSONC consumer handles it correctly, you can ignore this warning — it is informational.

"No content after comment stripping"

After removing comments, the file is empty or contains only whitespace. This means the file consists entirely of comments with no actual JSON content. This is unusual for a configuration file and likely indicates the wrong file was loaded, or the file is a template stub that hasn't been filled in yet.

Step 7 — Read the Valid JSONC Panel

When a file passes validation (green or yellow status), a green "Valid JSONC" panel shows the file statistics extracted from the structure:

• Root Type. Object, Array, String, Number, Boolean, or Null. Almost all configuration files should show Object. An Array root is unusual — verify it is intentional.
• Total Nodes. The count of all JSON values in the structure, including all nested objects, arrays, and scalar values. This gives a rough sense of the file's complexity.
• Max Depth. The deepest nesting level in the file. Compare this against your expectations — a tsconfig.json typically has a depth of 2–4; a complex monorepo config might reach 6–8.
• Top-level Keys. The number of keys directly in the root object. A large number of top-level keys (more than 20 or 30 in a config file) may suggest the file has grown organically and would benefit from reorganization.
• Comments Stripped. The number of comment tokens the preprocessor removed. If this is 0 and you know the file contains comments, there may be a comment that was incorrectly written (e.g., a # comment instead of //, which JSONC does not support).
• Line Count. The total lines in the original file.
• File Size. The file size in bytes or kilobytes.

Step 8 — Inspect the Structure Preview

For valid files, a second green panel shows the "Structure Preview (top-level)". This is a table of the top-level keys in the root object, with their value types — Object, Array, String, Number, Boolean, or Null — displayed alongside each key name.

Use this panel to quickly confirm:

• All expected top-level sections are present (e.g., compilerOptions, include, exclude in a tsconfig.json)
• No unexpected keys are present (a key that appears here but shouldn't may indicate a copy-paste from another config or a typo in the key name)
• Value types are what you expect — a key you expect to hold an object shows "Object", not "String" or "Null"

The preview shows only the top-level keys. To inspect the values inside nested objects, you will need to open the file directly — the preview is not a full tree view, just a quick top-level sanity check.

Worked Examples

Example 1: tsconfig.json failing to compile

Situation: Your TypeScript project's tsconfig.json was working yesterday, but today tsc is reporting a parse error and refusing to compile.

What to do: Drop the tsconfig.json into the Jsonc Validator. If the status bar shows red with a parser error like "Unexpected token } in JSON at position 342", the file has a structural error — probably a missing comma after a new option someone added. Find the area around position 342 in the cleaned content (or look at recent changes in your diff) and fix the syntax.

If the status bar shows green, the JSONC syntax is correct and the problem is with a TypeScript compiler option value, not the file structure. Check the tsc error message more carefully — it may be complaining about an unknown option name or an invalid value rather than a parse error.

Example 2: VS Code settings not applying

Situation: You edited your workspace settings.json to add a new extension's configuration, but the settings are not taking effect.

What to do: Drop settings.json into the Jsonc Validator. Check the Warnings panel for duplicate key warnings — if the extension's configuration key already exists elsewhere in the file and you added it a second time, VS Code may be using the first occurrence, the second, or silently discarding one. Merge the duplicate entries. Also check the structure preview to confirm the extension's key is present at the top level with the correct type.

Example 3: ESLint config silently ignoring rules

Situation: You added new rules to your .eslintrc.jsonc, but ESLint is not enforcing them. No error — it simply behaves as if the rules aren't there.

What to do: Drop the config file into the Jsonc Validator and check for duplicate key warnings. A common cause of silent rule-ignoring is a duplicate "rules" key — ESLint uses one and silently discards the other. If you find a duplicate, merge both rules objects into a single "rules" block. The structure preview will confirm there is only one rules entry at the top level after the fix.

Example 4: Validating a generated configuration file

Situation: A scaffolding tool generated a tsconfig.json for a new project. You want to verify it is syntactically correct before starting to modify it.

What to do: Drop the generated file into the validator immediately. Auto-generated config files are usually correct, but some tools produce files with encoding issues (particularly BOM-prefixed files on Windows), non-standard comment syntax, or structural quirks. If the validator returns green with no warnings, the file is ready to use. If it flags a BOM or encoding warning, re-save without the BOM before proceeding.

Tips and Edge Cases

• Plain .json files work too. The tool accepts both .jsonc and .json files. A plain JSON file with no comments or trailing commas will validate correctly — the comment stripping and trailing comma removal steps are no-ops, and the file is validated as standard JSON.
• JSONC does not support # comments. Some configuration formats use # for comments (TOML, YAML, Python). JSONC does not. A line beginning with # will cause a JSON parse error. If your file uses # comments, it is not JSONC — convert the comments to // first.
• Large files. The tool reads the entire file into memory before processing. Files up to 50 MB are supported. Very large files (10 MB+) may take a second or two to process on older hardware, but the validation will still complete correctly.
• Validating multiple files. After validating one file, click the ✕ button in the filename bar to clear it, then drop or browse for the next file. Results from the previous run are cleared automatically when you click Validate on a new file.
• The tool works offline. Once the page has loaded, validation requires no network connection. You can disconnect from the internet and continue validating files — useful if you are working with sensitive configuration that should not be on a network-connected machine.
• Error positions in cleaned vs. original content. The error position reported by the JSON parser refers to the cleaned content (after comment and trailing comma removal), not the original file. If the cleaned content is shorter than the original (because comments were stripped), the position will not map directly to a line number in the original. Use the position as an approximate guide and look in that region of your file for the structural problem.