A JSON inspection & pruning tool.
Project description
Python 3 support only; jsoncut is not currently supported under Python 2.
$ jsoncut --help
Usage: cli.py [OPTIONS] [JSONFILE]
Quickly select or filter out properties in a JSON document.
Options:
-r, --root TEXT Set the root of the JSON document.
-g, --get TEXT Get JSON object members and/or array
elements.
-G, --getdefault <TEXT TEXT>...
Same as --get, except provides a default
value to be used when a key/index is not
found (key, default-value)
-p, --fullpath Works with --get; uses the full key
path for the destination key name.
-d, --del TEXT Deletes JSON object members and/or array
elements.
-a, --any Works with --get & --del; instructs
jsoncut to ignore any key not found
errors.
-l, --list Generates a numbered list of JSON keys;
crawls through all keys in the 1st
JSON object found; list doesn't crawl
through JSON arrays.
-f, --fullscan Works with --list; searches for keys
in all JSON objects, not just the 1st
one.
-i, --inspect Inspect JSON document; crawls through
all keys & indexes in the entire
document; displays keys found, array
locations, JSON types, min & max values,
lengths and/or counts.
-q, --quotechar TEXT Set quoting character used around
command parameters; useful for the Windows
command-console which uses double-quotes
rather than the default single-quotes;
elimates having to escape quote
characters around keynames.
-I, --indent INTEGER The default format when redirecting JSON
output is compact JSON; this option
instead indents the output for human
readibility.
-c, --nocolor Disable syntax highlighting.
-s, --slice Used when the root of the JSON document
is an array; the default is to iterate
through that array; this option disables
iteratation so that the root-level array
can be sliced.
--version Show the version and exit.
--help Show this message and exit.
Common Usage Scenarios
Point to an array of objects within the JSON document with ‘root’ and use ‘get’, ‘getdefault’ or ‘del’ to operate on each object.
Use root to get a branch or a value from the document.
Use slice option to extract elements from a JSON array.
There are other ways to use it, but these are the most common.
Selecting JSON keys
- Keys are specified in dot-notation and can be:
A key name
A Key number (use –list to show the key numbers)
An index number.
A Python-style slice (only the last key can be a slice)
JSON Key Examples
1 |
key # |
.1 |
key name |
store |
key name |
store.book |
key names |
store.book.2 |
key names w/ index |
store.book.-1.price |
key names /w index |
store.book.:2 |
key name /w slice |
Installation
$ pip install pygments jsoncut
Loading the JSON document
- If the jsonfile argument is:
Left blank it will load the JSON document from STDIN if data is available, otherwise it will print a jsoncut usage message and exit.
A dash character ‘-’, it will load the JSON document from STDIN if data is available otherwise it will wait for the user to input data.
A path/filename, it will load the JSON data from the file
Generated Key Numbers
$ http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -l
1 bbox
2 features
3 metadata
4 metadata.api
5 metadata.count
6 metadata.generated
7 metadata.status
8 metadata.title
9 metadata.url
10 type
Select Root Key
By Key Number
$ http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -lr2
1 geometry
2 geometry.coordinates
3 geometry.type
4 id
5 properties
6 properties.alert
7 properties.cdi
8 properties.code
9 properties.detail
10 properties.dmin
11 properties.felt
12 properties.gap
13 properties.ids
14 properties.mag
15 properties.magType
16 properties.mmi
17 properties.net
18 properties.nst
19 properties.place
20 properties.rms
21 properties.sig
22 properties.sources
23 properties.status
24 properties.time
25 properties.title
26 properties.tsunami
27 properties.type
28 properties.types
29 properties.tz
30 properties.updated
31 properties.url
32 type
Or Key Name
$ http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -lr features
1 geometry
2 geometry.coordinates
3 geometry.type
...
Get Keys
$ http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -r2 -g 2,14,18
[
{
"mag": 1.45,
"nst": 15,
"coordinates": [
-122.7269974,
38.7626648,
2.14
]
},
{
"mag": 0.8,
"nst": null,
"coordinates": [
-152.3008,
61.4323,
9.3
]
},
{
"mag": 1,
"nst": 27,
"coordinates": [
-116.4545,
33.4861667,
17.09
]
},
{
"mag": 0.88,
"nst": 9,
"coordinates": [
-118.8696671,
37.6593323,
1.43
]
},
{
"mag": 1.4,
"nst": null,
"coordinates": [
-147.7345,
63.5458,
0
]
},
{
"mag": 0.92,
"nst": 24,
"coordinates": [
-117.1195,
33.9543333,
13.04
]
}
]
Key Names & Numbers can be Mixed
jsoncut.cli -r features -g 2,14,18,properties.nst
Drop Keys
http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -d features
{
"type": "FeatureCollection",
"metadata": {
"generated": 1485141344000,
"url": "http://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson",
"title": "USGS All Earthquakes, Past Hour",
"status": 200,
"api": "1.5.4",
"count": 7
},
"bbox": [
-150.8798,
33.495,
1.89,
-116.7903333,
62.4321,
78.9
]
}
Key Ranges
$ jsoncut.cli -r2 -g23-26,31-
[
{
"status": "automatic",
"time": 1486089565460,
"title": "M 1.1 - 4km WNW of Cobb, California",
"tsunami": 0,
"url": "http://earthquake.usgs.gov/earthquakes/eventpage/nc72759275",
"type": "Feature"
},
{
"status": "automatic",
"time": 1486088328647,
"title": "M 1.5 - 33km NNE of Anchor Point, Alaska",
"tsunami": 0,
"url": "http://earthquake.usgs.gov/earthquakes/eventpage/ak15193555",
"type": "Feature"
}
]
Inspect JSON document
Let’s say we know the JSON contains a list of earthquakes, but are not sure which of the above keys contains that information. We can use inspect to crawl through the entire JSON document looking for both unique keys and array locations and unique keys. Array indexes are represented by the ‘#’ wildcard character.
$ http earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson|jsoncut -i
bbox :array(count=6)
bbox.# :number(minval=-152.1395, maxval=64.7845)
features :array(count=5)
features.# :object(keys=4)
features.#.geometry :object(keys=2)
features.#.geometry.coordinates :array(count=3)
features.#.geometry.coordinates.# :number(minval=-152.1395, maxval=64.7845)
features.#.geometry.type :text(len=5)
features.#.id :text(len=10)
features.#.properties :object(keys=26)
features.#.properties.alert :null
features.#.properties.cdi :null | number(val=4.1)
features.#.properties.code :text(len=8)
features.#.properties.detail :text(len=74)
features.#.properties.dmin :null | number(minval=0.1081, maxval=0.537)
features.#.properties.felt :null | number(val=48)
features.#.properties.gap :null | number(minval=17, maxval=90.63)
features.#.properties.ids :text(len=12)
features.#.properties.mag :number(minval=1.29, maxval=5.1)
features.#.properties.magType :text(minlen=2, maxlen=3)
features.#.properties.mmi :null
features.#.properties.net :text(len=2)
features.#.properties.nst :null | number(minval=21, maxval=32)
features.#.properties.place :text(minlen=19, maxlen=31)
features.#.properties.rms :number(minval=0.13, maxval=1.39) | null
features.#.properties.sig :number(minval=26, maxval=420)
features.#.properties.sources :text(len=4)
features.#.properties.status :text(minlen=8, maxlen=9)
features.#.properties.time :number(minval=1486083146340, maxval=1486086087592)
features.#.properties.title :text(minlen=27, maxlen=39)
features.#.properties.tsunami :number(val=0)
features.#.properties.type :text(len=10)
features.#.properties.types :text(minlen=17, maxlen=55)
features.#.properties.tz :number(minval=-540, maxval=-180)
features.#.properties.updated :number(minval=1486085163717, maxval=1486086668516)
features.#.properties.url :text(len=59)
features.#.type :text(len=7)
metadata :object(keys=6)
metadata.api :text(len=5)
metadata.count :number(val=5)
metadata.generated :number(val=1486086732000)
metadata.status :number(val=200)
metadata.title :text(len=31)
metadata.url :text(len=73)
type :text(len=17)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.