PBIR

PBIR — Power BI Enhanced Report Format

Consolidado a partir da documentação oficial Microsoft Learn (Power BI Desktop Projects / Embedded). Fontes: projects-enhanced-report-format, projects-report (learn.microsoft.com/power-bi/developer). ⚠️ PBIR está atualmente em preview — considerar as limitações listadas na seção 8 antes de adotar em produção.

✅ Nota de validação (2026-08-06): estrutura geral e mecanismos (habilitação, conversão, datasetReference, schemas) conferidos e consistentes com a documentação oficial. Não re-verificados de forma independente: os prazos exatos de retenção de backup (30 dias Desktop / 28 dias Service, seção 4.2/4.3) — não achei fonte alternativa para cruzar, mas nada contradiz. Substitui o conteúdo anterior de 03-tmdl-pbir-guia-conteudo.md como referência principal.

---

1. Contexto: onde o PBIR se encaixa

Um Power BI Project (PBIP) salva o relatório e o modelo semântico em pastas separadas, usando formatos amigáveis a controle de versão:

O PBIR resolve, para o relatório, o mesmo problema que o TMDL resolve para o modelo: transformar um JSON monolítico (report.json) em uma estrutura de pastas com um arquivo por objeto, tornando o diff e o merge no Git muito mais legíveis.

---

2. O que é o PBIR

PBIR (Power BI Enhanced Report Format) é o formato aprimorado de definição de relatório usado dentro de arquivos Power BI Project (PBIP). Ele organiza cada visual, página, bookmark etc. em arquivos individuais, dentro de uma estrutura de pastas, usando JSON devidamente formatado.

Diferenciais em relação ao PBIR-Legacy (report.json):

• Formato publicamente documentado — permite modificações a partir de aplicações que não sejam o Power BI Desktop.
• Cada arquivo possui um JSON Schema público, que documenta cada propriedade e habilita validação de sintaxe em editores como o VS Code.
• Ao abrir o projeto, o Power BI Desktop valida os arquivos PBIR alterados para garantir que o carregamento tenha sucesso.

Ganhos práticos habilitados pelo PBIR:

• Copiar e colar visuais, páginas, bookmarks ou arquivos entre relatórios.
• Garantir consistência de um conjunto de visuais em todas as páginas (copiando/colando os arquivos do visual).
• Buscar e substituir (find & replace) facilmente em múltiplos arquivos de relatório.
• Aplicar mudanças manuais ou programáticas em lote (ex.: ocultar filtros em nível de visual via script).

---

3. Habilitando o PBIR (preview)

O PBIR só pode ser criado/convertido usando o Power BI Desktop, com o recurso de preview habilitado.

3.1 Para arquivos Power BI Project (PBIP)

1. File → Options and settings → Options → Preview features.
2. Marcar Store reports using enhanced metadata format (PBIR).

3.2 Para arquivos PBIX

1. File → Options and settings → Options → Preview features.
2. Marcar Store PBIR reports using enhanced metadata format (PBIR).

Habilitar para PBIX garante que o formato PBIR também seja salvo dentro dos arquivos .pbix, não apenas nos Power BI Projects.

3.3 Comportamento durante o preview

• Fabric Git Integration e Fabric REST APIs continuam exportando definições de relatório em PBIR-Legacy (report.json) por padrão.
• Se o relatório for importado no Fabric usando o formato PBIR, ambos os recursos passam a exportar a definição do relatório em PBIR.
• Na disponibilidade geral (GA), o PBIR se tornará o formato padrão.

---

4. Salvando, convertendo e restaurando

4.1 Salvar um novo projeto em PBIR

Com o preview habilitado, ao salvar o projeto o relatório é gravado dentro de uma pasta \definition, localizada dentro da pasta do relatório do PBIP.

4.2 Converter um projeto existente (PBIR-Legacy → PBIR)

1. Abrir o PBIP no Power BI Desktop.
2. Garantir que o Preview Feature esteja habilitado.
3. Save o projeto → aparece um prompt solicitando o upgrade para PBIR.
4. Selecionar Upgrade.

⚠️ Importante: uma vez feito o upgrade para PBIR, não é possível reverter pela UI. Para reverter, salve uma cópia dos arquivos PBIP antes de converter.

O Power BI Desktop cria automaticamente um backup do relatório antes do upgrade, retido por 30 dias em:

Após a conversão, o arquivo PBIR-Legacy (report.json) é substituído por uma pasta \definition contendo a representação PBIR do relatório. Selecionando Keep current, o Desktop não pergunta novamente sobre o upgrade.

4.3 PBIR no Power BI Service

• Novos relatórios criados no Service já usam PBIR por padrão.
• Relatórios existentes editados também são convertidos automaticamente para PBIR.
• Durante o Public Preview, administradores podem optar por sair (opt-out) desabilitando a configuração de tenant: "Automatically convert and store reports in the Power BI enhanced metadata format (PBIR)".

Quando o PBIR atingir GA, ele se tornará o único formato suportado, e a conversão será obrigatória.

Restaurar para PBIR-Legacy

• Ao converter um relatório para PBIR no Service, é criado automaticamente um backup em PBIR-Legacy, retido por 28 dias.
• Para restaurar: Report settings no workspace → Restore as PBIR-Legacy.
• Um relatório restaurado não é reconvertido automaticamente; para reabilitar, use Enable PBIR nas configurações do relatório.
• O backup de PBIR-Legacy do Service só é criado para relatórios convertidos diretamente no Service. Se a conversão ocorreu via publicação do Desktop ou upload de PBIX, use o backup criado pelo Power BI Desktop.

---

5. Estrutura de pastas e arquivos do PBIR

A definição do relatório fica dentro da pasta definition\:

├── bookmarks\ │ ├── [bookmarkName].bookmark.json │ └── bookmarks.json ├── pages\ │ ├── [pageName]\ │ │ ├── visuals\ │ │ │ ├── [visualName]\ │ │ │ │ ├── mobile.json │ │ │ │ └── visual.json │ │ │ │ │ └── page.json │ └── pages.json ├── version.json ├── reportExtensions.json └── report.json

Todos os schemas JSON do PBIR estão publicados em: github.com/microsoft/json-schemas/tree/main/fabric/item/report/definition

⚠️ Alguns arquivos de metadados (ex.: visual.json, bookmarks.json) podem conter valores de dados do modelo semântico. Ex.: um filtro 'Company' = 'Contoso' aplicado a um visual persiste o valor 'Contoso' no metadado. O mesmo vale para seleções de slicer, largura de colunas customizadas de matriz, formatação de séries específicas etc.

5.1 Convenção de nomenclatura PBIR

• Nomes entre colchetes ([ ]) na tabela acima seguem uma convenção padrão, mas podem ser renomeados para nomes mais amigáveis.
• Por padrão, páginas, visuais e bookmarks usam como nome de arquivo/pasta o nome do objeto no relatório — inicialmente um identificador único de 20 caracteres (ex.: 90c2e07d8e84e7d5c026).
• Renomear a propriedade 'name' dentro de cada arquivo JSON é suportado, mas pode quebrar referências externas (dentro e fora do relatório).
• O nome do objeto e/ou arquivo/pasta deve consistir em um ou mais caracteres de palavra (letras, dígitos, underscore) ou hífens.
• Após renomear arquivos/pastas PBIR, é necessário reiniciar o Power BI Desktop. No reinício, o Desktop preserva os nomes originais ao salvar.

5.2 Copiar nome de objeto do relatório

Cada objeto do relatório é salvo em pasta/arquivo separado, mas o nome nem sempre é óbvio. É possível copiar o nome de qualquer objeto (páginas, visuais, bookmarks, filtros) diretamente para a área de transferência:

No Desktop:

1. File → Options and settings → Report settings → Report objects → habilitar Copy object names when right clicking on report objects (uma vez só).
2. Clique com o botão direito em qualquer objeto do relatório → Copy object name.

O nome copiado pode ser colado na busca do Windows Explorer ou VS Code para localizar o objeto correspondente na pasta PBIR.

---

6. PBIR JSON Schemas

• Cada arquivo JSON do PBIR inclui uma declaração de JSON Schema no topo do documento.
• A URL do schema é publicamente acessível e documenta as propriedades/objetos disponíveis para cada arquivo.
• Editores como o VS Code oferecem IntelliSense e validação embutidos a partir desse schema.
• A URL do schema também define a versão do documento, que muda conforme a definição do relatório evolui.
• Todos os schemas: github.com/microsoft/json-schemas/tree/main/fabric/item/report/definition

---

7. Recursos avançados

7.1 definition.pbir — definição geral do relatório

Contém a definição geral do relatório e configurações centrais, incluindo a referência ao modelo semântico usado. O Power BI Desktop pode abrir um arquivo PBIR diretamente (assim como se o relatório fosse aberto a partir de um PBIP); se houver referência relativa via byPath, o modelo semântico é aberto junto.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    }
  }
}

A propriedade datasetReference referencia o modelo semântico e pode ser de dois tipos:

Exemplo byConnection:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "Data Source=\"powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName]\";initial catalog=[SemanticModelName];access mode=readonly;integrated security=ClaimsToken;semanticmodelid=[SemanticModelId]"
    }
  }
}

⚠️ Ao implantar um relatório via Fabric REST API, é obrigatório usar referência byConnection — apenas a propriedade semanticmodelid precisa ser especificada:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

⚠️ Não confundir o datasetReference do relatório com o storage mode do modelo semântico (ex.: DirectQuery). O datasetReference só define a qual modelo o relatório se conecta, não como esse modelo armazena/acessa os dados.

Múltiplos arquivos *.pbir

Quando modelo semântico e relatório compartilham o mesmo workspace, o Fabric Git Integration sempre exporta definições com referência byPath. Para forçar o relatório a abrir em live connect (ex.: para trabalhar com medidas em nível de relatório), é possível ter múltiplos arquivos *.pbir — um com conexão byPath e outro com byConnection. O Fabric Git Integration processa apenas o arquivo definition.pbir e ignora os demais *.pbir, mas eles podem coexistir no mesmo repositório:

├── definition\ ├── StaticResources\ ├── .platform ├── definition-liveConnect.pbir └── definition.pbir

A propriedade version do definition.pbir determina os formatos suportados:

7.2 Anotações PBIR (annotations)

É possível incluir anotações como pares nome-valor na definição do relatório, para cada visual, page e report. O Power BI Desktop ignora essas anotações, mas elas podem ser úteis para aplicações externas (ex.: scripts de deploy).

Exemplo — definindo uma defaultPage customizada em report.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  "annotations": [
    {
      "name": "defaultPage",
      "value": "c2d9b4b1487b2eb30e98"
    }
  ]
}

7.3 Alterações externas aos arquivos PBIR

Os arquivos JSON do PBIR podem ser editados com editores de código (VS Code) ou ferramentas externas, desde que respeitem o JSON Schema. Nome/tipo de propriedade incorretos são detectados diretamente no VS Code.

Alterações externas mal formadas podem gerar dois tipos de erro ao reabrir no Power BI Desktop:

Erros comuns

---

8. Considerações e limitações (preview)

• Em Sovereign Clouds, o PBIR não será automaticamente atualizado no Service antes da GA; clientes desses ambientes podem testar via Power BI Desktop com o preview habilitado.
• Relatórios grandes com mais de 500 arquivos podem apresentar problemas de performance na autoria (a visualização do relatório não é afetada).
• Conversão de PBIR-Legacy → PBIR não é reversível (embora um backup seja criado no momento da conversão).
• Converter um arquivo PBIP em PBIX (via "Save As") embute o relatório PBIR dentro do PBIX, carregando todas as limitações do PBIR para o PBIX.
• Filtros automáticos de visual só são persistidos no visual.json depois que o painel de filtros for expandido pelo menos uma vez durante a edição.
• Não suportado em workspaces de Template App.

Limites de tamanho (impostos pelo Service)

Ao atingir esses limites, considerar otimizar o relatório — ver o guia de otimização Power BI.

O Fabric Git Integration e as Fabric REST APIs exportam relatórios usando o formato atualmente aplicado no Service: se o relatório foi criado/importado como PBIR, é exportado em PBIR; se é PBIR-Legacy, é exportado em PBIR-Legacy.

---

9. Outros arquivos da pasta Report (fora de \definition)

Além da pasta definition\ (PBIR), a pasta Report de um Power BI Project pode conter:

Tipos de visuais customizados suportados

---

10. Quick reference

---

11. Fontes consultadas

1. Create a Power BI report in enhanced report format — visão geral do PBIR, motivação e como habilitar.
2. Power BI Desktop project report folder — estrutura completa da pasta Report, formato PBIR, estrutura definition\, schemas, anotações, erros comuns, limitações e limites de tamanho.