jshon

jshon [OPTIONS] [FILE]

jshon is typically invoked with one or more options to perform actions on JSON data. If FILE is not provided, jshon reads JSON from standard input.

-i
    Implicitly pretty-print the output. This is often combined with other operations.

-s
    Set the current JSON value to a string. Used for creating or modifying string values.

-e
    Extract or navigate to a value at a specified JSON path. Paths can use dot notation for object keys (e.g., 'key.subkey') or square brackets for array indices (e.g., 'array[0]').

-a
    Create an empty JSON array.

-p
    Pretty-print the JSON output, adding indentation for readability.

-Q
    Quote string output. Ensures that string values are wrapped in double quotes.

-u
    Unquote string output. Removes surrounding double quotes from string values.

-V
    Validate the input JSON. Outputs an error and exits non-zero if the input is not valid JSON.

-v, --version
    Display the version information of jshon and exit.

--help
    Display a brief help message and exit.

jshon is a lightweight command-line utility designed for parsing, manipulating, and creating JSON data within shell scripts. Following the Unix philosophy, it is a small, focused tool that reads JSON input from standard input or a specified file and outputs results to standard output. It supports querying specific elements using path expressions, setting new values, adding elements to objects or arrays, and pretty-printing JSON output. Unlike larger JSON processing tools, jshon prioritizes simplicity and integration with standard shell utilities, making it ideal for automating tasks that involve interacting with JSON-based APIs or configuration files. It handles all standard JSON types, including objects, arrays, strings, numbers, booleans, and null. Its design makes it particularly useful for shell environments where external dependencies should be minimized.

While highly useful for shell scripting, jshon has some limitations:

Limited Error Reporting: It provides basic error messages for malformed JSON, but debugging complex issues might require more robust tools.

No Stream Processing: jshon loads the entire JSON document into memory, which can be inefficient for extremely large JSON files.
Path Syntax Simplicity: Its path syntax is simpler compared to tools like jq, which offers more advanced filtering and transformation capabilities.

Deprecated Options: The -x option for array extraction is deprecated; -e should be used instead.

jshon typically reads JSON data from standard input (stdin) or a specified file argument. All results, whether extracted values or modified JSON structures, are printed to standard output (stdout), making it easy to pipe jshon's output to other shell commands.

Path expressions used with the -e option allow precise navigation within JSON objects and arrays. Object keys are accessed directly (e.g., -e key), and nested keys are separated by dots (e.g., -e parent.child). Array elements are accessed using zero-based indices within square brackets (e.g., -e array[0]). Multiple path segments can be chained.

jshon allows chaining multiple operations by repeating options. For instance, jshon -e key1 -e key2 would first navigate to key1, and then from that resulting object, navigate to key2. This enables complex data transformations in a single command.

While primarily a parser, jshon can also be used to construct simple JSON. For example, jshon -s 'value' creates a JSON string, jshon -a creates an empty array, and jshon -s key -s value creates a JSON object {"key": "value"}, which can be useful for dynamic JSON generation.

jshon was created by Michael P. Jung (miku) as a minimalist and highly portable JSON parser for POSIX shell environments. Its development aimed to provide a simple, single-file executable that adheres to the Unix philosophy of doing one thing well. It gained popularity among shell scripters looking for a less feature-rich but more lightweight alternative to other JSON tools, particularly for quick extraction and manipulation tasks within scripts where installing larger dependencies might be undesirable. Its design emphasizes ease of use and direct integration with standard shell commands.

jq(1), json_pp(1), curl(1), grep(1), awk(1), sed(1)