pbir-visual-json

name: pbir-visual-json description: Use when editing visual.json inside a Power BI PBIR report's visuals/ folder. Covers top-level structure (name, position, visual vs visualGroup mutually exclusive, filterConfig sibling NOT child of visual, root-level isHidden for bookmark toggles), expression literal suffixes — string 'text', double 14D, integer 14L, decimal 2.4M, hex '#FF0000', datetime literal, null — with exceptions (transparency uses L inside dropShadow, labelPrecision L, labelDisplayUnits D, triple-quoted font fallback chains), field reference patterns (Column, Measure, Aggregation, HierarchyLevel, SparklineData), visual-type to query-role map (card, tableEx, pivotTable, slicer, lineChart, barChart, kpi, scatterChart), objects vs visualContainerObjects split, sortDefinition, slicer default values via objects.general.properties.filter, visual groups, table column widths. Invoke when user edits visual.json, sets a visual property, debugs silently-ignored container props, or writes SQExpr literals. paths: - "/visuals//visual.json"

PBIR visual.json Reference

Path: Report.Report/definition/pages/{PageName}/visuals/{VisualName}/visual.json

Top-Level Structure

position

{"x": 100, "y": 50, "z": 1000, "width": 400, "height": 300, "tabOrder": 0}

z layer order: higher = front. Common values 0, 1000, 2000, 3000, 5000, 8000, 15000.

visual Object

Critical: objects vs visualContainerObjects are distinct in schema 2.4.0+. Container properties in objects fail silently. visualContainerObjects at root errors.

Expression Literal Suffixes

All formatting values inside visual.json use {"expr": {"Literal": {"Value": "..."}}} wrappers. Theme JSON uses bare values.

Non-literal expressions:

Gotchas: transparency uses D normally but L inside dropShadow. labelPrecision always L, labelDisplayUnits always D. String escaping: single quotes doubled ("'O''Brien'"). Font fallback chains: "'''Segoe UI Semibold'', helvetica, sans-serif'". (Yes — three single quotes. The outer pair wraps the SQExpr string literal; the inner pair escapes the space-containing font name. Not a typo.)

Field Reference Patterns

QueryAggregateFunction: 0=Sum, 1=Avg, 2=DistinctCount, 3=Min, 4=Max, 5=Count, 6=Median, 7=StdDev, 8=Var

Filter SourceRef gotcha: inside filter Where conditions, SourceRef uses "Source": "alias" (from From), NOT "Entity". Query projections use "Entity".

Visual Types and Query Roles

Projection Properties

Visual calculations (NativeVisualCalculation) always have queryRef: "select".

sortDefinition

"sortDefinition": {
  "sort": [{
    "field": {"Measure": {"Expression": {"SourceRef": {"Entity": "Sales"}}, "Property": "Revenue"}},
    "direction": "Descending"
  }],
  "isDefaultSort": true
}

Slicer Default Selected Values

Store in objects.general.properties.filter — NOT filterConfig. filterConfig filters data going into the slicer; objects.general.properties.filter pre-selects values.

Hiding Visuals and Fields

• Hide whole visual: "isHidden": true at root (outside visual).
• Hide fields from display: omit from queryState — still referenceable by extension measures / filters.

Visual Groups

{
  "name": "kpi_group",
  "position": {"x": 0, "y": 0, "z": 0, "width": 800, "height": 400},
  "visualGroup": {
    "displayName": "KPI Section",
    "groupMode": "ScaleMode",
    "objects": {"background": [...], "general": [...], "lockAspect": [...]}
  }
}

groupMode: ScaleMode (scale contents) or ScrollMode. Children set parentGroupName. Group objects limited to background, general, lockAspect.

Table / Matrix Column Widths

"columnWidth": [{
  "properties": {"value": {"expr": {"Literal": {"Value": "215D"}}}},
  "selector": {"metadata": "Orders.Order Lines"}
}]

mobile.json

Optional sibling file at visuals/{VisualName}/mobile.json. Mirrors visual.json position fields with mobile coordinates. Typically authored via Desktop.

Gotchas

April 2026 visual changes

Reference

• Microsoft Learn: Visualizations overview in Power BI
• Microsoft Learn: Visualization types in Power BI
• Microsoft Learn: Power BI Desktop project — report folder
• Microsoft Learn: Card visual — Fixed size, Fit to space, theme keys
• Microsoft Learn: Smart narrative visual
• Comprehensive MS Learn link bundle (visual catalog → visualType / per-visual articles / visualGroup / custom visuals / PBIR file format): references/REFERENCE.md

See also

• pbir-themes — theme value conventions (bare vs wrapped literals)
• pbir-conditional-formatting — CF patterns inside visual.json objects
• pbir-filters — filter body shape and SourceRef.Source rule
• pbir-bookmarks — bookmarks reference the visual's root-level name