JSON Lines Format Documentation

Complete documentation for the JSON Lines (JSONL) text file format. This documentation covers syntax rules, examples, MIME types, file extensions, and implementation guidelines.

What is JSON Lines?

JSON Lines is a convenient format for storing structured data that may be processed one record at a time. It works well with unix-style text processing tools and shell pipelines. Each line in a JSON Lines file is a valid JSON value, most commonly a JSON object.

Key Characteristics

• UTF-8 encoding
• Each line is a valid JSON value
• Line terminator is '\n'
• Works well with streaming parsers
• Memory-efficient for large datasets

Format Rules

A valid JSON Lines file must follow these rules:

UTF-8 Encoding - Files must be encoded in UTF-8
Valid JSON per line - Each line must be a valid JSON value
Newline separation - Lines are separated by the newline character '\n'
No array wrapping - The file should not be wrapped in square brackets
No trailing commas - No commas between lines

Example

Here's a simple example of a JSON Lines file:

example.jsonl

{"name": "John Doe", "age": 30, "city": "New York"}
{"name": "Jane Smith", "age": 25, "city": "San Francisco"}
{"name": "Bob Johnson", "age": 35, "city": "Chicago"}

MIME Types and File Extensions

JSON Lines files should use the following MIME types and file extensions:

MIME Types

• application/jsonl (preferred)
• application/x-jsonl
• text/jsonl

File Extensions

• .jsonl (most common)
• .ndjson (Newline Delimited JSON)
• .jsonlines (less common)

Use Cases

JSON Lines format is commonly used for:

Log file storage and analysis
Data streaming and real-time processing
Machine learning datasets
Database exports and imports
API responses for large datasets
Data pipelines and ETL processes

Implementation Examples

Python

example.py

import json

with open('data.jsonl', 'r') as f:
    for line in f:
        data = json.loads(line.strip())
        process(data)

JavaScript

example.js

const fs = require('fs');
const readline = require('readline');

const fileStream = fs.createReadStream('data.jsonl');
const rl = readline.createInterface({
  input: fileStream,
  crlfDelay: Infinity
});

rl.on('line', (line) => {
  const data = JSON.parse(line);
  process(data);
});

JSONL Tools

Use our free online tools to work with JSONL files:

JSONL Converter

Convert between JSON, CSV, and JSONL formats

JSONL Validator

Validate JSONL files for syntax errors

[ JSONL::Tools ]