jq¶

jq is an open source command-line JSON processor with over 126 contributors.

Readme¶

The Readme.md contains information about pipeline status, installation and configuration of jq. Also there are references to their official documentation, such as releases. A link to their StackOverflow and Liberia in case the reader has questions is found at the bottom of the page.

Status¶

The project has not received any updates since the end of May 2022 and the newest release is jq 1.6 which was published in November of 2018.

Founder¶

The original founder of jq is Stephen Dolan. Dolan has a lot of other projects and contributions. His most recent contributions (state: Apr. 2023) have been to the OCaml language system.

Maintainer¶

The AUTHORS file mention Nicolas Williams and William Langford as maintainers.

Hosting¶

JQ is hosted on GitHub. Dolan has his own subdomain, which he uses for hosting the documentation: https://stedolan.github.io/jq/

Homepage¶

There is no real homepage, but there is documentation of the product, that sort of acts like one: https://stedolan.github.io/jq/

Compatibility¶

Jq is compatible with most operating systems. The pipeline is failing for the most recent commits, but the latest release is built for 32- and 64-bit Linux, amd64 Mac OS and 32- and 64-bit Windows. There is no notice about ARM compatibility. But since is a “compile-ios.sh” script in the gits root directory which contains the following lines:

for arch in i386 x86_64 armv7 armv7s arm64; do
    ...
done

This implies, that arm compatibility is given.

License¶

Jq itself does not have a named license, but given the articulation it conforms to the MIT License with Stephen Dolan himself in the Copyright notice. The documentation (everything under doc/) is licensed under Creative Commons CC BY 3.0.

Parts of jq are licensed differently:

dtoa.c
- Copyright © 1991, 2000, 2001 by Lucent Technologies
- Author David M. Gay
- License Unknown
g_fmt.c
- Copyright © 1991, 1996 by Lucent Technologies (David M. Gay)
- Author David M. Gay
- License Unknown
decNumber
- Copyright © 1995-2005 International Business Machines Corporation and others
- License Unknown

UI¶

Jq does not have a UI per se, since it is a commandline tool, like grep, sed or tee.

Origin¶

Over a decade ago, jq has been started. The origin of jq begins on Wed Jul 18 20:57:59 2012 with the initial commit (eca89acee00faf6e9ef55d84780e6eeddf225e5c).

Programming Languages¶

Most of jq has been written in C (93.5%). It also has some M4 (2.3%), Yacc (1.3%), Shell (1.0%) and jq (0.9%). There are also Makefiles and other smaller files, which combined make up 0.5%.

Configuration¶

The project is built with GNU Make:

autoreconf -fi              # if building from git
./configure --with-oniguruma=builtin
make -j8
make check

Development Environment¶

There are no IDEs needed to develop within the project. Vim/Neovim or nano are more than enough to write sourcecode here.

Documentation¶

Documentation of jq is build in Python. The templating engine jinja2, such as markdown and yaml modules are used to build a website from the documentation source files.

Users¶

Jq has lots of users distributed among the world. There is no way of telling how many exactly, but the size of the project implies, that it may be at least hundreds of thousands of users. 24.7 thousand people alone have starred the project on GitHub.

Forks¶

Jq has been forked by 1.4 thousand people with the most starred one being jq’s maintainers version.

Even though the project is very popular and often forked, the most starred fork only has eight stars and most of them have none at all.

Contributing¶

To contribute to jq, you have to clone the project and hand in an issue. You can either create an issue or use an existing one. Usually, you will find a bug or a feature request already in the issues, so creating a new one is hardly wanted. Next, you create a branch for your project on which you will develop. You can create a pull request with your changes in this issue and communicate with the maintainers what you have to change in order to have your commits merged.

The project has over 681 issues and 131 pull requests, so it might be a little optimistic to think that the request will eventually be merged.

Git Workflow¶

The project currently has 17 branches. Each branch is a short description of the bug or feature that is being implemented/fixed.

Bugs usually start with bugfix/ and releases are also kept in a seperate branch. The default branch in jq is master. There is no stable or next branch.

Installation¶

Installing and compiling jq from source can easily be done on the commandline:

# Compiling
git submodule update --init # if building from git to get oniguruma
autoreconf -fi              # if building from git
./configure --with-oniguruma=builtin
make -j8
make check

# Installation
sudo make install

There are also guides for Windows and MacOS, for which a cross-compilation environment is needed. If the workspace is clean, these commands can build the binaries:

# git clean ...
autoreconf -i
./configure
make distclean
scripts/crosscompile <name-of-build> <configure-options>

There is an entire section on the wiki where cross compilation is being explained.

Language¶

The notices and alerts that the programm is giving are in english. There are no other man-pages other than that.

Example¶

Usage: jq [OPTIONS] <JQ FILTER> [FILES]

An example of how jq can be of use is demonstrated here using a simple example.

In this example, the user wants to subscribe to an mqtt broker, but the payload from the topic “telemetry/livingroom/dht11” is returned as a json string:

mosquitto_sub -t telemetry/livingroom/dht11
# {"humidity":45.15715789794922,"temperature_c":20.44152069091797,"temperature_f":68.79473876953125,"timestamp":1681303320640}

To better read the message, the user can use jq:

mosquitto_sub -t telemetry/livingroom/dht11
# {
#   "humidity": 45.15715789794922,
#   "temperature_c": 20.44152069091797,
#   "temperature_f": 68.79473876953125,
#   "timestamp": 1681303320640
# }

There is also the possibility, that the user wants to quickly see if a certain element is present in a json file.

jq ".[]|select(.Name==\"Marge Simpson\")" simpsons.json

{
  "Name": "Marge Simpson",
  "Alter": 34,
  "Kinder": [
    "Bart",
    "Lisa",
    "Maggie"
  ],
  "Jobs": [
    "Hausfrau",
    "KKW Angestellte",
    "Polizistin",
    "Telefonseelsorgerin"
  ],
  "Hobbies": [
    "Malen",
    "Zeichnen"
  ]
}

This example is from wiki.ubuntuusers.de and there are many more usages of jq.