agourlay / json-2-csv

Transforms JSON collections into CSV files.

Version Matrix

json-2-csv Maven Central Join the chat at

A library transforming JSON collections into CSV files.


  • ingests JSON collections from a File or from a LazyList[String].
  • turns nested JSON objects into extra CSV columns and lines.
  • works in a streaming fashion with a small memory footprint.


  • the JSON objects in the collection level must share a common structure.
  • the first element should be a complete definition of the structure, the following elements can be sparse.
  • the transformation stops at the first error encountered.

Input & output formats

A file containing a JSON collection like this is transformed into a CSV file like that.

When nested objects are turned into extra columns the content of the parent object is not repeated.


Two methods on the Json2Csv object returning an Either of the number of CSV lines written to the OutputStream:

def convert(file: File, resultOutputStream: OutputStream): Either[Exception, Long]

def convert(chunks:  LazyList[String], resultOutputStream: OutputStream): Either[Exception, Long]

Usage example

object Boot {
    if (args.isEmpty) println("Error - Provide the CSV file path as argument ")
    else {
      val output = new FileOutputStream("result-json.csv")
      Json2Csv.convert(new File(args(0)), output) match {
        case Right(nb) => println(s"$nb CSV lines written to 'result-json.csv'")
        case Left(e)  => println(s"Something bad happened $e")


libraryDependencies ++= Seq(
  "com.github.agourlay" %% "json-2-csv" % "0.5.6",


This code is open source software licensed under the MIT License.