https://github.com/joshbuddy/jsonpath

Ruby implementation of http://goessner.net/articles/JsonPath/
https://github.com/joshbuddy/jsonpath

Keywords from Contributors

rubygems rack sinatra grape activejob activerecord mvc authorization oauth feature-flag

Last synced: about 9 hours ago
JSON representation

Repository metadata

Ruby implementation of http://goessner.net/articles/JsonPath/

Host: GitHub
URL: https://github.com/joshbuddy/jsonpath
Owner: joshbuddy
License: mit
Created: 2008-12-13T18:44:34.000Z (about 17 years ago)
Default Branch: master
Last Pushed: 2024-02-02T15:02:19.000Z (about 2 years ago)
Last Synced: 2026-02-16T12:36:54.054Z (15 days ago)
Language: Ruby
Homepage:
Size: 288 KB
Stars: 455
Watchers: 8
Forks: 76
Open Issues: 25
Releases: 8
Metadata Files:
- Readme: README.md
- License: LICENSE.md

JsonPath

This is an implementation of http://goessner.net/articles/JsonPath/.

What is JsonPath?

JsonPath is a way of addressing elements within a JSON object. Similar to xpath
of yore, JsonPath lets you traverse a json object and manipulate or access it.

Usage

Command-line

There is stand-alone usage through the binary jsonpath

jsonpath [expression] (file|string)

If you omit the second argument, it will read stdin, assuming one valid JSON
object per line. Expression must be a valid jsonpath expression.

Library

To use JsonPath as a library simply include and get goin'!

require 'jsonpath'

json = <<-HERE_DOC
{"store":
  {"bicycle":
    {"price":19.95, "color":"red"},
    "book":[
      {"price":8.95, "category":"reference", "title":"Sayings of the Century", "author":"Nigel Rees"},
      {"price":12.99, "category":"fiction", "title":"Sword of Honour", "author":"Evelyn Waugh"},
      {"price":8.99, "category":"fiction", "isbn":"0-553-21311-3", "title":"Moby Dick", "author":"Herman Melville","color":"blue"},
      {"price":22.99, "category":"fiction", "isbn":"0-395-19395-8", "title":"The Lord of the Rings", "author":"Tolkien"}
    ]
  }
}
HERE_DOC

Now that we have a JSON object, let's get all the prices present in the object.
We create an object for the path in the following way.

path = JsonPath.new('$..price')

Now that we have a path, let's apply it to the object above.

path.on(json)
# => [19.95, 8.95, 12.99, 8.99, 22.99]

Or reuse it later on some other object (thread safe) ...

path.on('{"books":[{"title":"A Tale of Two Somethings","price":18.88}]}')
# => [18.88]

You can also just combine this into one mega-call with the convenient
JsonPath.on method.

JsonPath.on(json, '$..author')
# => ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "Tolkien"]

Of course the full JsonPath syntax is supported, such as array slices

JsonPath.new('$..book[::2]').on(json)
# => [
#      {"price" => 8.95, "category" => "reference", "title" => "Sayings of the Century", "author" => "Nigel Rees"},
#      {"price" => 8.99, "category" => "fiction", "isbn" => "0-553-21311-3", "title" => "Moby Dick", "author" => "Herman Melville","color" => "blue"},
#    ]

...and evals, including those with conditional operators

JsonPath.new("$..price[?(@ < 10)]").on(json)
# => [8.95, 8.99]

JsonPath.new("$..book[?(@['price'] == 8.95 || @['price'] == 8.99)].title").on(json)
# => ["Sayings of the Century", "Moby Dick"]

JsonPath.new("$..book[?(@['price'] == 8.95 && @['price'] == 8.99)].title").on(json)
# => []

There is a convenience method, #first that gives you the first element for a
JSON object and path.

JsonPath.new('$..color').first(json)
# => "red"

As well, we can directly create an Enumerable at any time using #[].

enum = JsonPath.new('$..color')[json]
# => #<JsonPath::Enumerable:...>
enum.first
# => "red"
enum.any?{ |c| c == 'red' }
# => true

For more usage examples and variations on paths, please visit the tests. There
are some more complex ones as well.

Querying ruby data structures

If you have ruby hashes with symbolized keys as input, you
can use :use_symbols to make JsonPath work fine on them too:

book = { title: "Sayings of the Century" }

JsonPath.new('$.title').on(book)
# => []

JsonPath.new('$.title', use_symbols: true).on(book)
# => ["Sayings of the Century"]

JsonPath also recognizes objects responding to dig (introduced
in ruby 2.3), and therefore works out of the box with Struct,
OpenStruct, and other Hash-like structures:

book_class = Struct.new(:title)
book = book_class.new("Sayings of the Century")

JsonPath.new('$.title').on(book)
# => ["Sayings of the Century"]

JsonPath is able to query pure ruby objects and uses __send__
on them. The option is enabled by default in JsonPath 1.x, but
we encourage to enable it explicitly:

book_class = Class.new{ attr_accessor :title }
book = book_class.new
book.title = "Sayings of the Century"

JsonPath.new('$.title', allow_send: true).on(book)
# => ["Sayings of the Century"]

Other available options

By default, JsonPath does not return null values on unexisting paths.
This can be changed using the :default_path_leaf_to_null option

JsonPath.new('$..book[*].isbn').on(json)
# => ["0-553-21311-3", "0-395-19395-8"]

JsonPath.new('$..book[*].isbn', default_path_leaf_to_null: true).on(json)
# => [nil, nil, "0-553-21311-3", "0-395-19395-8"]

When JsonPath returns a Hash, you can ask to symbolize its keys
using the :symbolize_keys option

JsonPath.new('$..book[0]').on(json)
# => [{"category" => "reference", ...}]

JsonPath.new('$..book[0]', symbolize_keys: true).on(json)
# => [{category: "reference", ...}]

Selecting Values

It's possible to select results once a query has been defined after the query. For
example given this JSON data:

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            }
        ]
}

... and this query:

"$.store.book[*](category,author)"

... the result can be filtered as such:

[
   {
      "category" : "reference",
      "author" : "Nigel Rees"
   },
   {
      "category" : "fiction",
      "author" : "Evelyn Waugh"
   }
]

Manipulation

If you'd like to do substitution in a json object, you can use #gsub
or #gsub! to modify the object in place.

JsonPath.for('{"candy":"lollipop"}').gsub('$..candy') {|v| "big turks" }.to_hash

The result will be

{'candy' => 'big turks'}

If you'd like to remove all nil keys, you can use #compact and #compact!.
To remove all keys under a certain path, use #delete or #delete!. You can
even chain these methods together as follows:

json = '{"candy":"lollipop","noncandy":null,"other":"things"}'
o = JsonPath.for(json).
  gsub('$..candy') {|v| "big turks" }.
  compact.
  delete('$..other').
  to_hash
# => {"candy" => "big turks"}

Fetch all paths

To fetch all possible paths in given json, you can use `fetch_all_path`` method.

data:

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees"
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh"
            }
        ]
}

... and this query:

JsonPath.fetch_all_path(data)

... the result will be:

["$", "$.store", "$.store.book", "$.store.book[0].category", "$.store.book[0].author", "$.store.book[0]", "$.store.book[1].category", "$.store.book[1].author", "$.store.book[1]"]

Contributions

Please feel free to submit an Issue or a Pull Request any time you feel like
you would like to contribute. Thank you!

Running an individual test

ruby -Ilib:../lib test/test_jsonpath.rb --name test_wildcard_on_intermediary_element_v6

Owner metadata

Name: Joshua Hull
Login: joshbuddy
Email:
Kind: user
Description:
Website:
Location: Copenhagen, DK
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/8898?v=4
Repositories: 220
Last ynced at: 2023-04-10T07:28:02.472Z
Profile URL: https://github.com/joshbuddy

GitHub Events

Total

Pull request event: 5
Fork event: 7
Issues event: 6
Watch event: 8
Issue comment event: 6

Last Year

Pull request event: 3
Fork event: 3
Issues event: 4
Watch event: 3
Issue comment event: 5

Committers metadata

Last synced: 3 days ago

Total Commits: 205
Total Committers: 43
Avg Commits per committer: 4.767
Development Distribution Score (DDS): 0.746

Commits in past year: 0
Committers in past year: 0
Avg Commits per committer in past year: 0.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
Joshua Hull	j**y@g**m	52
Gergely Brautigam	s**7@g**m	47
Josh Hull	j**y@t**m	20
mohanapriya2308	5****8	14
Steve Agalloco	s**o@g**m	8
Alexander.Iljushkin	A**n@b**u	6
Anupama Kumari	a**i@f**m	5
Josh Hull	j**l@l**m	4
Gergely Brautigam	g**m@a**m	3
Fraser Hanson	f**n@n**m	3
Markus Doits	d****s	3
Michael Grosser	m**l@g**t	3
Dan Chetlin	d**n@g**m	2
Gergely Brautigam	g**y@a**m	2
Michael Kruglos	m**s@t**m	2
BK	bk@r****o	2
James Goodwin	j**n@g**m	2
Mohana	m**y@f**m	2
yangdong	d**g@g**m	1
liufengyun	l**a@g**m	1
anu radha	4****8	1
a5-stable	s**6@g**m	1
ShepFC3	c**d@g**m	1
Patrick Sinclair	m**e@g**m	1
Oliver Searle-Barnes	o**r@o**k	1
Benjamin Vetter	v**r@p**e	1
Karol Kozakowski	k**i@e**l	1
Peter Williams	p**s@c**m	1
anton-hrynevich	a**h@o**m	1
Michael Kruglos	m**l@k**m	1
and 13 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 24 days ago

Total issues: 51
Total pull requests: 74
Average time to close issues: 3 months
Average time to close pull requests: 13 days
Total issue authors: 45
Total pull request authors: 27
Average comments per issue: 4.69
Average comments per pull request: 1.51
Merged pull request: 50
Bot issues: 0
Bot pull requests: 0

Past year issues: 5
Past year pull requests: 7
Past year average time to close issues: 4 days
Past year average time to close pull requests: N/A
Past year issue authors: 5
Past year pull request authors: 5
Past year average comments per issue: 0.4
Past year average comments per pull request: 0.14
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/joshbuddy/jsonpath

Top Issue Authors

NDuggan (4)
gongfarmer (3)
cburgmer (2)
khairihafsham (1)
dblock (1)
sebastiandeutsch (1)
johnallen3d (1)
nak1114 (1)
incubus (1)
melsawy (1)
narendranvelmurugan (1)
fadhlimaulidri (1)
marciondg (1)
deivinsontejeda (1)
SteveDonie (1)

Top Pull Request Authors

Skarlso (27)
doits (5)
grosser (4)
anupama-kumari (3)
joshbuddy (3)
jgoodw1n (2)
nak1114 (2)
mohanapriya2308 (2)
blambeau (2)
gogainda (2)
gongfarmer (2)
wynksaiddestroy (2)
pranjal-wego (2)
boutil (2)
notEthan (2)

Top Issue Labels

feature-request (6)
answered (6)
bug (4)
needs more info (4)
question (3)
stale (2)
Hacktoberfest (1)

Top Pull Request Labels

bug (2)
enhancement (1)

Package metadata

Total packages: 12
Total downloads:
- rubygems: 175,389,120 total
Total docker downloads: 2,930,213,878
Total dependent packages: 101 (may contain duplicates)
Total dependent repositories: 1,427 (may contain duplicates)
Total versions: 171
Total maintainers: 2

gem.coop: jsonpath

Ruby implementation of http://goessner.net/articles/JsonPath/.

Homepage: https://github.com/joshbuddy/jsonpath
Documentation: http://www.rubydoc.info/gems/jsonpath/
Licenses: MIT
Latest release: 1.1.5 (published over 2 years ago)
Last Synced: 2026-03-02T05:32:06.653Z (1 day ago)
Versions: 61
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 87,700,703 Total
Docker Downloads: 1,465,106,939
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Docker downloads count: 0.066%
- Average: 0.097%
- Downloads: 0.321%
Maintainers (2)
- joshbuddy
- skarlso

rubygems.org: jsonpath