Command Line Interface
New in version 0.9.0
Python JSONPath includes a script called json, exposing JSONPath, JSON Pointer and JSON Patch features on the command line. Use the --version argument to check the current version of Python JSONPath, and the --help argument to display command information.
$ json --help
usage: json [-h] [--debug] [--pretty] [-v] [--no-unicode-escape] COMMAND ...
JSONPath, JSON Pointer and JSON Patch utilities.
positional arguments:
COMMAND
path Find objects in a JSON document given a JSONPath.
pointer Resolve a JSON Pointer against a JSON document.
patch Apply a JSON Patch to a JSON document.
optional arguments:
-h, --help show this help message and exit
--debug Show stack traces. (default: False)
--pretty Add indents and newlines to output JSON. (default: False)
-v, --version Show the version and exit.
--no-unicode-escape Disable decoding of UTF-16 escape sequence within paths and pointers. (default:
False)
Use [json COMMAND --help] for command specific help.
Usage Examples:
Find objects in source.json matching a JSONPath, write them to result.json.
$ json path -q "$.foo['bar'][?@.baz > 1]" -f source.json -o result.json
Resolve a JSON Pointer against source.json, pretty print the result to stdout.
$ json --pretty pointer -p "/foo/bar/0" -f source.json
Apply JSON Patch patch.json to JSON from stdin, output to result.json.
$ cat source.json | json patch /path/to/patch.json -o result.json
Use json COMMAND --help for command specific help.
$ json path --help
usage: json path [-h] (-q QUERY | -r PATH_FILE) [-f FILE] [-o OUTPUT]
Find objects in a JSON document given a JSONPath.
optional arguments:
-h, --help show this help message and exit
-q QUERY, --query QUERY
JSONPath query string.
-r PATH_FILE, --path-file PATH_FILE
Text file containing a JSONPath query.
-f FILE, --file FILE File to read the target JSON document from. Defaults to reading from the
standard input stream.
-o OUTPUT, --output OUTPUT
File to write resulting objects to, as a JSON array. Defaults to the standard
output stream.
--no-type-checks Disables filter expression well-typedness checks.
--strict Compile and evaluate JSONPath expressions with strict compliance with RFC 9535.
Global Options
These arguments apply to any subcommand and must be listed before the command.
--debug
Enable debugging. Display full stack traces, if available, when errors occur. Without the --debug option, the following example shows a short "json path syntax error" message.
$ json path -q "$.1" -f /tmp/source.json
json path syntax error: unexpected token '1', line 1, column 2
With the --debug option, we get the stack trace triggered by JSONPathSyntaxError.
$ json --debug path -q "$.1" -f /tmp/source.json
Traceback (most recent call last):
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/bin/json", line 8, in <module>
sys.exit(main())
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/cli.py", line 338, in main
args.func(args)
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/cli.py", line 234, in handle_path_command
path = jsonpath.compile(args.query or args.path_file.read())
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/env.py", line 148, in compile
_path: Union[JSONPath, CompoundJSONPath] = JSONPath(
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/path.py", line 49, in __init__
self.selectors = tuple(selectors)
File "/home/james/.local/share/virtualenvs/jsonpath_cli-8Tb3e-ir/lib/python3.9/site-packages/jsonpath/parse.py", line 256, in parse
raise JSONPathSyntaxError(
jsonpath.exceptions.JSONPathSyntaxError: unexpected token '1', line 1, column 2
--pretty
Enable pretty formatting when outputting JSON. Adds newlines and indentation to output specified with the -o or --output option. Without the --pretty option, the following example output is on one line.
$ json pointer -p "/categories/1/products/0" -f /tmp/source.json
{"title": "Cap", "description": "Baseball cap", "price": 15.0}
With the --pretty option, we get nicely formatted JSON output.
$ json --pretty pointer -p "/categories/1/products/0" -f /tmp/source.json
{
"title": "Cap",
"description": "Baseball cap",
"price": 15.0
}
--no-unicode-escape
Disable decoding of UTF-16 escape sequences, including surrogate paris. This can improve performance if you know your paths and pointers don't contain UTF-16 escape sequences.
Commands
One of the subcommands path, pointer or patch must be specified, depending on whether you want to search a JSON document with a JSONPath, resolve a JSON Pointer against a JSON document or apply a JSON Patch to a JSON Document.
path
Find objects in a JSON document given a JSONPath. One of -q/--query or -r/--path-file must be given. -q being a JSONPath given on the command line as a string, -r being the path to a file containing a JSONPath.
-q / --query
The JSONPath as a string.
-r / --path-file
The path to a file containing a JSONPath.
-f / --file
The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.
-o / --output
The path to a file to write resulting objects to, as a JSON array. If omitted or a hyphen (-) is given, results will be written to the standard output stream.
--no-type-checks
New in version 0.10.0
Disables JSONPath filter expression well-typedness checks. The well-typedness of a filter expression is defined by RFC 9535.
--strict
New in version 2.0.0
Compile and evaluate JSONPath expressions with strict compliance with RFC 9535.
pointer
Resolve a JSON Pointer against a JSON document. One of -p/--pointer or -r/--pointer-file must be given. -p being a JSON Pointer given on the command line as a string, -r being the path to a file containing a JSON Pointer.
-p / --pointer
An RFC 6901 formatted JSON Pointer string.
-r / --pointer-file
The path to a file containing a JSON Pointer.
-f / --file
The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.
-o / --output
The path to a file to write the resulting object to. If omitted or a hyphen (-) is given, results will be written to the standard output stream.
-u / --uri-decode
Enable URI decoding of the JSON Pointer. In this example, we would look for a property called "hello world" in the root of the target document.
patch
Apply a JSON Patch to a JSON document. Unlike path and pointer commands, a patch can't be given as a string argument. PATCH is a positional argument that should be a file path to a JSON Patch document or a hyphen (-), which means the patch document will be read from the standard input stream.
These examples read the patch from patch.json and the document to modify from target.json
-f / --file
The path to a file containing the target JSON document. If omitted or a hyphen (-), the target JSON document will be read from the standard input stream.
-o / --output
The path to a file to write the resulting object to. If omitted or a hyphen (-) is given, results will be written to the standard output stream.
-u / --uri-decode
Enable URI decoding of JSON Pointers in the patch document.