How to Convert JSON with Nested Arrays to CSV Using jq

Learn how to convert JSON records containing arrays into a CSV format with multiple rows per item using jq's --slurp option and string interpolation.
---
This video is based on the question https://stackoverflow.com/q/79473037/ asked by the user 'BRASK0' ( https://stackoverflow.com/u/15315720/ ) and on the answer https://stackoverflow.com/a/79473083/ provided by the user 'Paolo' ( https://stackoverflow.com/u/3390419/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: Cannot index string with string "name" - CSV output from JSON

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to drop me a comment under this video.
---
Introduction

Converting JSON data into CSV format can be tricky, especially when the JSON contains arrays nested within objects. For example, if you have a JSON file with entries that look like this:

[[See Video to Reveal this Text or Code Snippet]]

You may want to produce a CSV where each alias gets its own row alongside the name, like:

[[See Video to Reveal this Text or Code Snippet]]

The Problem

When trying to use jq to convert this JSON stream to CSV, common errors arise such as:

[[See Video to Reveal this Text or Code Snippet]]

This typically happens because the JSON is treated as separate objects rather than a single array, and your jq expression tries to index a string instead of an object.

The Solution: Use --slurp to Read as an Array

The jq option --slurp (or -s) reads all input JSON values into an array. This means you can then iterate over this array (.[]) safely.

Step-by-step command:

[[See Video to Reveal this Text or Code Snippet]]

-s or --slurp collects all JSON objects into one array.

( "name,aliases" ), ... prints the CSV header.

.[] iterates over each object in the array.

(.name),(.aliases[]) produces one line per alias.

Why this works

The JSON objects are processed as array elements.

.aliases[] expands the aliases array into separate rows, paired with their corresponding name.

The CSV header is manually specified.

Output is in raw string mode (-r) for clean CSV formatting.

Summary

Use jq --slurp to convert multiple JSON objects into an array.

Extract fields and expand array items using .[] and .aliases[].

Construct CSV header manually.

This approach avoids "Cannot index string with string" errors caused by incorrect JSON streaming handling.

With just one concise command, you can produce well-structured CSVs from complex JSON sources.