jmespath.js is a javascript implementation of JMESPath, which is a query language for JSON. It will take a JSON document and transform it into another JSON document through a JMESPath expression.
Using jmespath.js is really easy. There's a single function
you use, jmespath.search
:
> var jmespath = require('jmespath');
> jmespath.search({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, "foo.bar.baz[2]")
2
In the example we gave the search
function input data of
{foo: {bar: {baz: [0, 1, 2, 3, 4]}}}
as well as the JMESPath
expression foo.bar.baz[2]
, and the search
function evaluated
the expression against the input data to produce the result 2
.
The JMESPath language can do a lot more than select an element from a list. Here are a few more examples:
> jmespath.search({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, "foo.bar")
{ baz: [ 0, 1, 2, 3, 4 ] }
> jmespath.search({"foo": [{"first": "a", "last": "b"},
{"first": "c", "last": "d"}]},
"foo[*].first")
[ 'a', 'c' ]
> jmespath.search({"foo": [{"age": 20}, {"age": 25},
{"age": 30}, {"age": 35},
{"age": 40}]},
"foo[?age > `30`]")
[ { age: 35 }, { age: 40 } ]
The example above only show a small amount of what a JMESPath expression can do. If you want to take a tour of the language, the best place to go is the JMESPath Tutorial.
One of the best things about JMESPath is that it is implemented in many different programming languages including python, ruby, php, lua, etc. To see a complete list of libraries, check out the JMESPath libraries page.
And finally, the full JMESPath specification can be found on the JMESPath site.
As an extension to common JMESPath API and available in jmespath.js only,
custom filter functions can be specified through the functionTable
property of the optional third argument of the search
function.
The custom functions can even call third-party
libraries via closure. The following example shows how a custom
filter function contains_ci
is implemented with
lodash
library
to provide case insensitive string matching
const jmespath = require('jmespath')
const assert = require('assert')
const _ = require('lodash')
let res = jmespath.search([{ a: 'foo' }], "[?contains_ci(a, 'FOO')]", {
functionTable: {
/*jshint camelcase: false */
contains_ci: {
_func: function(resolvedArgs) {
if (!resolvedArgs[0] || !resolvedArgs[1]) {
return false
}
return (
_.toLower(resolvedArgs[0]).indexOf(_.toLower(resolvedArgs[1])) >= 0
)
},
_signature: [
{
types: [2]
},
{
types: [2]
}
]
}
}
})
assert.deepStrictEqual(res, [{ a: 'foo' }])
See type constants for type mapping used by the example.