Format JSON di Bash: Panduan jq dan python3

Ketika skrip deploy mulai memproses respons API atau memvalidasi file konfigurasi di CI, mengetahui cara memformat JSON di bash dengan cepat menjadi sangat penting. Dua alat yang mencakup 99% kasus dunia nyata adalah jq dan python3 -m json.tool — keduanya dapat menjalankan pipeline format json bash secara andal, memvalidasi dengan kode keluar, dan terintegrasi dengan bersih ke dalam alur kerja CI/CD. Untuk inspeksi satu kali tanpa terminal, browser-based Pemformat JSON langsung menanganinya. Panduan ini mencakup instalasi jq, pemformatan pipe dan file, fungsi validasi, integrasi CI/CD di GitHub Actions, pre-commit hooks, pola heredoc, dan kapan harus menggunakan fallback Python stdlib.

Apa Itu Pemformatan JSON di Bash?

Pemformatan JSON di bash berarti mengubah JSON yang kompak dan diminifikasi menjadi output yang diindentasi dan mudah dibaca manusia. Data yang mendasarinya tidak berubah — hanya spasi dan jeda baris yang berbeda. Dalam konteks scripting ini penting karena dua alasan: keterbacaan saat debugging, dan validasi saat formatter memeriksa ulang sintaks sebagai efek samping. Alat seperti jq mengurai JSON sepenuhnya sebelum memformatnya ulang, yang berarti menjalankan format yang berhasil juga merupakan pemeriksaan validitas implisit. Perilaku ganda itu — format dan validasi dalam satu langkah — inilah yang membuat jq begitu berguna dalam pipeline otomatis.

{"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 — Memformat JSON di Bash

jq adalah standar de-facto untuk pemrosesan JSON dalam skrip shell (jq 1.6+, bash 4+). Ini adalah prosesor JSON command-line yang dibuat khusus yang dapat memformat, memfilter, mengubah, dan memvalidasi JSON. Filter identitas . meneruskan input tanpa perubahan, tetapi diformat. Ketika jq tidak dapat mengurai input, ia keluar dengan kode 1 — inilah yang membuatnya ideal untuk scripting: pemformatan dan validasi adalah satu operasi.

Instal jq

# macOS
brew install jq

# Debian / Ubuntu
apt-get install -y jq

# Fedora / RHEL / CentOS
dnf install jq

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

# Verifikasi
jq --version  # jq-1.7.1

Format dari stdin dan dari file

# Teruskan JSON inline melalui jq
echo '{"host":"db-prod-01.internal","port":5432}' | jq .

# Format file secara langsung (cetak ke stdout)
jq . config/feature-flags.json

# Format dengan indentasi 4 spasi
jq --indent 4 . config/feature-flags.json

# Format menggunakan tab alih-alih spasi
jq --tab . config/feature-flags.json

Tulis output yang diformat ke file

# Simpan output yang diformat (JANGAN redirect kembali ke file yang sama)
jq . compact.json > formatted.json

# Kompak (minifikasi) — kebalikan dari pemformatan
jq -c . formatted.json

Urutkan kunci dan hapus warna

# Urutkan semua kunci secara alfabetis (berguna untuk diff deterministik)
jq --sort-keys . config/app-config.json

# Nonaktifkan output warna saat menulis ke file log
jq --monochrome-output . response.json >> deploy.log

Referensi Opsi jq

Flag jq yang paling sering digunakan untuk alur kerja pemformatan dan validasi:

Validasi JSON dalam Skrip Bash

Validasi dan pemformatan adalah operasi yang sama di jq — ia mengurai sebelum mencetak. Alihkan stdout ke /dev/null ketika Anda hanya menginginkan kode keluar tanpa output yang diformat. Pola di bawah ini dapat digunakan kembali di seluruh skrip deploy, pre-commit hooks, dan pipeline CI. Dalam respons insiden, hal pertama yang saya lakukan dengan payload API yang tidak familiar adalah meneruskannya melalui jq — ini mengubah tembok JSON yang diminifikasi menjadi sesuatu yang benar-benar bisa saya baca dan debug.

Fungsi validasi yang dapat digunakan kembali

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

Batalkan deploy pada konfigurasi tidak valid

CONFIG="infra/k8s/app-config.json"
validate_json "$CONFIG" || { echo "Membatalkan deploy: konfigurasi tidak valid" >&2; exit 1; }

Validasi semua file JSON dalam direktori

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

Format JSON dari File dan Respons API

Dua sumber umum JSON dalam skrip shell adalah file di disk dan respons HTTP API melalui curl. Masing-masing memiliki pola penanganan yang sedikit berbeda. Untuk file, kekhawatiran utamanya adalah pengeditan aman di tempat. Untuk respons API, detail utamanya adalah menekan bilah kemajuan curl agar tidak merusak input jq.

Pemformatan aman di tempat untuk sebuah file

# Format dan timpa dengan aman menggunakan file temp
tmp=$(mktemp)
jq --indent 2 . config/feature-flags.json > "$tmp" && mv "$tmp" config/feature-flags.json
echo "Memformat config/feature-flags.json"

Format respons curl API

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

Format dan filter secara bersamaan

# Dapatkan yang diformat + filter ke error saja dari endpoint monitoring
curl -s "https://monitoring.internal/api/events?level=error&limit=10" \
  | jq '[.events[] | {id, message, timestamp, service}]' \
  || { echo "Gagal mengambil atau mengurai events" >&2; exit 1; }

Pola || { ... } sangat penting di sini. Tanpanya, curl yang gagal atau respons API yang cacat diteruskan secara diam-diam dan langkah berikutnya dalam skrip Anda beroperasi pada data kosong atau sebagian. Jika Anda perlu memeriksa respons bersarang yang kompleks tanpa terlebih dahulu menulis ekspresi filter, browser-based Pemformat JSON memungkinkan Anda menempel respons mentah dan menavigasi pohon secara interaktif.

Format JSON dalam Pipeline CI/CD

CI adalah tempat gerbang validasi JSON paling penting — konfigurasi yang cacat yang mencapai produksi jauh lebih menyakitkan untuk di-rollback daripada kegagalan pipeline. Sebagian besar pesaing mendokumentasikan jq untuk penggunaan terminal satu kali; pola di bawah ini adalah yang saya gunakan dalam alur kerja SRE produksi untuk menangkap kesalahan konfigurasi sebelum pernah mencapai slot deployment.

GitHub Actions — validasi semua konfigurasi JSON

- name: Validasi konfigurasi JSON
  run: |
    echo "Memvalidasi file konfigurasi JSON..."
    find . -name "*.json" -not -path "*/node_modules/*" | while read -r f; do
      if ! jq . "$f" > /dev/null 2>&1; then
        echo "::error file=$f::Sintaks JSON tidak valid"
        exit 1
      fi
    done
    echo "Semua file JSON valid"

Pre-commit hook — validasi file JSON yang di-stage

#!/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 "JSON tidak valid: $f"; exit 1; }
done
echo "Validasi JSON berhasil"

Format Variabel JSON dan Heredoc di Bash

Skrip shell sering membangun payload JSON secara dinamis — dari variabel lingkungan, metadata git, atau nilai yang dihitung. Pola yang paling aman adalah jq -n --arg / --argjson daripada interpolasi string, yang rusak saat sebuah nilai berisi tanda kutip atau baris baru. Selalu beri tanda kutip ganda pada variabel saat meneruskan ke jq untuk mencegah pemisahan kata pada spasi dalam JSON.

Format variabel respons API yang tersimpan

# Selalu beri tanda kutip "$API_RESPONSE" — spasi dalam JSON akan merusak ekspansi yang tidak dikutip
echo "$API_RESPONSE" | jq --indent 2 .

Bangun dan format payload dengan jq -n

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

# Periksa payload yang dibangun
echo "$payload" | jq .

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

Format JSON di Bash Tanpa Menginstal jq

Ketika jq tidak tersedia — image Docker minimal, CI runner yang terkunci, atau sistem di mana Anda tidak dapat menginstal paket — modul json.tool bawaan Python menyediakan kemampuan inti yang sama. Ini adalah bagian dari pustaka standar Python; jika Python 3 terinstal, ini berfungsi tanpa dependensi tambahan.

# Format dari file
python3 -m json.tool config.json

# Kontrol lebar indentasi
python3 -m json.tool --indent 2 config.json

# Urutkan kunci secara alfabetis
python3 -m json.tool --sort-keys config.json

# Format dari stdin (mis., dialirkan dari curl)
curl -s https://api.deployments.internal/v1/status | python3 -m json.tool

# Validasi dengan kode keluar (semantik sama seperti jq)
python3 -m json.tool config.json > /dev/null && echo "valid" || echo "tidak valid"

# Validasi string inline
echo '{"service":"payments-api","healthy":true}' | python3 -m json.tool > /dev/null
echo "Kode keluar: $?"  # 0 = valid

Output Terminal dengan Penyorotan Sintaks

jq mewarnai outputnya secara default — kunci berwarna biru, string hijau, angka putih. Ketika Anda memerlukan penyorotan sintaks JSON penuh dalam pager yang dapat digulir, atau saat men-debug respons bersarang yang besar dalam sesi terminal, bat memberikan pengalaman yang paling ergonomis. Keduanya berguna untuk debugging dan inspeksi interaktif; tidak satu pun yang boleh digunakan saat menulis output ke file atau respons API.

Instal bat

# macOS
brew install bat

# Debian / Ubuntu (binary mungkin bernama batcat — buat alias jika demikian)
apt-get install -y bat
# alias bat=batcat   # tambahkan ke ~/.bashrc jika diperlukan

# Verifikasi
bat --version  # bat 0.24.0

Lihat file JSON dengan penyorotan sintaks

# JSON dengan penyorotan sintaks di pager (tekan q untuk keluar)
bat config/app-config.json

# Nonaktifkan paging — cetak langsung ke terminal
bat --paging=never config/app-config.json

# Teruskan output jq melalui bat untuk inspeksi berwarna
jq '.database' infra/app-config.json | bat --language=json --paging=never

Output jq berwarna dalam pager yang dapat digulir

# -C memaksa warna bahkan ketika stdout bukan tty (mis. saat meneruskan ke less)
jq -C . logs/deploy-response.json | less -R

Bekerja dengan File JSON Besar di Bash

Ketika file JSON melebihi 50–100 MB, memuatnya ke memori dengan mode default jq bisa lambat atau memicu OOM pada host yang dibatasi memori (container Docker dengan batas 512 MB, misalnya). jq --stream memancarkan pasangan path/value secara bertahap saat membaca, tanpa melakukan buffer seluruh dokumen. Untuk NDJSON (satu objek JSON per baris), jq memiliki pendekatan native yang lebih efisien.

Stream file JSON besar dengan jq --stream

# --stream memancarkan pasangan [path, skalar] saat jq membaca input
# Ekstrak semua field "status" dari arsip log besar tanpa memuatnya sepenuhnya
jq -c --stream   'if length == 2 and (.[0][-1] == "status") then .[1] else empty end'   logs/archive-2026-03.json

NDJSON / JSON Lines — proses satu objek per baris

# NDJSON: satu objek JSON per baris — umum dalam ekspor Kafka, Fluentd, dan Logstash
# -R membaca baris mentah; fromjson? melewati baris yang bukan JSON valid
jq -c -R 'fromjson? | {id: .request_id, status: .http_status, latency: .duration_ms}'   logs/access-2026-03-13.ndjson > logs/summary.ndjson

# Alternatif loop shell — berguna ketika Anda memerlukan penanganan error per baris
while IFS= read -r line; do
  echo "$line" | jq -c '{id: .request_id, status: .http_status}' 2>/dev/null ||     echo "LEWATI: baris yang cacat" >&2
done < logs/access-2026-03-13.ndjson

Kesalahan Umum

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 "JSON tidak valid di 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 — Perbandingan Cepat

Memilih antara alat tergantung pada apa yang tersedia di lingkungan Anda dan apa yang Anda butuhkan selain pemformatan dasar:

Untuk sebagian besar scripting bash dan pekerjaan CI/CD, jq adalah default yang tepat — ia memvalidasi, memformat, memfilter, dan menyediakan kode keluar yang andal dalam satu binary tanpa dependensi runtime. Gunakan python3 -m json.tool sebagai fallback ketika Anda tidak dapat menginstal paket tambahan dan Python sudah ada.

Pertanyaan yang Sering Diajukan

tmp=$(mktemp)
jq --indent 2 . config/app-config.json > "$tmp" && mv "$tmp" config/app-config.json
echo "Berhasil diformat di tempat"

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

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

# Format dari file
python3 -m json.tool config.json

# Format dari stdin (mis., respons 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 .

# Format hanya blok konfigurasi database
jq --indent 2 '.database' infra/app-config.json

# Format + filter array events hanya ke level error
jq '[.events[] | select(.level == "error") | {id, message, service}]' events.json

# Uji kode keluar secara langsung
echo '{"ok":true}' | jq . > /dev/null 2>&1; echo "exit: $?"  # exit: 0
echo '{bad json}' | jq . > /dev/null 2>&1; echo "exit: $?"   # exit: 1

# flag -e: keluar 1 jika output false/null
echo 'null' | jq -e . > /dev/null 2>&1; echo "exit: $?"      # exit: 1

Alat Terkait

Alternatif dan pelengkap berbasis browser untuk pemformatan JSON bash — berguna ketika Anda memerlukan antarmuka visual, tautan yang dapat dibagikan, atau sedang bekerja di luar terminal: