I was wondering what they meant by that term as well. Does every JSON document i...

kbouck · on March 17, 2023

It generally means an sequence/array of flat json objects, each key represents a column name, and the value representing the row value for that column. Nested json can also be "flattened".

> "... ordering of key-value pairs"

order of appearance of key-value pairs in input does not matter.

> "... if row #100 introduces a new key-value pair"

this is sparse data. miller handles this with the "unsparsify" verb:

    $ cat in.json
    { "a": 1, "b": 2 }
    { "a": 3, "b": 4 }
    { "a": 5, "b": 6, "c": 7 }

without unsparsify:

    $ cat in.json | mlr --j2p cat
    a b
    1 2
    3 4

    a b c
    5 6 7

with unsparsify:

    $ cat in.json | mlr --j2p unsparsify then cat
    a b c
    1 2 -
    3 4 -
    5 6 7

unsparsify can also set default values:

    $ cat in.json | mlr --j2p unsparsify --fill-with 0 then cat
    a b c
    1 2 0
    3 4 0
    5 6 7

> "... What if the value for a key is an array?"

Array value treatment seems to depend on output format. for output types that can represent arrays, they are preserved:

    $ cat in-array.json
    { "a": [0,1,2], "b": [5,6,7] }
    { "a": [3,4,5], "b": [8,9,0] }

    $ cat in-array.json | mlr --jsonl cat
    {"a": [0, 1, 2], "b": [5, 6, 7]}
    {"a": [3, 4, 5], "b": [8, 9, 0]}

for formats like csv/fixed-width, arrays are flattened into columns, one for each array element:

    $ cat in-array.json | mlr --j2p cat
    a.1 a.2 a.3 b.1 b.2 b.3
    0   1   2   5   6   7
    3   4   5   8   9   0

flatten separator can also be set:

    $ cat in-array.json | mlr --j2p --flatsep _ cat
    a_1 a_2 a_3 b_1 b_2 b_3
    0   1   2   5   6   7
    3   4   5   8   9   0