About This Article
This article was created using an automated generation workflow leveraging generative AI. It reviews the key sorting feature in the official jq manual and organizes safe procedures to make JSON configuration diffs easier for humans to read.Verification Status: 📘 Confirmed with official jq specifications; Ubuntu actual device verification pending
When you run diff directly on JSON files, diff differences in key order alone can often generate a large volume of diff output.Normalizing Key Order with jq Before Running diff allows you to focus on actual configuration value differences.
Try This First
cat > before.json <<'JSON'
{"port":8080,"mode":"test","enabled":true}
JSON
cat > after.json <<'JSON'
{"enabled":true,"mode":"prod","port":8080}
JSON
jq -S . before.json > before.sorted.json
jq -S . after.json > after.sorted.json
diff -u before.sorted.json after.sorted.json
The difference you need to look at is mode of test → prod. Key reordering disappears from the diff output.
Why -S Works
The order of keys in a JSON object is often not essential when humans are reviewing configuration differences.jq -S sorts object keys in the output, reducing formatting discrepancies.
Changing a Single Location
port Change to 8081 and re-run. The diff will show two locations, making it easier to visually track what has been changed during a review.
Practical Applications
This can be used for checking web server configurations, API responses, exported application settings, and changes in AI-generated JSON. Always check for secret values before attaching the output to a change request.
jq 'del(.password, .token, .secret)' config.json
This example only removes top-level keys with matching names. It does not automatically or completely remove nested or differently named secret values.
Note
Normalization is not a guarantee that the semantics are identical. Because array order can be meaningful, avoid sorting arrays indiscriminately.
Summary
When comparing JSON files, reducing formatting variations beforehand makes the diff easier for humans to review.jq -S + diff -u is a practical combination that can be easily tested on a small scale.
Official and Primary Sources
- jq Manual: https://jqlang.org/manual/
