grafana-dashboard-normalizer

Canonicalize Grafana dashboard JSON for clean git diffs. Strips volatile fields (id, version, iteration, templating current), renumbers panels sequentially, sorts tags and all object keys. Zero runtime dependencies - ships a CLI (gdnorm) and a small library API.

Problem

Grafana dashboard JSON contains volatile fields (panel ids, iteration counters, runtime-selected templating values) and unsorted keys. Committing raw exports produces noisy diffs. gdnorm normalizes the JSON so only meaningful changes show up in git.

Install

npm install -g grafana-dashboard-normalizer

or run via npx:

npx grafana-dashboard-normalizer dashboard.json

CLI

gdnorm [files...] [options]

• No files: read stdin, write normalized JSON to stdout.
• Files (no flags): print normalized JSON of each file to stdout (concatenated).
• --write: rewrite files in place when changed; prints normalized: <file>.
• --check: CI mode; lists files that would change, exits 1 if any.
• --keep : remove names from the default stripTop (id, version, iteration).
• --strip : add names to stripTop.
• --no-renumber: keep original panel ids.
• --no-sort-tags: keep original tag order.
• --keep-variable-current: keep templating variable current values.
• --help, --version.

Examples:

gdnorm dashboards/*.json --write
gdnorm --check dashboards/
cat dash.json | gdnorm > normalized.json
gdnorm --keep id,version dash.json

Exit codes: 0 ok, 1 check found differences, 2 usage/IO/parse error.

Library API

import { normalizeDashboard } from "grafana-dashboard-normalizer";

const result = normalizeDashboard(dashboardJson, {
  stripTop: ["id", "version", "iteration"],
  stripVariableCurrent: true,
  renumberPanels: true,
  sortTags: true,
});
// result.dashboard - normalized object
// result.json      - canonical JSON string (2-space indent, LF, trailing newline)
// result.changed   - whether normalization modified the canonical form

Options:

• stripTop (default ["id","version","iteration"]): top-level fields to remove.
• stripVariableCurrent (default true): remove current from templating.list entries.
• renumberPanels (default true): reassign panel ids 1..n in traversal order (rows included).
• sortTags (default true): sort the top-level tags array lexicographically.

Normalization is deterministic and idempotent: normalize(normalize(x)) === normalize(x). Input that is not a plain object throws a TypeError.

License

MIT