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

The Ndjson Validator runs entirely in your browser — your data 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 an NDJSON or JSONL 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/ndjson-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 "NDJSON Validator"), or directly via the URL above.

Step 2 — Load Your NDJSON File

There are two ways to load a file. The easiest is drag and drop: drag your .ndjson, .jsonl, or .json file from your file manager and drop it anywhere on the drop zone. The drop zone accepts these extensions 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 — you will see the filename appear in a bar above the buttons.

If you drop a file with an unsupported extension, the tool displays a type error message identifying the extension that was rejected. Only .ndjson, .jsonl, and .json files are accepted. 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 NDJSON button. Validation runs in JavaScript in your browser tab — for most files under a few megabytes, results appear instantly. Clicking the button also clears any results from a prior 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 NDJSON — no issues found." Every non-empty line parsed successfully as JSON, all root values are objects or arrays, no encoding issues were detected, and no key consistency problems were found.
• Yellow — "Valid NDJSON — N warning(s). See details below." The file is structurally valid but the validator detected conditions worth reviewing. See the Warnings panel for details.
• Red — "Validation failed — N error(s) found." One or more lines failed to parse as valid JSON, or a fatal encoding issue was detected. The Error panel below provides the full list of errors with line numbers.

Step 5 — Review the Error Panel

If validation fails, a red Validation Errors panel appears below the status bar. Each error is listed with its line number and the parser's error message. The validator reports the first 10 errors by line number; if there are more than 10, a summary count is shown for the remainder. Common error messages and what they mean:

"Line N: JSON syntax error — Unexpected token X in JSON at position P"

The JSON parser could not parse line N. The character X at position P is where the parser gave up. Common causes:

• A missing closing brace or bracket — the record started but did not finish on the same line
• An unquoted key: {key: "value"} instead of {"key": "value"}
• A trailing comma on the last property: {"a": 1,} — unlike JSONC, standard JSON and NDJSON do not permit trailing commas
• A single-quoted string: {'key': 'value'} — JSON requires double quotes
• A JavaScript-specific value: undefined, NaN, or Infinity are not valid JSON values

"Line N: root value is a bare [type], not a JSON object or array"

Line N parsed successfully as JSON, but the top-level value is a string, number, boolean, or null rather than an object or array. NDJSON records should be objects {} or arrays []. This error is most commonly caused by an export script that wrote a quoted string or a numeric value to each line instead of a full JSON object.

"File contains null bytes"

The file contains null bytes, which cannot appear in a valid UTF-8 text file. This usually means the file is binary content mistakenly given an NDJSON 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 text.

"File contains no non-empty lines" / "File is empty"

The file has no content after stripping whitespace and the trailing newline. Verify you loaded the correct file — the filename bar shows the name of the loaded file for confirmation.

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 structure is valid — but they flag conditions that may indicate data quality problems:

"N empty line(s) found at line(s): X, Y, Z"

Blank lines were found in the file. A single trailing blank line is silently removed before processing; only interior empty lines or multiple trailing blank lines are reported. If the empty lines were intentional separators, most NDJSON parsers will handle them correctly, but the NDJSON specification does not require parser support for interior blank lines.

"UTF-8 BOM detected at the start of the file"

The file begins with a UTF-8 byte order mark. The validator strips the BOM and continues processing, but the warning is shown because strict JSON parsers will fail on a BOM-prefixed file. Re-save the file without the BOM: in VS Code, click the encoding indicator in the status bar and choose "Save with Encoding" → UTF-8 (without BOM).

"File uses bare CR (\\r) line endings"

The file uses old Mac-format line endings. Convert the file to LF line endings before using it in production — most NDJSON tools handle CRLF, but bare CR is not universally supported.

"Key "X" is missing from N of M record(s)"

A top-level key that appears in some records is absent from others. The message tells you the key name, how many records have it, and how many are missing it. Decide whether the missing key is intentional (the field is optional) or a data quality problem (a bug in the export logic). If you expect every record to have this key, investigate the records where it is absent.

"Line N: duplicate key(s) in object: "X""

Record on line N contains the key X more than once. The duplicate key will cause silent data loss in most parsers — only one of the values will survive. Find the line in your source file, identify which value is correct, and remove the duplicate.

"File contains a mix of JSON objects (N) and JSON arrays (M)"

Some records are objects and some are arrays. This is technically permitted by the NDJSON specification but unusual in practice. If the mix is unintentional, check your export logic — you may be concatenating records from two different sources that use different shapes.

Step 7 — Read the Stats Panel

When a file passes validation (green or yellow status), a green "Valid NDJSON" stats panel shows file-level metrics extracted during parsing:

• Total records. The count of non-empty lines that parsed successfully as JSON. This is the number of records that will be available to a downstream consumer. Compare it against the expected row count from your source query or export command.
• Unique keys. The count of distinct top-level keys found across all object records. For a dataset where every record should have the same schema, this number should match the expected column count. A higher number indicates extra keys in some records.
• Record type. "Objects {}" if all records are JSON objects, "Arrays []" if all are arrays, or "Mixed" if both types are present.
• Parse errors. The count of lines that failed to parse. Zero is the target — any non-zero value means some records are malformed and will be skipped or rejected by downstream consumers.
• Empty lines. The count of blank lines found in the file (excluding the trailing newline).
• File size. The size of the file in bytes, kilobytes, or megabytes.
• Line endings. LF (Unix/macOS, the standard), CRLF (Windows), or CR (old Mac). LF is the recommended format for NDJSON.
• BOM present. Yes or No. If Yes, re-save without the BOM before using the file in production.

Step 8 — Inspect the Keys Panel

For files where records are JSON objects, a second green panel lists all distinct top-level keys found across all records, sorted alphabetically, with a count in the panel header showing how many unique keys were found. Use this panel to:

• Confirm all expected field names are present — a typo in a field name (e.g., timestmap instead of timestamp) will appear as a separate key here
• Spot unexpected keys that shouldn't be in the dataset — an extra key that appears here but isn't expected may indicate records from the wrong source were included
• Cross-check the key list against your schema documentation before loading the file into a database or ML framework

Keys are listed with sequential numbers in the left column for easy reference. If a key appears here but you expected it to be absent, or is absent when you expected it to be present, investigate the records that contain (or don't contain) it using the data preview below.

Step 9 — Review the Data Preview

The data preview panel renders the first 5 records in a formatted table — one column per top-level key, one row per record. For object records, column headers show the key names; for array records, headers show index positions ([0], [1], etc.).

Use the preview to visually confirm the parsed data looks correct:

• Values appear in the right columns — if a value appears under the wrong column header, the field names in your data may have shifted or been reordered
• Values are the right type — a column you expect to contain numbers should not show string-quoted numbers or empty cells where numbers are expected
• No columns appear unexpectedly empty across all 5 records — consistent nulls in a column that should have data may indicate an export bug affecting that field
• No columns are cut off — very long values are truncated with an ellipsis in the preview table; hover over a cell to see the full value in a tooltip

The preview is not a substitute for full data review, but it is the fastest way to catch structural problems — a misconfigured export, a shifted delimiter, or an encoding issue that garbles string values — before the file is loaded into a production system.

Worked Examples

Example 1: ML fine-tuning dataset rejected by the API

Situation: You prepared a JSONL fine-tuning dataset for a language model API. The API rejected the file with a generic "invalid format" error and provided no line number.

What to do: Drop the file into the Ndjson Validator. If the error panel shows "Line 47: JSON syntax error — Unexpected token ' in JSON at position 12", look at line 47 in your file — it almost certainly contains a single-quoted string. JSONL for ML fine-tuning must use standard JSON with double quotes. Find and replace all single-quoted strings in your data before resubmitting. If the error panel shows a root type error ("root value is a bare string"), your export script wrote escaped JSON strings rather than JSON objects — fix the serialization logic to write full objects.

Example 2: Database import produces fewer rows than expected

Situation: You exported 10,000 records from your database as NDJSON and then imported the file into a new database. The import completed but only 9,847 rows appear in the destination table.

What to do: Drop the file into the Ndjson Validator and check the stats panel. If "Total records" shows fewer than 10,000, some records were not written to the file during export — investigate the export script for silent failures. If "Total records" shows 10,000 but "Parse errors" is 153, then 153 records are malformed and were skipped during import — check the error panel for the line numbers and examine those records in the original file to find the export bug.

Example 3: Key consistency warning on a log export

Situation: You exported structured application logs as NDJSON. The validator shows the file is valid but with 3 key consistency warnings. The warning messages say that the key stack_trace is missing from 9,240 of 9,328 records.

What to do: This is expected behavior. The stack_trace key is only present on error-level log records (88 out of 9,328), which is intentional — it is an optional field that only appears when there is an error to report. No fix is needed. Note the warning for your downstream consumers so they know to handle the missing key gracefully (treat absence as null).

Example 4: Validating a streaming API capture

Situation: You recorded the streaming response from an API and saved it as a .ndjson file. You want to confirm the capture is complete and all records parsed correctly before archiving it.

What to do: Drop the file into the Ndjson Validator. Check "Total records" against the expected number of streaming chunks. Check "Parse errors" — it should be zero for a clean capture. Check "BOM present" — some capture tools prepend a BOM on Windows. Check the data preview to confirm the first 5 records contain the expected fields and values. If everything looks correct, the capture is complete and the file is ready to archive.

Tips and Edge Cases

• Standard .json files work too. The tool accepts .json in addition to .ndjson and .jsonl. A file with a .json extension that contains one JSON object per line will validate correctly as NDJSON. A file that contains a single JSON array will produce a root type error on all lines (each line is a partial array fragment, not a complete JSON value) — this is the correct behavior, because such a file is not NDJSON.
• The trailing newline is not a parse error. Most text editors append a newline after the last line of a file. The validator detects and removes this trailing blank line before processing, so it does not count as an empty line or cause a parse error on a phantom empty record.
• Line numbers in the error panel refer to the original file. Unlike some validators that report positions in a preprocessed version of the content, the NDJSON validator reports the original line numbers from the file as-loaded. Line 47 in the error panel is line 47 in your file — open the file in any text editor and jump directly to that line.
• Large files. The tool reads the entire file into memory before processing. Files up to 50 MB are supported. The key panel lists all distinct keys found across all records — for a file with millions of records, this may include a large number of keys, but the display is paginated and scrollable.
• 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 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 for sensitive data files that should not be processed on a network-connected machine.
• NDJSON does not support comments. Unlike JSONC, NDJSON files cannot contain comments. A line beginning with // will cause a JSON syntax error on that line. If your file contains comment lines, remove them before validating.