jackson-jq

Pure Java jq Implementation for Jackson JSON Processor

Usage

First, you need Java 8 or later.

If you use Maven, add the following snippet to the <dependencies> section of your POM. For instructions for other build tools (Gradle, etc.), visit jackson-jq on search.maven.org.

<dependency>
    <groupId>net.thisptr</groupId>
    <artifactId>jackson-jq</artifactId>
    <version>1.6.2</version>
</dependency>

See jackson-jq/src/test/java/examples/Usage.java for the API usage.

Using a jackson-jq command line tool

To test a query quickly, we provide jackson-jq CLI.

Please note that jackson-jq is a Java library and the CLI is provided solely for debugging/testing purpose (and not for production). The command-line options might change without notice.

$ curl -LO https://repo1.maven.org/maven2/net/thisptr/jackson-jq-cli/1.6.2/jackson-jq-cli-1.6.2.jar

$ java -jar jackson-jq-cli-1.6.2.jar --help
usage: jackson-jq [OPTIONS...] QUERY
 -c,--compact      compact instead of pretty-printed output
 -h,--help         print this message
    --jq <arg>     specify jq version
 -n,--null-input   use `null` as the single input value
 -r,--raw          output raw strings, not JSON texts

$ java -jar jackson-jq-cli-1.6.2.jar '.foo'
{"foo": 42}
42

To test a query with a specific jq version,

$ java -jar jackson-jq-cli-1.6.2.jar --jq 1.5 'join("-")'
["1", 2]
jq: error: string ("-") and number (2) cannot be added

$ java -jar jackson-jq-cli-1.6.2.jar --jq 1.6 'join("-")' # jq-1.6 can join any values, not only strings
["1", 2]
"1-2"

Homebrew (or Linuxbrew) users can alternatively run brew tap eiiches/jackson-jq && brew install jackson-jq to install the CLI. jackson-jq will be available on your $PATH.

Branches and versioning

There are currently two development branches.

• develop/1.x: This branch (you are viewing), which is currently under development for the future 1.0 release. You can find preview releases at Releases page (tags: 1.0.0-preview.yyyyMMdd). Although the API is not stable yet, I recommend new users to use these releases insetad of 0.x versions, because these releases have more features, better compatibility, and better performance.
• develop/0.x: The development branch for 0.x versions. Features that need breaking API changes will no longer be added. Go to Releases and find the latest 0.x.y version.

PRs can be sent to any of the develop/* branches. The patch will be ported to the other branch(es) if necessary.

We use Semantic Versioning 2.0.0 for Java API versioning, 1.0.0 onwards. A jq behavior fix (even if it may possibly affect users) will not be considered a major change if the fix is to make the bahavior compatible with ./jq; these kind of incompatible changes are documented in the release note.

If you get different results between ./jq and jackson-jq, please file an issue. That is a bug on jackson-jq side.

Implementation Status

jackson-jq aims to be a compatible jq implementation. However, not every feature is available; some are intentionally omitted because thay are not relevant as a Java library; some may be incomplete, have bugs or are yet to be implemented.

List of Features

Click to see the list

This table illustrates which features (picked from jq-1.5 manual) are supported and which are not in jackson-jq. We try to keep this list accurate and up to date. If you find something is missing or wrong, please file an issue.