Pbir Pages

PBIR Page JSON Reference

Page-level JSON for reports in PBIR format. Each page lives in definition/pages/<PageName>/page.json. Page order and the active page are tracked in definition/pages/pages.json.

Schema: https://developer.microsoft.com/json-schemas/fabric/item/report/definition/page/2.0.0/schema.json

Top-Level Properties

Minimal Page

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/page/2.0.0/schema.json",
  "name": "77e770be04c64c0c6938",
  "displayName": "Overview",
  "displayOption": "FitToPage",
  "width": 1280,
  "height": 720
}

Common Page Sizes

The Fluent 2 base theme is GA and is the default for new reports in Desktop and the service; it bumps the new-page default to 1920x1080. Initial page in a report stays 1280x720; existing reports and existing pages don't auto-resize when switching base themes. The Theme pane (View ribbon) also surfaces aspect-ratio presets for common page sizes. See pbir-themes for base-theme switching.

pages.json

Page order and active page:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/pagesMetadata/1.0.0/schema.json",
  "pageOrder": ["77e770be04c64c0c6938", "da2e63ebeb2179a994f1"],
  "activePageName": "77e770be04c64c0c6938"
}

Canvas Alignment

verticalAlignment and horizontalAlignment control canvas position when the viewport differs from the canvas size. Most relevant with displayOption: "ActualSize".

Background (Canvas)

The canvas is the area where visuals sit. It is NOT the wallpaper behind it (that is outspace).

Visual hierarchy (bottom to top): outspace (wallpaper) -> background (canvas) -> visuals.

"objects": {
  "background": [{
    "properties": {
      "color":        { "solid": { "color": { "expr": { "Literal": { "Value": "'#FFFFFF'" } } } } },
      "transparency": { "expr": { "Literal": { "Value": "0D" } } }
    }
  }]
}

Transparency values: "0D" opaque, "50D" semi, "100D" fully transparent (shows wallpaper).

Wallpaper (outspace)

The area behind and around the canvas.

"objects": {
  "outspace": [{
    "properties": {
      "color": { "solid": { "color": { "expr": { "Literal": { "Value": "'#2B579A'" } } } } }
    }
  }]
}

outspacePane (Filter Pane) — NOT on page.json

outspacePane is report-level, never page-level. Do not place it in page.json. Responsibility is split:

• Visibility and expansion state (visible, expanded) live in report.json → objects.outspacePane — see pbir-filters.
• Styling (colors, text, backgrounds, input colors, width) lives in the custom theme at visualStyles["*"]["*"].outspacePane — see pbir-themes.

Visual Interactions

Override default cross-filtering between visuals on a page. Set on page.json:

"visualInteractions": [
  { "source": "slicer_region", "target": "chart_trend", "type": "NoFilter" }
]

source and target are the name values from each visual's visual.json.

Page-Level Filters

"filterConfig": {
  "filters": [{
    "name": "filter-guid",
    "field": {
      "Column": {
        "Expression": { "SourceRef": { "Entity": "Products" } },
        "Property":   "Category"
      }
    },
    "type": "Categorical",
    "howCreated": "User"
  }]
}

Same structure as report-level filters in report.json. Slicer visuals are NOT filters — they are regular visuals bound to categorical data.

Tooltip Pages

Small hidden pages shown as rich tooltips when a visual is hovered.

Setup on page.json:

{
  "name": "tooltip_revenue_id",
  "displayName": "RevenueTooltip",
  "displayOption": "ActualSize",
  "width": 320,
  "height": 240,
  "type": "Tooltip",
  "visibility": "HiddenInViewMode"
}

• type: "Tooltip" — marks the page
• visibility: "HiddenInViewMode" — hides from page tabs
• displayOption: "ActualSize" — tooltip pages don't scale
• Common sizes: 320x240 (default), 400x120 (wide/compact)

Opt-in from a visual (in the visual's visualContainerObjects):

"visualContainerObjects": {
  "visualTooltip": [{
    "properties": {
      "show":    { "expr": { "Literal": { "Value": "true" } } },
      "type":    { "expr": { "Literal": { "Value": "'ReportPage'" } } },
      "section": { "expr": { "Literal": { "Value": "'tooltip_revenue_id'" } } }
    }
  }]
}

• type values: "'ReportPage'" (use tooltip page), "'Default'" (auto default tooltip)
• section — the name GUID from the tooltip page's page.json, NOT its displayName
• Disable tooltips per visual: "show" set to "false"

visualHeaderTooltip styles the tooltip over header icons (separate from the hover tooltip) — same pattern, slightly different properties.

Drillthrough Pages

A regular page (type: "Default") with a drillthrough filter in filterConfig. Users right-click a value on another page and navigate in with the filter applied.

{
  "name": "drillthrough_customer_id",
  "displayName": "CustomerDetails",
  "displayOption": "FitToPage",
  "width": 1920,
  "height": 1080,
  "filterConfig": {
    "filters": [{
      "name": "drillthrough_filter_id",
      "field": {
        "Column": {
          "Expression": { "SourceRef": { "Entity": "Customers" } },
          "Property":   "Customer Name"
        }
      },
      "type": "Categorical",
      "howCreated": "User"
    }]
  }
}

• Any field can be a drillthrough target. Hidden the page from tabs via visibility: "HiddenInViewMode" if it is drillthrough-only
• Add a back-button visual (actionButton) so users can return

Page Formatting Objects

Page Folder Naming

• PBI Desktop generates folder names as 20-char hex (e.g. 0c32c81bce347402001e/)
• Rename freely to PascalCase (e.g. Overview/) for better diffs and readability
• Desktop-generated folders may contain spaces — prefer letters, digits, underscores, hyphens in human-authored names
• page.json filename and the internal name property MUST remain unchanged

Literal Value Encoding

All formatting property values are wrapped in expression literals:

Gotchas

Reference

• Microsoft Learn: Customize page sizes and dimensions in Power BI
• Microsoft Learn: Create tooltips based on report pages
• Microsoft Learn: Use drillthrough in Power BI reports
• Comprehensive MS Learn link bundle (page sizes / canvas vs wallpaper / tooltip / drillthrough / visual interactions / PBIR file format): references/REFERENCE.md

See also

• pbip-project-structure — project file layout
• pbir-cli — pbir pages / pbir visuals commands
• pbir-report-workflow — layout math and workflow
• pbir-filters — outspacePane visibility/expansion on report.json
• pbir-themes — outspacePane theme styling