JSON v Bash pomocí jq — průvodce

Když deploy skript začne zpracovávat API odpovědi nebo validovat konfigurační soubory v CI, znalost toho, jak formátovat JSON v bash, se stane rychle nezbytnou. Dva nástroje, které pokrývají 99 % reálných případů, jsou jq a python3 -m json.tool — oba dokáží spolehlivě zpracovat JSON bash pipeline, validovat s kódy ukončení a čistě integrovat do CI/CD workflow. Pro jednorázovou inspekci bez terminálu to prohlížečový JSON Formatter zvládne okamžitě. Tato příručka pokrývá instalaci jq, formátování z pipe a souborů, validační funkce, integraci CI/CD v GitHub Actions, pre-commit hooks, vzory heredoc a kdy sáhnout po záložním řešení Python stdlib.

Co je formátování JSON v Bash?

Formátování JSON v bash znamená transformaci kompaktního, minifikovaného JSON na odsazený, čitelný výstup. Podkladová data jsou nezměněná — liší se pouze mezery a zalomení řádků. V kontextu skriptování to záleží ze dvou důvodů: čitelnost při ladění a validace, když formátovač jako vedlejší efekt kontroluje syntaxi. Nástroje jako jq plně zparsují JSON před jeho přeformátováním, což znamená, že úspěšné spuštění formátování je zároveň implicitní kontrolou platnosti. Toto duální chování — formátovat a validovat v jednom kroku — je to, co dělá jq tak užitečným v automatizovaných pipeline.

{"service":"payments-api","version":"2.4.1","database":{"host":"db-prod-01.internal","port":5432,"pool_size":20},"cache":{"enabled":true,"ttl":300}}

{
  "service": "payments-api",
  "version": "2.4.1",
  "database": {
    "host": "db-prod-01.internal",
    "port": 5432,
    "pool_size": 20
  },
  "cache": {
    "enabled": true,
    "ttl": 300
  }
}

jq — Formátování JSON v Bash

jq je de facto standard pro zpracování JSON v shell skriptech (jq 1.6+, bash 4+). Je to účelově postavený příkazový řádkový JSON procesor, který umí formátovat, filtrovat, transformovat a validovat JSON. Filtr identity . prochází vstup nezměněný, ale naformátovaný. Když jq nemůže zparsovat vstup, ukončí se s kódem 1 — to je to, co jej dělá ideálním pro skriptování: formátování a validace jsou jedna operace.

Instalace jq

# macOS
brew install jq

# Debian / Ubuntu
apt-get install -y jq

# Fedora / RHEL / CentOS
dnf install jq

# Alpine (Docker obrazy)
apk add --no-cache jq

# Ověření
jq --version  # jq-1.7.1

Formátování ze stdin a ze souboru

# Přesměrování inline JSON přes jq
echo '{"host":"db-prod-01.internal","port":5432}' | jq .

# Přímé formátování souboru (výpis na stdout)
jq . config/feature-flags.json

# Formátování se 4-mezerovým odsazením
jq --indent 4 . config/feature-flags.json

# Formátování pomocí tabulátorů místo mezer
jq --tab . config/feature-flags.json

Zápis formátovaného výstupu do souboru

# Uložit formátovaný výstup (NEPŘESMĚROVÁVEJTE zpět do stejného souboru)
jq . compact.json > formatted.json

# Kompaktní (minifikovat) — opak formátování
jq -c . formatted.json

Řazení klíčů a odebrání barev

# Seřadit všechny klíče abecedně (užitečné pro deterministické diff)
jq --sort-keys . config/app-config.json

# Zakázat barevný výstup při zápisu do log souboru
jq --monochrome-output . response.json >> deploy.log

Přehled voleb jq

Nejčastěji používané jq příznaky pro formátování a validační workflow:

Validace JSON v Bash skriptu

Validace a formátování jsou v jq stejná operace — parsuje před výpisem. Přesměrujte stdout na /dev/null pokud chcete pouze kód ukončení bez formátovaného výstupu. Níže uvedený vzor je opakovaně použitelný v deploy skriptech, pre-commit hooks a CI pipeline. Při řešení incidentů je první věc, kterou dělám s neznámým API payloadem, přesměrování přes jq — promění zeď minifikovaného JSON v něco, co mohu skutečně číst a ladit.

Znovupoužitelná validační funkce

validate_json() {
  local file="$1"
  if jq . "$file" > /dev/null 2>&1; then
    echo "✓ Platný JSON: $file"
    return 0
  else
    echo "✗ Neplatný JSON: $file" >&2
    return 1
  fi
}

Přerušení deploye při neplatné konfiguraci

CONFIG="infra/k8s/app-config.json"
validate_json "$CONFIG" || { echo "Přerušení deploye: neplatná konfigurace" >&2; exit 1; }

Validace všech JSON souborů v adresáři

find ./config -name "*.json" | while read -r f; do
  jq . "$f" > /dev/null 2>&1 || echo "NEPLATNÝ: $f"
done

Formátování JSON ze souborů a API odpovědí

Dva běžné zdroje JSON v shell skriptech jsou soubory na disku a HTTP API odpovědi přes curl. Každý má mírně odlišný vzor zpracování. U souborů je hlavní starostí bezpečná přímá editace. U API odpovědí je klíčovým detailem potlačení ukazatele průběhu curl, aby nenarušil vstup jq.

Bezpečné přímé formátování souboru

# Bezpečné formátování a přepsání pomocí dočasného souboru
tmp=$(mktemp)
jq --indent 2 . config/feature-flags.json > "$tmp" && mv "$tmp" config/feature-flags.json
echo "config/feature-flags.json naformátován"

Formátování odpovědi curl API

# Formátování stavu deploye z API
DEPLOY_ID="dep_8f3a2b9c"
curl -s \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  "https://api.deployments.internal/v1/deploys/$DEPLOY_ID" \
  | jq --indent 2 .

Simultánní formátování a filtrování

# Formátovaně + filtrovat pouze chyby z monitorovacího endpointu
curl -s "https://monitoring.internal/api/events?level=error&limit=10" \
  | jq '[.events[] | {id, message, timestamp, service}]' \
  || { echo "Nepodařilo se načíst nebo zparsovat události" >&2; exit 1; }

Vzor || { ... } je zde kritický. Bez něj selhaný curl nebo deformovaná API odpověď tiše prochází a další krok v skriptu pracuje s prázdnými nebo neúplnými daty. Pokud je potřeba prozkoumat komplexní vnořené odpovědi bez psaní výrazu filtru, prohlížečový JSON Formatter umožní vložit surovou odpověď a interaktivně procházet strom.

Formátování JSON v CI/CD pipeline

CI je místo, kde nejvíce záleží na JSON validačních branách — deformovaná konfigurace, která se dostane do produkce, je mnohem bolestivější na rollback než selhání pipeline. Níže uvedené vzory jsou ty, které používám v produkčních SRE workflow pro zachycení chyb konfigurace dříve, než se vůbec dostanou do deployment slotu.

GitHub Actions — validace všech JSON konfigurací

- name: Validace JSON konfigurací
  run: |
    echo "Validuji JSON konfigurační soubory..."
    find . -name "*.json" -not -path "*/node_modules/*" | while read -r f; do
      if ! jq . "$f" > /dev/null 2>&1; then
        echo "::error file=$f::Neplatná JSON syntaxe"
        exit 1
      fi
    done
    echo "Všechny JSON soubory jsou platné"

Pre-commit hook — validace staged JSON souborů

#!/usr/bin/env bash
set -euo pipefail
STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep '\.json$' || true)
[ -z "$STAGED" ] && exit 0
for f in $STAGED; do
  jq . "$f" > /dev/null 2>&1 || { echo "Neplatný JSON: $f"; exit 1; }
done
echo "JSON validace prošla"

Formátování JSON proměnných a Heredocs v Bash

Shell skripty často dynamicky sestavují JSON payloady — z proměnných prostředí, git metadat nebo vypočtených hodnot. Nejbezpečnějším vzorem je jq -n --arg / --argjson namísto interpolace řetězců, která se rozbije ve chvíli, kdy hodnota obsahuje uvozovku nebo zalomení řádku. Při předávání do jq vždy použijte dvojité uvozovky kolem proměnných, aby se zabránilo word-splittingu na mezerách v JSON.

Formátování uložené proměnné API odpovědi

# Vždy citujte "$API_RESPONSE" — mezery v JSON by rozbily necitovanou expanzi
echo "$API_RESPONSE" | jq --indent 2 .

Sestavení a formátování payloadu pomocí jq -n

payload=$(jq -n \
  --arg env "production" \
  --arg version "$(git describe --tags)" \
  --argjson replicas 3 \
  '{environment: $env, version: $version, replicas: $replicas}')

# Prohlédnout sestavený payload
echo "$payload" | jq .

# Odeslat na API
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  -d "$payload" \
  "https://api.deployments.internal/v1/deploys"

Formátování JSON v Bash bez instalace jq

Když jq není dostupné — minimální Docker obrazy, zamčené CI runnery nebo systémy, kde nelze instalovat balíčky — vestavěný modul json.tool Pythonu poskytuje stejnou základní funkcionalitu. Je součástí standardní knihovny Pythonu; pokud je nainstalován Python 3, funguje bez dalších závislostí.

# Formátování ze souboru
python3 -m json.tool config.json

# Nastavení šířky odsazení
python3 -m json.tool --indent 2 config.json

# Řazení klíčů abecedně
python3 -m json.tool --sort-keys config.json

# Formátování ze stdin (např. přesměrováno z curl)
curl -s https://api.deployments.internal/v1/status | python3 -m json.tool

# Validace s kódem ukončení (stejná sémantika jako jq)
python3 -m json.tool config.json > /dev/null && echo "platný" || echo "neplatný"

# Validace inline řetězce
echo '{"service":"payments-api","healthy":true}' | python3 -m json.tool > /dev/null
echo "Kód ukončení: $?"  # 0 = platný

Výstup terminálu se zvýrazněním syntaxe

jq barví svůj výstup ve výchozím nastavení — klíče modře, řetězce zeleně, čísla bíle. Když je potřeba plné zvýraznění syntaxe JSON v scrollovatelném pageru nebo při ladění velkých vnořených odpovědí v terminálové relaci, bat poskytuje nejergonomičtější zážitek. Oba jsou užitečné pro ladění a interaktivní inspekci; ani jeden by neměl být použit při zápisu výstupu do souborů nebo API odpovědí.

Instalace bat

# macOS
brew install bat

# Debian / Ubuntu (binární soubor může být pojmenován batcat — případně vytvořte alias)
apt-get install -y bat
# alias bat=batcat   # přidejte do ~/.bashrc pokud je potřeba

# Ověření
bat --version  # bat 0.24.0

Prohlížení JSON souborů se zvýrazněním syntaxe

# JSON se zvýrazněnou syntaxí v pageru (stiskněte q pro ukončení)
bat config/app-config.json

# Zakázat stránkování — výpis přímo do terminálu
bat --paging=never config/app-config.json

# Přesměrování výstupu jq přes bat pro barevnou inspekci
jq '.database' infra/app-config.json | bat --language=json --paging=never

Barevný výstup jq ve scrollovatelném pageru

# -C vynucuje barvy i když stdout není tty (např. při přesměrování do less)
jq -C . logs/deploy-response.json | less -R

Práce s velkými JSON soubory v Bash

Když JSON soubor překročí 50–100 MB, načítání do paměti ve výchozím režimu jq může být pomalé nebo způsobit OOM na hostitelích s omezenou pamětí (Docker kontejnery s limitem 512 MB, například). jq --stream inkrementálně vydává páry cesta/hodnota při čtení, bez bufferování celého dokumentu. Pro NDJSON (jeden JSON objekt na řádek) má jq efektivnější nativní přístup.

Streamování velkého JSON souboru pomocí jq --stream

# --stream vydává páry [cesta, skalár] při čtení vstupu jq
# Extrahovat všechna pole "status" z velkého log archivu bez jeho úplného načtení
jq -c --stream   'if length == 2 and (.[0][-1] == "status") then .[1] else empty end'   logs/archive-2026-03.json

NDJSON / JSON Lines — zpracování jednoho objektu na řádek

# NDJSON: jeden JSON objekt na řádek — běžné v exportech Kafka, Fluentd a Logstash
# -R čte surové řádky; fromjson? přeskakuje řádky, které nejsou platný JSON
jq -c -R 'fromjson? | {id: .request_id, status: .http_status, latency: .duration_ms}'   logs/access-2026-03-13.ndjson > logs/summary.ndjson

# Alternativa pomocí shell smyčky — užitečné když je potřeba zpracování chyb po řádcích
while IFS= read -r line; do
  echo "$line" | jq -c '{id: .request_id, status: .http_status}' 2>/dev/null ||     echo "PŘESKOČENO: deformovaný řádek" >&2
done < logs/access-2026-03-13.ndjson

Časté Chyby

jq --indent 2 . settings.json > settings.json

tmp=$(mktemp) && jq --indent 2 . settings.json > "$tmp" && mv "$tmp" settings.json

jq . response.json > formatted.json

jq . response.json > formatted.json || { echo "Neplatný JSON v response.json" >&2; exit 1; }

curl https://api.payments.internal/config | jq .

curl -s https://api.payments.internal/config | jq .

jq -r . config.json

jq . config.json

jq vs python3 vs json_pp — Rychlé Srovnání

Volba mezi nástroji závisí na tom, co je k dispozici ve vašem prostředí a co potřebujete nad rámec základního formátování:

Pro většinu bash skriptování a CI/CD práce je jq správnou výchozí volbou — validuje, formátuje, filtruje a poskytuje spolehlivé kódy ukončení v jediném binárním souboru bez runtime závislosti. Vraťte se k python3 -m json.tool když nelze nainstalovat další balíčky a Python je již přítomen.

Často Kladené Dotazy

tmp=$(mktemp)
jq --indent 2 . config/app-config.json > "$tmp" && mv "$tmp" config/app-config.json
echo "Úspěšně formátováno přímo"

validate_json() {
  local file="$1"
  if jq . "$file" > /dev/null 2>&1; then
    echo "✓ Platný JSON: $file"
    return 0
  else
    echo "✗ Neplatný JSON: $file" >&2
    return 1
  fi
}

validate_json infra/k8s/app-config.json || exit 1

# Formátování ze souboru
python3 -m json.tool config.json

# Formátování ze stdin (např. odpověď curl)
curl -s https://api.internal/status | python3 -m json.tool --indent 2

DEPLOY_ID="dep_8f3a2b9c"
curl -s \
  -H "Authorization: Bearer $DEPLOY_API_TOKEN" \
  "https://api.deployments.internal/v1/deploys/$DEPLOY_ID" \
  | jq --indent 2 .

# Formátovat pouze blok konfigurace databáze
jq --indent 2 '.database' infra/app-config.json

# Formátovat + filtrovat pole events pouze na úroveň chyb
jq '[.events[] | select(.level == "error") | {id, message, service}]' events.json

# Testování kódu ukončení přímo
echo '{"ok":true}' | jq . > /dev/null 2>&1; echo "exit: $?"  # exit: 0
echo '{bad json}' | jq . > /dev/null 2>&1; echo "exit: $?"   # exit: 1

# -e příznak: exit 1 pokud je výstup false/null
echo 'null' | jq -e . > /dev/null 2>&1; echo "exit: $?"      # exit: 1

Související Nástroje

Prohlížečové alternativy a doplňky k bash JSON formátování — užitečné když potřebujete vizuální rozhraní, sdílitelný odkaz nebo pracujete mimo terminál: