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.