Building a JSON to JSONL Converter cover image

Building a JSON to JSONL Converter

January 28, 2025

projects

While building data processing pipelines at work, I kept running into a simple but annoying problem - converting JSON files to JSONL format. Sure, I could write a quick script each time, but why do that over and over? So I built a simple web-based JSON to JSONL converter as part of JSONLTools. This is part of a larger project - you can read about how I built the whole platform in my post about building JSONLTools with Laravel and Livewire.

The Problem

If you work with data processing or machine learning pipelines, you've probably dealt with JSONL (JSON Lines) format. It's great for streaming and processing large datasets line by line. But most APIs and data sources give you regular JSON, usually as arrays of objects. Converting between the two formats manually is tedious and error-prone.

I found myself writing the same conversion logic in different projects:

$jsonArray = json_decode($input, true);
$jsonlOutput = '';
foreach ($jsonArray as $item) {
    $jsonlOutput .= json_encode($item) . "\n";
}

There had to be a better way.

Building the Solution

I decided to build a web-based converter using my go-to stack:

The core conversion logic is pretty straightforward:

public function convertToJsonl()
{
    try {
        $decodedJson = json_decode($jsonInput, true);

        if (is_array($decodedJson)) {
            if (array_is_list($decodedJson)) {
                // Convert array of objects to JSONL
                $jsonlLines = array_map(function ($item) {
                    return json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
                }, $decodedJson);
                $this->jsonlOutput = implode("\n", $jsonlLines);
            } else {
                // Handle single object
                $this->jsonlOutput = json_encode($decodedJson, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
            }
        }
    } catch (\Exception $e) {
        // Error handling
    }
}

The interesting parts came from user feedback and edge cases:

  1. Some JSON files had Unicode characters that were getting mangled - fixed by adding the JSON_UNESCAPED_UNICODE flag
  2. Users needed to handle both arrays of objects and single objects - added format detection
  3. Copy-paste was annoying for large files - added a one-click copy button

Real-World Example

Here's what the converter does. Take this JSON:

[
    {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]"
    },
    {
        "id": 2,
        "name": "Jane Smith",
        "email": "[email protected]"
    }
]

It converts it to JSONL:

{"id":1,"name":"John Doe","email":"[email protected]"}
{"id":2,"name":"Jane Smith","email":"[email protected]"}

Simple, but useful when you're processing thousands of records.

What I Learned

Building this seemingly simple tool taught me a few things:

  1. Native is Better: PHP's built-in JSON functions are way faster than any custom parsing I tried
  2. Memory Matters: Processing line-by-line keeps memory usage low even with large files
  3. UX Details Count: Clear error messages and keyboard shortcuts make a big difference
  4. Keep it Focused: I was tempted to add tons of features, but the tool is better because it does one thing well

What's Next

I've got a few ideas for improvements based on user feedback:

Try It Out

If you need to convert JSON to JSONL format, give the converter a try. It's free and doesn't require any signup. Just paste your JSON and get your JSONL.

While you're at it, check out our other JSONL tools:

Want to learn more about JSONL? Check out my guides on What is JSONL? and JSONL Best Practices.