PBIR

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). ✅ Atualizado em 02/10/2026: PBIP e PBIR estão em disponibilidade geral (GA) e o PBIR é o formato padrão de relatório (ver seção 3).

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.

Os Power BI Projects (.pbip) também estão em GA. Para editar o modelo semântico por código dentro do Desktop, veja a TMDL view no guia de TMDL.

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. Status: formato padrão (GA)

Desde a versão de setembro de 2026, os Power BI Projects (PBIP) e o PBIR estão em disponibilidade geral (GA), e o PBIR é o formato padrão de relatório no Power BI Desktop e no Power BI Service. Não é mais preciso habilitar nenhum recurso de preview.

• Relatórios em PBIR-Legacy (report.json) continuam abrindo normalmente no Desktop e no Service.
• Ao editar e salvar um relatório PBIR-Legacy, o Power BI o converte automaticamente, sem perguntar, para PBIR.
• O Fabric Git Integration e as Fabric REST APIs exportam as definições de relatório em PBIR.

💡 Precisa manter um relatório em PBIR-Legacy? Não o edite no Service, ou use uma versão do Power BI Desktop lançada antes de setembro de 2026.

4. Salvando, convertendo e restaurando

4.1 Salvar um projeto em PBIR

Ao salvar como Power BI Project (.pbip), o relatório é gravado dentro de uma pasta \definition, localizada dentro da pasta do relatório do PBIP.

4.2 Conversão automática (PBIR-Legacy → PBIR)

Antes de converter, o Power BI cria um backup do relatório.

No Power BI Desktop (retido por 30 dias):

No Power BI Service (retido por 28 dias):

• Para restaurar: Report settings no workspace → Restore as PBIR-Legacy.
• Esse backup só é criado para relatórios convertidos diretamente no Service. Se a conversão aconteceu no Desktop, use o backup do Desktop.

⚠️ Restaurar o backup não impede uma nova conversão: se o relatório for editado e salvo de novo, ele volta a ser convertido para PBIR.

Após a conversão, o arquivo PBIR-Legacy (report.json) é substituído por uma pasta \definition com a representação PBIR do relatório.

4.3 Editar os arquivos com o Desktop aberto (preview)

A partir da versão de agosto de 2026, o Power BI Desktop detecta alterações salvas fora dele (ex.: no VS Code) nos arquivos do projeto e mostra o aviso Apply external changes, que recarrega o relatório e o modelo sem fechar o projeto.

1. File → Options and settings → Options → Preview features → marcar Detect and reload external PBIP changes.
2. Reiniciar o Power BI Desktop.
3. Salvar o trabalho no Desktop antes de editar os arquivos por fora — alterações não salvas no Desktop são sobrescritas ao aplicar (o Desktop avisa).
4. Manter o caminho de cada arquivo do projeto abaixo do limite de 260 caracteres do Windows.

O PBIP e o PBIR estão em GA; só esse recarregamento automático de alterações externas continua em preview.

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.

No Service:

1. Nas configurações do relatório, habilite Copy object names when right clicking on report objects (uma vez só, vale para todos os relatórios).
2. Em modo de edição, clique com o botão direito no objeto → 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. No Service, ele também ajuda a ligar uma consulta DAX ao visual que a gerou, no Workspace Monitoring ou no Log Analytics.

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

• 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.
• Se um relatório PBIR-Legacy não for convertido para PBIR ao ser editado e salvo, a Microsoft trata como problema do produto: abra uma solicitação de suporte.

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 as definições de relatório em PBIR.

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

💡 Para versionar estes arquivos e voltar a uma versão anterior, veja PBIP + Git.

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, conversão (GA), limitações e limites de tamanho.
3. Edit PBIP files outside Power BI Desktop — recarregar alterações externas com o Desktop aberto (preview).