orcus-json
Help output
Usage: orcus-json [options] FILE
The FILE must specify the path to an existing file.
Options:
-h [ --help ] Print this help.
--mode arg Mode of operation. Select one of the following
options: convert, lint, map, map-gen, structure,
or subtree.
--resolve-refs Resolve JSON references to external files.
-o [ --output ] arg Output file path.
-f [ --output-format ] arg Specify the format of output file. Supported
format types are:
* XML (xml)
* JSON (json)
* YAML (yaml)
* flat tree dump (check)
* no output (none)
-m [ --map ] arg Path to a map file. This parameter is only used
in map mode, and it is required in that mode.
-i [ --indent ] arg Number of whitespace characters to use for one
indent level. This is applicable when the command
generates output in JSON format.
-p [ --path ] arg JSONPath expression specifying the root of a
subtree to extract. It is only used in subtree
mode.
Supported modes
This command supports the following modes:
convert
lint
map
map-gen
structure
subtree
convert
The convert
mode is used to perform simple conversion of a JSON document to
a different format that supports similar property-tree structure, such as XML
and YAML.
You can also “convert” a JSON document to JSON as well. This may seem
pointless, but may be useful when the source JSON document contains JSON
references, and you want to resolve them by specifying the --resolve-refs
option. Note, however, that this command currently only supports resolving
references to external files via relative paths. References to other resource
types may be added in the future.
lint
The lint
mode is used to reformat a JSON document optionally with a
different indent level.
map and map-gen
The map
and map-gen
modes are related, and are typically used together.
The map
mode is used to map a JSON document to a spreadsheet document model
with a used-defined mapping rule, and the map-gen
mode is used to
auto-generate a mapping rule based on the content of the source JSON document.
Refer to the Mapping JSON to spreadsheet section on a detailed example of how to use the these modes to map a JSON document to a spreadsheet document model.
structure
The structure
mode analyses the overall structure of the source JSON
document, and prints paths to all identified “leaf-node” values to standard
output. Each path is expressed in a JSONPath-like format. Refer to the
Mapping JSON to spreadsheet section for the detailed description of this
format.
subtree
the subtree
mode allows you to extract a subtree structure from a JSON
document using a JSONPath expression
to specify the root of the subtree. Note that this mode only supports a limited
subset of the full JSONPath expression syntax. Both the dot notation and the
bracket notation are supported, as well as the wildcard symbol.
Example usage
Reformat JSON document
You can use this command to re-format a JSON document by specifying --mode
to lint
, with an optional indent level via --indent
option. The
following command reformats the input JSON file in a “prettified” format with the
indent level of 2:
orcus-json --mode lint --indent 2 path/to/input.json
The command writes the output to standard output by default, or you can specify
the --output
option to have it written to a local file instead. If you
don’t specify the --indent
option, it defaults to the indent level of 4.
Extract subtree from JSON document
To extract a subtree structure from a JSON document, use the subtree
mode with
the root of a desired subtree to extract:
orcus-json --mode subtree -p "$.store.fruits[3]" -i 2 path/to/source.json
This command traverses the original JSON document by following the store
and fruits
object keys and taking the 4th element of an array as the new root of the tree, and
writes it to stdout with the indent level of 2.
You can also use the wildcard expression to select all elements of an array, as in the following example:
orcus-json --mode subtree -p "$.store.fruits[*].name" -i 2 path/to/source.json
This command traverses the original JSON document through the store
and
fruits
objects keys as in the previous example, but selects all elements of
the array, and in each element only grabs the name
key of the object below
it.
Convert JSON document to YAML
To convert a JSON document to YAML, use the convert
mode and specify the
output format to yaml
in the --output-format
option or simply -f
:
orcus-json --mode convert -f yaml path/to/input.json
The command then writes the converted document to standard output. If you wish
to write it to a local file, use the --output
option to specify the path to
output file the command can write to.