Skip to main content

A JSON inspection & pruning tool.

Project description


a JSON pruning tool

Python 3 support only; jsoncut is not currently supported under Python 2.

$ jsoncut --help

  Quickly select or filter out properties in a JSON document.

  -r, --root TEXT                 Set the root of the JSON document.
  -g, --get TEXT                  Get JSON object members and/or array
  -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
  -a, --any                       Works with --get & --del; instructs
                                  jsoncut to ignore any key not found
  -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
  -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
  -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 key names key names w/ index key names /w index key name /w slice


$ pip install pygments jsoncut


Pygments is not required by jsoncut, but if installed it can provide syntax highlighting for any JSON written to STDOUT.

Loading the JSON document

If the jsonfile argument is:
  1. Left blank it will load the JSON document from STDIN if data is available, otherwise it will print a jsoncut usage message and exit.
  2. 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.
  3. A path/filename, it will load the JSON data from the file

Generated Key Numbers

$ http|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|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
13 properties.ids
14 properties.mag
15 properties.magType
16 properties.mmi
18 properties.nst
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
30 properties.updated
31 properties.url
32 type

Or Key Name

$ http|jsoncut -lr features
 1 geometry
 2 geometry.coordinates
 3 geometry.type

Get Keys

$ http|jsoncut -r2 -g 2,14,18
    "mag": 1.45,
    "nst": 15,
    "coordinates": [
    "mag": 0.8,
    "nst": null,
    "coordinates": [
    "mag": 1,
    "nst": 27,
    "coordinates": [
    "mag": 0.88,
    "nst": 9,
    "coordinates": [
    "mag": 1.4,
    "nst": null,
    "coordinates": [
    "mag": 0.92,
    "nst": 24,
    "coordinates": [

Key Names & Numbers can be Mixed

jsoncut.cli -r features -g 2,14,18,properties.nst

Drop Keys

http|jsoncut -d features
  "type": "FeatureCollection",
  "metadata": {
    "generated": 1485141344000,
    "url": "",
    "title": "USGS All Earthquakes, Past Hour",
    "status": 200,
    "api": "1.5.4",
    "count": 7
  "bbox": [

Key Ranges

$ jsoncut.cli -r2 -g23-26,31-
    "status": "automatic",
    "time": 1486089565460,
    "title": "M 1.1 - 4km WNW of Cobb, California",
    "tsunami": 0,
    "url": "",
    "type": "Feature"
    "status": "automatic",
    "time": 1486088328647,
    "title": "M 1.5 - 33km NNE of Anchor Point, Alaska",
    "tsunami": 0,
    "url": "",
    "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|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)                     :text(len=10)             :object(keys=26)       :null         :null | number(val=4.1)        :text(len=8)      :text(len=74)        :null | number(minval=0.1081, maxval=0.537)        :null | number(val=48)         :null | number(minval=17, maxval=90.63)         :text(len=12)         :number(minval=1.29, maxval=5.1)     :text(minlen=2, maxlen=3)         :null         :text(len=2)         :null | number(minval=21, maxval=32)       :text(minlen=19, maxlen=31)         :number(minval=0.13, maxval=1.39) | null         :number(minval=26, maxval=420)     :text(len=4)      :text(minlen=8, maxlen=9)        :number(minval=1486083146340, maxval=1486086087592)       :text(minlen=27, maxlen=39)     :number(val=0)        :text(len=10)       :text(minlen=17, maxlen=55)          :number(minval=-540, maxval=-180)     :number(minval=1486085163717, maxval=1486086668516)         :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.

Files for jsoncut, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size jsoncut-0.1.1.tar.gz (16.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page