Getting Started with JSONL

A complete beginner-friendly tutorial to master JSON Lines format in 10 minutes. From your first JSONL file to production-ready code.

10 min read Beginner Friendly Code Examples

Tutorial Contents

What is JSONL? Your First JSONL File Reading JSONL Writing JSONL Common Mistakes Next Steps

What is JSONL?

Regular JSON

[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25},
  {"name": "Charlie", "age": 35}
]

One big array - must load everything into memory

JSONL Format

{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Charlie", "age": 35}

One JSON object per line - stream line by line

Key Concept: JSONL is simply JSON objects separated by newlines. Each line is a complete, valid JSON object. That's it!

Your First JSONL File

Step 1: Create a new file

Create a file named users.jsonl (or users.json - both extensions work!)

Step 2: Add your data

Type or paste this content:

{"id": 1, "name": "Alice Johnson", "email": "[email protected]", "role": "developer"}
{"id": 2, "name": "Bob Smith", "email": "[email protected]", "role": "designer"}
{"id": 3, "name": "Charlie Brown", "email": "[email protected]", "role": "manager"}

Congratulations!

You just created your first JSONL file! Each line is a complete JSON object representing one user.

Reading JSONL Files

Python

Method 1: Standard Library (Recommended)

import json

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

# Output:
# Name: Alice Johnson, Role: developer
# Name: Bob Smith, Role: designer
# Name: Charlie Brown, Role: manager

Method 2: Load All Data

import json

# Read all at once (use only for small files)
users = []
with open('users.jsonl', 'r') as file:
    for line in file:
        users.append(json.loads(line))

print(f"Total users: {len(users)}")  # Total users: 3

JavaScript (Node.js)

Using readline module

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

async function readJSONL(filename) {
    const fileStream = fs.createReadStream(filename);
    const rl = readline.createInterface({
        input: fileStream,
        crlfDelay: Infinity
    });

    for await (const line of rl) {
        const user = JSON.parse(line);
        console.log(`Name: ${user.name}, Role: ${user.role}`);
    }
}

readJSONL('users.jsonl');

Go

Using bufio.Scanner

package main

import (
    "bufio"
    "encoding/json"
    "fmt"
    "os"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Role  string `json:"role"`
}

func main() {
    file, _ := os.Open("users.jsonl")
    defer file.Close()

    scanner := bufio.NewScanner(file)
    for scanner.Scan() {
        var user User
        json.Unmarshal(scanner.Bytes(), &user)
        fmt.Printf("Name: %s, Role: %s\n", user.Name, user.Role)
    }
}

Writing JSONL Files

Python 

import json

users = [
    {"id": 1, "name": "Alice Johnson", "role": "developer"},
    {"id": 2, "name": "Bob Smith", "role": "designer"},
    {"id": 3, "name": "Charlie Brown", "role": "manager"}
]

# Write to JSONL file
with open('output.jsonl', 'w') as file:
    for user in users:
        # Write each object as JSON on its own line
        file.write(json.dumps(user) + '\n')

print("File written successfully!")

Important!

Always add \n after each JSON object. Don't forget the newline!

JavaScript (Node.js) 

const fs = require('fs');

const users = [
    {id: 1, name: "Alice Johnson", role: "developer"},
    {id: 2, name: "Bob Smith", role: "designer"},
    {id: 3, name: "Charlie Brown", role: "manager"}
];

// Create write stream
const writeStream = fs.createWriteStream('output.jsonl');

// Write each object
users.forEach(user => {
    writeStream.write(JSON.stringify(user) + '\n');
});

writeStream.end();
console.log('File written successfully!');

Common Mistakes to Avoid

Missing Newlines 

{"id": 1}{"id": 2}  ❌ WRONG!
{"id": 1}
{"id": 2}  ✅ CORRECT!

Wrapping in Array 

[
  {"id": 1},
  {"id": 2}
]  ❌ That's JSON, not JSONL!

Multi-line JSON Objects 

{
  "id": 1,
  "name": "Alice"
}  ❌ Each object must be on ONE line!
{"id": 1, "name": "Alice"}  ✅ Correct!

Trailing Comma 

{"id": 1},
{"id": 2},  ❌ No commas between lines!
{"id": 1}
{"id": 2}  ✅ Just newlines!

Quick Reference

Format Rules

  • One JSON object per line
  • Each line ends with newline (\n)
  • No commas between lines
  • No array wrapper

File Extensions

  • .jsonl (recommended)
  • .json (also works)
  • .ndjson (same format)
  • .jsonlines (valid)

When to Use

  • Streaming data
  • Large datasets
  • ML training data
  • Log files

Next Steps

Now that you understand the basics, explore these resources to master JSONL:

More Examples

Real-world use cases and patterns

Best Practices

Production-ready patterns

Language Guides

Deep dives for each language

FAQ

Quick answers to common questions