Grafana / Intermediate: transformations, configuration, and alerts / Lesson 9

Dashboard JSON, provisioning, and identity

Review dashboard configuration as versioned state with stable UIDs, local identifiers, data-source mappings, and a deliberate source-of-truth policy.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish dashboard UID, local ID, and schema revision.
Explain file provisioning versus UI changes.
Check referenced resources before moving a dashboard.

A title is not a complete dashboard identity

A dashboard title helps readers, while a UID supports stable references within the relevant Grafana scope. Local numeric IDs and panel IDs have their own roles and should not be treated as portable global identity. A copied dashboard can collide with an existing UID or retain references to a source that means something else in the destination. Record folder or organization context and ownership. The classic JSON model also contains model and revision fields whose meanings differ from Grafana’s application version. Check the selected version’s schema instead of incrementing numbers until an import appears to work.

Read configuration without assuming completeness

The small JSON fragment names a synthetic UID and title with no panels. It illustrates a portion of the classic dashboard definition, not an API request, complete migration artifact, or current universal schema. Real dashboards also contain query targets, source references, variables, time settings, field configuration, and plugin-specific options. Exported material can retain internal names, query text, or selected data in related sharing formats. Review the actual export type and privacy implications before treating it as a harmless template. No dashboard is created or exported by this course.

json Illustrative classic-dashboard definition fragment

{"uid":"transit-lab-overview","title":"Transit Lab Overview","panels":[]}

The fragment is incomplete and unexecuted. It establishes no Grafana schema validation, API compatibility, resource creation, or portable source mapping.

Choose a source of truth for managed configuration

File provisioning can manage dashboards and data sources in supported self-managed deployments, with documented update and deletion behavior. A permitted UI edit of a provisioned dashboard does not automatically rewrite its source file; a later provisioning update can replace database state. Review the exact allow-UI-update and deletion settings instead of assuming a UI save is durable configuration management. Cloud-managed provisioning, APIs, Terraform providers, and other supported approaches have different ownership and capability boundaries. Select the actual authorized mechanism and version before designing rollout, backup, or rollback procedures.

Check local references and uniqueness before review

The offline JSON fixture verifies two synthetic panel IDs are unique and their source UID appears in a declared inventory. This is a narrow structural check, not a Grafana validator. It cannot establish plugin options, query correctness, folder permissions, source credentials, or version migration. A valid JSON document can still reference the wrong backend. Keep environment mappings explicit and test missing resources as well as the expected case. Do not silently substitute a default source when the reviewed UID is absent; that can turn a deployment problem into a misleading but populated panel.

python Offline configuration-reference fixture

import json
raw = '{"uid":"transit-lab-overview","panels":[{"id":1,"source_uid":"transit-lab-prom"},{"id":2,"source_uid":"transit-lab-prom"}]}'
document = json.loads(raw)
known_sources = {"transit-lab-prom"}
ids = [panel["id"] for panel in document["panels"]]
assert len(ids) == len(set(ids))
assert all(panel["source_uid"] in known_sources for panel in document["panels"])
print(document["uid"], "panels", len(ids))

Expected output

transit-lab-overview panels 2

source_uid is a teaching-record field, not a claimed Grafana schema field. Only fixed JSON and inventory assumptions are checked.

Review semantic diffs and recovery assumptions

A dashboard change should explain user-facing behavior, query and source changes, variable defaults, access effects, and verification. Avoid reviewing only a large serialized diff where generated layout fields hide a changed denominator. Preserve the approved configuration and environment mapping, and understand how the chosen management mechanism restores it. This lesson executes local JSON checks only. It imports no dashboard, writes no Grafana state, runs no provisioning provider, and changes no file watched by a service. Configuration syntax and actual lifecycle behavior remain untested platform properties.

Common errors and fixes

A dashboard title is used as a global identifier

Why it happens: Display naming was confused with scoped identity.
How to fix it: Review UID and destination resource scope.
Prevent it next time: Keep migration mappings explicit.

A provisioned UI edit is overwritten unexpectedly

Why it happens: The file remains authoritative under the chosen mechanism.
How to fix it: Review the documented update policy and source of truth.
Prevent it next time: Version managed changes at the authoritative source.

Valid JSON is called a tested dashboard

Why it happens: Parsing was confused with schema and runtime validation.
How to fix it: Separate local structure checks from Grafana integration evidence.
Prevent it next time: Test source references and plugin compatibility when authorized.

Check your understanding

1. Why can reusing the same dashboard UID in another environment be unsafe without a mapping review?

Show worked solution

The destination may already use that identity, or the copied source UIDs and folder scope may refer to different resources. Check intended create-versus-update behavior, permissions, plugin versions, and source mappings through the actual supported mechanism. A familiar title does not establish equivalent identity or data.

2. What does the Python fixture prove and what does it leave untested?