1. What it is#
The definition of a dashboard — visuals, filters, pages, bookmarks, model (tables, relationships, calculated columns, KPIs) and dependencies — exported as a single deterministic JSON file, which can be versioned in Git, reviewed in a Pull Request and reimported without losing identity. It is the equivalent of PBIP / Fabric's Git integration.
2. When to use it#
- You want a real history of who changed what on a dashboard, with PR review.
- You are going to promote a dashboard between environments (dev → test → prod) without copying data — see Environments and promotion.
- You need to prove what you built without exposing data: the Ingestia Academy grades the hands-on challenges from this file.
- You want a readable backup of the dashboard's structure.
3. How it works#
The format (ProjetoBI)
{
"formatVersion": 2,
"dashboard": {
"id": "…", // preserved on the round-trip
"name": "Vendas 2026",
"widgets": [ { "id": "w…", "viz": "line", "sql": "…" } ],
"pages": { … } | null, // canvas + tabs
"filters": [ { "id": "…", "type": "select", … } ],
"bookmarks": [ { "id": "…", "name": "…" } ]
},
"model": { "tables": [], "relations": [], "calcColumns": [], "kpis": [] },
"dependencies": {
"savedQueryIds": [],
"semanticModelId": "…", // when there is a link to a central model
"tabelasReferenciadas": [ "dataset.tabela", … ]
}
}Determinism (byte for byte). The export sorts object keys (recursively, alphabetically) and preserves array order (the order of widgets and filters is semantic). The same project generates exactly the same bytes; the Git diff only shows up when the content really changes.
IDs preserved. Exporting never regenerates an id: widgets (w…), calculated
columns, KPIs and hierarchies come out with the id they have in the database. Relationships have no
id — the identity is the link itself (table.column → table.column). That is why
reimporting the same file is idempotent: everything shows as inalterado.
The Git flow
Export
Open Dashboards → [dashboard] → Share and, on the Project (BI-as-code) card, use Export project. It downloads
<name>-projeto.json.Commit
Keep the file in the company's repository (e.g.:
bi/<dashboard>/projeto.json):bashgit add bi/vendas/projeto.json git commit -m "bi(vendas): ajusta KPI de receita" git push
--- Review in the PR Because the file is sorted and multiline, every changed field is one line of the diff. No reordering noise. --- Reimport On the same Project (BI-as-code) card, choose the reviewed file (up to 1 MB, read in your browser) and click Preview (dry-run): the product shows the classification of each entity before writing. Import project only becomes available after that preview.
### Import: dry-run + explicit conflict resolution
| status | meaning |
| ------------- | ------------------------------------------------------- |
| `novo` | the id only exists in the imported project |
| `inalterado` | same id, content identical to the current one |
| `conflito` | same id, **different content** (with a readable diff in the reader's language) |
**A conflict is never resolved silently.** Without a chosen strategy, the import
**aborts and writes nothing**. Strategies (in the **Conflict strategy**
selector): **`manter_meu`** — "Keep mine" (the current content stays),
**`usar_deles`** — "Use the file's" (the file's content comes in), and
**`abortar_em_conflito`** — "Abort on conflict", which is the **screen default**.
The merge is **additive**: whatever only exists on your dashboard is preserved — importing never
deletes what you didn't send.
## 4. Prerequisites
- Being the **workspace owner**: exporting, previewing and importing the project
define the whole dashboard (definition + model), like duplicating or deleting it — the
card lives on the **Share** page, and the import form appears only for
the owner.
- The dashboard must be **saved** (the export reads what is in the database, not what
is on screen unsaved).
- To promote between environments: sibling workspaces in the same
[organization](../administracao/organizacao-e-workspaces.md).
## 5. How to validate
1. Export the dashboard; keep file A.
2. Reimport A **without changing anything**: the dry-run must show **only `inalterado`**.
3. Export again (file B). `A` and `B` must be **identical byte for byte**
(`diff A B` empty).
4. Change a widget's title in the file and reimport: the dry-run shows **one**
`conflito`, with the diff of that field; switch the strategy to **"Use the
file's"** (`usar_deles`) and click **Import project**. With the default
strategy (abort), the import refuses and nothing is written.
## 6. Limits and caveats
**Travels in the project (the definition):** ids of widgets, calculated columns, KPIs and
hierarchies; visuals (type + SQL/config), filters, bookmarks, page/canvas;
model; declared dependencies (`savedQueryIds`, `semanticModelId`,
`tabelasReferenciadas`).
**Stays in the environment (does NOT migrate):**
- **Data and snapshots** — only the definition travels; the refresh repopulates the data at the destination.
- **Secrets and credentials** — connections, keys and tokens never enter the file.
- **Schedules and run history** — cron, next triggers, runs.
- **Per-person state** — personal views and favorites.
Compatibility: **current** `formatVersion` **= 2**; reading accepts **2 and 1** (the
previous one gets an automatic _upgrade_, `page` → `pages`). An unknown
`formatVersion`, broken JSON or no `formatVersion` is **refused** (fail-closed).
**Pipelines** do not go into this format — they have their own
[versioning](../orquestracao/publicar-e-versionar.md).
## 7. Sample data (synthetic)
Workspace **Aurora Varejo**: dashboard "Comercial Aurora" over `aurora_gold.vendas`,
`produtos`, `filiais` and `calendario`, with the measures `Receita`, `Pedidos` and
`Ticket médio`. The exported file has `dependencies.tabelasReferenciadas`
pointing to those four tables and `model.relations` with
`vendas.produto_id → produtos.id` and `vendas.filial_id → filiais.id`.
## 8. Evidence
A deterministic suite for **round-trip** (export → import → export returns the
same bytes), **canonical ordering** (keys in any order → same output),
**dry-run classification** (new / unchanged / conflict) and **refusal**
of an unknown `formatVersion`.
**Related:** [Editor, canvas, pages and themes](editor-canvas-paginas-temas.md) ·
[Publish and share](tutorial-publicar-e-compartilhar.md) ·
[Environments and promotion](../administracao/ambientes-e-promocao.md).