Every format with its parser

In this Teratip scenario, we are in a GNU/Linux console environment, which could be inside a Jenkinsfile for example, and we need a JSON object. A very common situation.

Over many years we have seen things like:

echo '{"channel":"main","text":"Hello %%USER%%"}' > message.json

With also very complex to read sed structures to fill placeholders.

Or even run a sh script in a jenkinsfile that calls python code to be able to use the python library to create the JSON and later send it back to sh which sends it back to Jenkins. Crazy, right?

But we have jq. In the beginning, you might think it is difficult to learn but if you type man jq, you will find many examples describing multiple and very useful situations.

Let's take a look at the following example. In this case we will use jq to create a JSON object filling up some placeholders and make a Slack API call request with it.

data=$( jq -n \
  --arg SLACK_CHANNEL "${SLACK_CHANNEL}" \
  --arg text "Hello ${USER}." \
  '{channel:$SLACK_CHANNEL,text:$text}' )

curl -X POST \
  -H "Authorization: Bearer $SLACK_AUTHORIZATION" \
  -H 'Content-type: application/json; charset=utf-8' \
  --data "$data" \
  https://slack.com/api/chat.postMessage

Explanation:

The -n parameter in jq allows you to create a new object from scratch without taking any input to parse.

The --arg parameter creates a variable named as the first argument inside the structure and fills it with whatever you write as the second argument. As you can see, placeholders are OK. No need to escape anything here.

The last parameter is the JSON template. Pay special attention to where the dollar sign needs to be placed. Could be mischievous at first sight.

Since all of this runs in a $() subshell, the output will be stored in the data variable.

Now you can use it with your curl by just calling --data "$data"

Time to play with jq now! Let us know how you used to create your JSON objects in the past before this Teratip showed you how to do it properly.