Learn JSONL in 5 Minutes - Quick Start Guide

Quick Start Guide

Minute 1: The Basics Minute 2: Write Your First JSONL Minute 3: Read JSONL Data Minute 4: Common Operations

Minute 1: What is JSONL?

Regular JSON

[
  {
    "id": 1,
    "name": "Alice",
    "email": "[email protected]"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "[email protected]"
  }
]

Entire file must be valid JSON

Cannot append without re-parsing

Entire file loaded into memory

JSONL Format

{"id": 1, "name": "Alice", "email": "[email protected]"}
{"id": 2, "name": "Bob", "email": "[email protected]"}

One valid JSON object per line

Append-friendly (just add a new line)

Stream line-by-line (minimal memory)

The Key Concept

JSONL is simply regular JSON objects, separated by newlines. Each line is a complete, self-contained JSON object. That's it!

Minute 2: Write Your First JSONL File

Python

import json

# Sample data
users = [
    {"id": 1, "name": "Alice", "role": "developer"},
    {"id": 2, "name": "Bob", "role": "designer"},
    {"id": 3, "name": "Charlie", "role": "manager"}
]

# Write to JSONL file
with open('users.jsonl', 'w') as f:
    for user in users:
        f.write(json.dumps(user) + '\n')

print("Created users.jsonl successfully!")

JavaScript (Node.js)

const fs = require('fs');

// Sample data
const users = [
    {id: 1, name: "Alice", role: "developer"},
    {id: 2, name: "Bob", role: "designer"},
    {id: 3, name: "Charlie", role: "manager"}
];

// Write to JSONL file
const lines = users.map(user => JSON.stringify(user)).join('\n');
fs.writeFileSync('users.jsonl', lines);

console.log('Created users.jsonl successfully!');

Bash (Manual Creation)

# Create JSONL file manually
cat > users.jsonl << 'EOF'
{"id": 1, "name": "Alice", "role": "developer"}
{"id": 2, "name": "Bob", "role": "designer"}
{"id": 3, "name": "Charlie", "role": "manager"}
EOF

echo "Created users.jsonl successfully!"

Minute 3: Read JSONL Data

Python - Stream Processing

import json

# Read JSONL file line by line (memory efficient!)
with open('users.jsonl', 'r') as f:
    for line in f:
        user = json.loads(line)
        print(f"{user['name']} is a {user['role']}")

# Output:
# Alice is a developer
# Bob is a designer
# Charlie is a manager

JavaScript - Async Stream

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

// Read JSONL file with streams (memory efficient!)
const fileStream = fs.createReadStream('users.jsonl');
const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity
});

for await (const line of rl) {
    const user = JSON.parse(line);
    console.log(`${user.name} is a ${user.role}`);
}

Bash with jq

# Read and process with jq
cat users.jsonl | jq -r '"\(.name) is a \(.role)"'

# Filter developers only
cat users.jsonl | jq 'select(.role == "developer")'

# Count total lines
wc -l users.jsonl

Minute 4: Common Operations

Append New Data

Adding new records is simple - just append a new line!

# Python
with open('users.jsonl', 'a') as f:
    new_user = {"id": 4, "name": "Diana"}
    f.write(json.dumps(new_user) + '\n')

# Bash
echo '{"id": 4, "name": "Diana"}' >> users.jsonl

Filter Data

Process only the records you need

# Python
with open('users.jsonl', 'r') as f:
    for line in f:
        user = json.loads(line)
        if user['role'] == 'developer':
            print(user)

Convert to CSV

Transform JSONL to other formats

# Bash with jq
cat users.jsonl | jq -r '[.id, .name, .role] | @csv'

# Output:
# 1,"Alice","developer"
# 2,"Bob","designer"

Count Records

Quick statistics without loading entire file

# Bash - count lines
wc -l users.jsonl

# Python - count while processing
count = sum(1 for line in open('users.jsonl'))
print(f"Total records: {count}")

Minute 5: Best Practices & Tips

Do

Use UTF-8 encoding for all files
One valid JSON object per line (no arrays)
Use \n (LF) for line endings
Stream process for large files (line-by-line)
Compress with gzip for storage (.jsonl.gz)
Use .jsonl extension (or .json / .ndjson)

Don't

Don't put arrays or objects across multiple lines
Don't use trailing commas after objects
Don't load entire file if you can stream
Don't mix JSON and JSONL in same file
Don't forget error handling for malformed lines
Don't use JSONL for deeply nested hierarchical data

When to Use JSONL

AI/ML Training Data - OpenAI, Vertex AI, etc.

Application Logs - Structured logging

Data Streaming - Real-time pipelines

Big Data - Spark, Hadoop, ETL

Analytics Events - User tracking

API Responses - Streaming results

Next Steps

Full Tutorial

Complete 10-minute deep dive into JSONL with advanced examples

More Examples

Real-world use cases with production-ready code samples

Language Guides

Python, JavaScript, Go, Rust, Java, and more

Best Practices

Production tips, performance optimization, and error handling

Tools & CLI

Command-line tools and utilities for working with JSONL

ML Use Cases

Using JSONL for AI training data and machine learning pipelines

Quick Reference Card

File Extensions

.jsonl, .json, .ndjson

MIME Type

application/x-ndjson

Line Ending

\n (LF - Unix style)

Encoding

UTF-8

Valid JSONL Example

{"timestamp": "2025-11-11T10:00:00Z", "event": "login", "user_id": 123}
{"timestamp": "2025-11-11T10:01:15Z", "event": "page_view", "user_id": 123}
{"timestamp": "2025-11-11T10:02:30Z", "event": "purchase", "user_id": 456}