HyperPBI specification reference

HyperPBI 2.0 uses Field Manifest aliases or canonical resolved field keys. Display names are not accepted as aliases. Alias resolution covers descriptor-declared nested structures, while ArcGIS service fields and joined map aliases remain unchanged. Component maturity (stable, beta, experimental, deprecated) describes implementation governance and is separate from authoring complexity (recommended, standard, advanced).

This reference describes the implemented HyperPBI dashboard schema 2.0 contract, the only version accepted by the production runtime. Runtime implementation and validators are authoritative.

Root object and version behavior

{
  "version": "2.0",
  "title": "Operations",
  "theme": { "mode": "light", "density": "compact" },
  "app": { "enabled": true },
  "data": { "sources": {}, "datasets": {} },
  "definitions": {},
  "components": []
}

Version 2.0 rejects unknown root, component, dataset-definition, and nested map properties. Dashboard schema 1.0 and missing versions are blocking errors and are never migrated by the runtime.

The package version in pbiviz.json is unrelated to this schema version.

Theme and style system

theme accepts:

• mode: light|dark|auto
• density: compact|normal|spacious
• fontFamily
• primaryColor, accentColor, surfaceColor, textColor, borderColor
• dangerColor, warningColor, successColor
• numeric radius, cardPadding, gap

styles.globalCss is sanitized visual-wide CSS. styles.components is a record keyed by *, a component type, or #component_id; each entry may contain className, style, and css. Component-local style wins. CSS is parsed, allowlisted, and scoped; it is not an arbitrary browser stylesheet.

During authoring, app.designSystem may reference a registered design preset. Preparation merges its theme/style defaults, lets explicit authoring values win, and removes designSystem before strict runtime validation. Unknown presets are errors.

Root layout, shell, and state

layout.type is grid|flex|split; optional columns and gap are numeric. layout.leftPanel can set width, collapsible, and defaultCollapsed; layout.main can set type: grid|flex, columns, and gap.

app supports:

• enabled
• layout: vertical|horizontal
• container: fluid|boxed
• density: compact|normal
• stickyHeader
• contentPadding: none|compact|normal
• brand: required title; optional subtitle, icon, shortTitle
• navbar: visibility, sidebar toggle, search, actions, user, notifications
• sidebar: visibility, width, collapsed width, collapse settings, mobile breakpoint, navigation, footer
• pageHeader: visibility, title/subtitle, breadcrumbs, actions, metadata
• footer: visibility and primary/secondary text

Navigation/action items use declarative uiAction; they never execute code or navigate arbitrary URLs. A permanent sidebar should be used only when the visual viewport can support it. Overlays/offcanvas are safer for narrow tiles.

Runtime state tracks tabs, steps, sidebar state, component values, overlays/toasts, selected source rows/keys, per-component selections, highlights, and interaction filters. Stable IDs are therefore part of the behavior contract.

Field references and origin

New 2.0 authoring uses Field Manifest aliases. Preparation resolves them to canonical runtime keys. Aliases match ^[A-Za-z][A-Za-z0-9]*$, are deterministically derived from display/source metadata, qualify collisions with the source table, and use a stable suffix only for remaining collisions.

Field metadata distinguishes:

• key: canonical runtime key
• alias: AI-facing key
• displayName
• queryName, qualifiedName
• sourceTable, sourceColumn
• kind: column|measure|unknown
• queryAggregation
• isImplicitAggregation
• origin: powerbi-column|powerbi-measure|dataset-group|dataset-derived|dataset-metric
• semantic role, data type, format, bound roles, and default aggregation
• identity-selection and external-filter support

A query wrapper such as Sum(Sales.Amount) has queryAggregation: "sum" and isImplicitAggregation: true when it wraps a model column. It is not a true model measure. External filters require a column plus sourceTable and sourceColumn. Identity selection instead uses Power BI selection identities/source-row lineage.

Logical datasets

data.sources may declare read-only miniup.table, miniup.function, or web-only rest.get sources. data.datasets is a named object. Every definition requires a nonblank source of powerbi, a declared source, or another named dataset. Allowed operations are filter, derive, rename, select, groupBy, metrics, distinct, sort, and limit.

After resolving the source chain, runtime and static-schema order is:

1. filter
2. derive
3. rename
4. select
5. groupBy and metrics
6. distinct
7. sort
8. limit

See Data model for exact contracts, lineage, caching, and zero-row behavior.

Definitions

definitions maps a name to a component fragment. An instance supplies use: "name" and its own id.

• Object properties merge recursively.
• Instance values override definition values.
• Arrays are replaced, not concatenated.
• A definition may inherit another definition with use.
• Definition IDs are removed so an instance cannot inherit an identity.
• Unknown references and cycles are errors.

Expansion occurs before strict component validation. use is therefore an authoring property, not a runtime component property.

Application patterns

Patterns have type: "pattern", a pattern name, a stable id, and pattern-specific fields. They expand before strict component validation and derive child IDs from the pattern ID.

Unknown patterns and missing required values produce structured diagnostics.

Calculations

Root calculations.fields defines typed row-level outputs with key, optional label, type: number|text|boolean|date, and a safe expression. Root calculations.metrics defines dashboard aggregates using count, countWhere, sum, sumWhere, avg, avgWhere, min, max, distinctCount, ratio, or percentOfTotal.

Preparation validates root calculated fields and augments the static powerbi schema before logical-dataset propagation and component binding validation. At runtime those fields are evaluated before logical datasets, so they can drive dataset select/derive/group/metrics and components even when the current data view has zero rows. Root scalar metrics are recomputed over currently filtered rows and remain a separate namespace consumed through metricGrid.metrics[].metric or the metric template namespace. See Calculations DSL.

Shared component contract

Every 2.0 component requires:

• type: a canonical type
• id: globally unique; ^[A-Za-z][A-Za-z0-9_-]{0,99}$

Shared allowed properties are type, id, dataset, title, subtitle, span, order, responsive, heightMode, minHeight, aspectRatio, className, hidden, props, style, css, slots, data, visibility, interactions, interaction, ariaLabel, icon, variant, size, disabled, tooltip, and uiAction.

span, when supplied, is numeric from 1 through 12. title, subtitle, dataset, and ariaLabel must be strings; hidden must be Boolean. A component inherits its ancestor dataset unless it names another dataset. Unknown datasets and fields outside the selected dataset schema are errors.

Exact per-type required/allowed properties, status, capabilities, accessibility notes, compatibility, and examples are generated in the component catalog. Do not maintain a second handwritten list.

Responsive layout and sizing

responsive is a mobile-first object keyed by xs, sm, md, lg, and xl. HyperPBI uses component-container widths of 0, 480, 768, 1024, and 1280 pixels, so an embedded dashboard responds to its own allocated space rather than the browser viewport. Each rule may set:

• integer span from 1 through 12
• integer order
• either Boolean visible or hidden
• direction: "row"|"column"
• Boolean stack
• integer columns from 1 through 24

Compact components are full width by default. Grids and split panes stack at xs; splits restore their authored direction at md, while grids restore authored columns and component desktop spans at lg. Explicit breakpoint rules win. The base hidden property remains an unconditional authoring hide and is not reversed by a responsive rule.

heightMode is auto|fixed|fill|aspectRatio. fill establishes a reusable height chain through root/app content, nested grids/flex/splits, cards, tabs, map frames, chart canvases, and virtual tables; every ancestor still needs a bounded host height. aspectRatio uses aspectRatio (default 16:9 for shared components) plus optional minHeight. Maps retain their existing map-specific fixed/fill/aspect sizing and default heights.

split supports direction, children, sizes, minSizes, maxSizes, resizable, persist, and storageKey. Pane arrays align one-to-one with children, use percentages, and are normalized to 100. Feasible minimum/maximum bounds are enforced both initially and during resize. Resizable handles support pointer drag, arrow keys (Shift changes by five percentage points), double-click reset, ResizeObserver propagation, and an accessible separator value. persist is none|session|local; a resizable split defaults to per-visual local persistence, namespaced by the visual instance and stable component ID.

Interaction systems

UI actions

uiAction is one action or an array. Types are:

• clearFilters
• setTab (target, value)
• setState (target, value)
• toggleState (target)
• toggleSidebar
• openOverlay, closeOverlay, toggleOverlay (target)
• setStep (target, value), nextStep, previousStep (target)
• showToast (message; optional title, intent, durationMs)
• dismissToast (target)
• scrollTo (target)
• refresh (successful safe no-op; Power BI owns refresh)

Toast duration is persistent when omitted/zero; otherwise runtime clamps it to 1,000–30,000 ms.

Universal data interaction

interaction allows:

• enabled
• trigger: auto|click|change
• internalMode: none|highlight|filter
• internalScope: self|others|all
• externalMode: none|auto|selection|filter
• field, value
• operator: =|!=|>|>=|<|<=|contains|in|between
• selectionMode: replace|toggle|add
• multiSelect, showSelector, clearOnSecondClick
• target or targets to restrict internal linked behavior to one or more existing component IDs

It is optional. auto trigger resolves to change for controls and click otherwise. auto external mode resolves to filter for controls and selection for data-point/custom components.

Safe event-specific interactions

interactions maps a supported event such as custom-content onClick to an allowlisted action: selectRow, selectWhere, clearSelection, setFilter, clearFilter, setState, toggleState, openTab, toggleCollapse, drillToDetail, highlight, or clearHighlight. Conditions use safe expression objects; no handler code is accepted.

See Interactions for origin/lineage restrictions.

Overlays

dropdown, popover, modal, offcanvas, and compatibility drawers render through the root overlay host. Each requires a stable ID. UI actions must target an existing overlay ID. Dropdown/popover positioning is viewport-aware; modal/offcanvas support focus and dismissal behavior. Do not simulate overlays with fixed-position custom HTML (fixed positioning is blocked by scoped CSS policy).

Charts

Semantic chart bindings are schema properties: category/measure, x/y, series, source/target, path fields, group/indicators, or nested chart depending on the type. Aggregation enum is sum|avg|min|max|count|distinctCount|countWhere|first where component metadata allows it.

Safe ECharts options may adjust presentation. Functions, URL-bearing keys, executable strings, and unsupported series types are removed. On semantic charts, options cannot replace datasets/transforms, generated axis data/type, semantic series data/type/links/nodes/encode/transform/dimensions, radar indicators, or series counts. advancedChart permits broader sanitized JSON options but still no functions or unsafe URLs.

events accepts zoom, rangeSelect, and brush. Each event has enabled, optional field, optional linked targets, and an optional universal interaction override. Zoom state is persisted per chart. rangeSelect maps the visible data-zoom window to adapter bindings; brush maps ECharts rectangle/polygon selections to exact binding rows. Both deduplicate original source lineage before internal linking or Power BI selection. Event configuration remains data: no callbacks or handler strings are accepted.

drill performs hierarchical navigation over already evaluated logical datasets. It requires at least two levels; every level has a stable id, a named dataset, and optional label, category, measure, x, y, and pointSize. A child parentField is compared with the selected parent binding value. initialLevel, trigger: "click"|"doubleClick", and showBreadcrumbs control navigation. Breadcrumb state stores level IDs and selected values, and every chart binding continues to resolve through each dataset row's original Power BI lineage. Drill never issues a network or semantic-model query.

Tables and matrix

table accepts native columns, pagination, page size, search, column resizing, maximum rows, sticky header, compact/normal density, stripes, hover, row count, page-size choices, row actions, and an empty state. Columns can specify field/title/width/format/alignment, conditions, sorting, resizing, visibility, wrapping, freezing, text/badge/progress cell type, and intent mapping.

virtualization accepts enabled, threshold from 1 through 5,000, rowHeight from 22 through 80 pixels, and overscan from 1 through 100. When pagination is off and the threshold is exceeded, the runtime measures the actual scroll viewport and renders only the visible range plus overscan. Explicitly disabling virtualization retains a 5,000-row non-virtual DOM guard. The Power BI formatting data limit remains authoritative; a 250,000-row final memory guard prevents unbounded author input. Search indexing is built once when search becomes active and reused across subsequent query text.

export accepts enabled, formats: ["csv","xlsx"], scope: "filtered"|"selected"|"selectedOrFiltered", and fileName. Export uses the complete prepared/filter/sort result rather than the virtual DOM or display truncation. Selected scope intersects selection with currently filtered rows; selectedOrFiltered falls back to filtered rows when nothing is selected. Hidden columns are excluded. CSV includes a UTF-8 BOM and RFC-style escaping; XLSX is a deterministic OOXML workbook. Text beginning with spreadsheet formula sigils is neutralized in both formats.

matrix requires nonempty rows and values and renders every value descriptor. Each value may define field, aggregation, where, title, and format; metric titles fall back deterministically when omitted. count/countWhere can omit a field, while numeric aggregations require a numeric field and countWhere/sumWhere/avgWhere require where. With columns, output headers are column group × metric. Totals and heatmap normalization are per metric. maxRows is deterministic, and the runtime enforces a 5,000-cell budget with a visible truncation warning. Row/column headers use table scopes and data-cell labels include their row, column, and metric context. engine: "tabulator" is compatibility input normalized to native because Tabulator is not bundled.

Maps

map uses Leaflet and accepts view, basemap, layerGroups, bookmarks, layers, search, legend, layer panel, toolbar, and height. Layer source types are powerbi, arcgisFeature, arcgisTile, and arcgisDynamic. Public ArcGIS requests require HTTPS, a permitted Maps package host, and no embedded credentials.

tools.rectangleSelection and tools.lassoSelection are Boolean or objects with enabled and selectionMode: "replace"|"toggle"|"add"; lasso also accepts minimumPoints from 3 through 100, and runtime draft points are bounded. Matching toolbar.rectangleSelection and toolbar.lassoSelection flags control button visibility. A drag tests visible resolved points, independent multipoints, crossing lines, and polygon area (including holes), then updates canonical feature keys and passes deduplicated Power BI row lineage through the universal interaction engine. Ctrl/Cmd toggles and Shift adds without changing the authored default. Service-only features remain locally selectable without fabricating Power BI identities.

All Power BI fields arrive through Values. Each layer may set dataset; precedence is layer, map, then powerbi. Power BI location bindings belong in that layer's source.bindings. Explicit layers never inherit global Runtime Config coordinates. Geometry overrides coordinates; latitude/longitude are strict finite numbers in range; missing layerValue returns no unrelated data; mixed geometry is classified across all features. Renderer, label, popup/tooltip, visibility, filter, interaction, and cluster aggregation fields resolve from the exact powerbi|service|joined fieldSource; defaults are Power BI for Power BI layers, service for ArcGIS references, and joined for ArcGIS joins. Grouped logical rows retain contributing source identity arrays.

view.fitPadding is a bounds-padding ratio from 0 through 0.5, with authoring default 0.08; pixel values such as 24 are invalid. Basemap and authored center/zoom/min/max update the mounted map reactively. Stable point shapes are circle|square|diamond|triangle. An explicit cluster renderer clusters independently of legacy global clustering and accepts clusterLabel: "count"|"sum"; sum requires a numeric aggregateField and may declare its source and format. ArcGIS metadata inspection and join preview are explicit, cancellable authoring operations and fetched metadata is never persisted into the specification.

ArcGIS tile/dynamic mounted instances are definition-reactive: URL, attribution, zoom, pane, layer IDs/definitions, image format/transparency, and debounce changes replace only that overlay and preserve the viewport. Root service inspection makes one bounded summary request, classifies spatial layers, hierarchy-only groups, and nonspatial tables, then fetches only the selected item's metadata. Successful item metadata is cached; aborted/stale results cannot overwrite a new selection.

Map feature interactions accept trigger: "click" only; strict 2.0 authoring rejects map-layer change and auto without changing non-map interaction enums. Join cardinality is from Power BI rows to service features: oneToOne requires unique normalized keys on both sides, while manyToOne permits repeated Power BI keys for aggregation but diagnoses repeated service keys. unmatchedPolicy controls no warning, one bounded summary, or detailed bounded diagnostics. Blank/invalid numeric inputs are excluded, empty sum|avg|min|max returns null, and aggregation diagnostics contain counts rather than rows. Computed class breaks cap effective classes by request, ramp, and distinct finite values, collapse repeated quantiles, and include the maximum explicitly. Runtime diagnostics use canonical RFC 6901 paths; Map Studio scopes selected-layer diagnostics by exact pointer/prefix.

Strict validation rejects unknown nested map properties and unimplemented naturalBreaks. Partial/experimental accepted properties emit capability limitations from the machine-readable registry. Maps require explicit layers; legacy top-level settings, map-specific style, and top-level popup are rejected. The complete contract, Map Studio behavior, capability table, and performance bounds are documented in Map services.

Analytical map additions

Map source discriminators are powerbi, geoJson, xyz, arcgisFeature, arcgisTile, and arcgisDynamic. Renderers include service, simple, uniqueValue, classBreaks, continuousColor, proportionalSize, cluster, heatmap, densityGrid, icon, line, and polygon.

tools.rectangleSelection, tools.lassoSelection, and tools.circleSelection accept Boolean or structured definitions with enabled and selectionMode: "replace"|"add"|"remove"|"toggle". tools.selection bounds selected features and submitted Power BI identities. Scale-bar and coordinate-display definitions are accepted operational tools.

Safe icon definitions are builtIn|svg|image; SVG is sanitized and image URLs are HTTPS/relative. Symbols support data-driven icon, rotation, size, color, marker text/badge, anchor/offset, line cap/join/dashes, selected/hover/external-highlight overrides, and dimmed opacity. Heatmaps use a real retained canvas renderer. Pixels are never selectable; interactivePoints can retain a transparent source hit layer.

Layer legends support categorical, class-break, continuous, size, icon, line, polygon, heat, and combined presentations; click filtering/highlight/selection; hover highlight; counts; percentages; aggregate values; labels; ordering; search; isolate/select-all/clear; and independent internal/external interaction gates. Quick filters support categorical, numeric/date ranges, text, null/not-null, top N, layer scope, filter-to-selected, and clear.

The exact schema, security constraints, and copyable JSON are in Analytical maps. Provider and service behavior remains in Map services.

SVG

svg requires viewBox and elements; svgMarkup requires svg. Both accept size/aspect/role/description/dataContext/motion/performance. Structured SVG elements, binding forms, animation enums, repeat behavior, sanitizer rules, and exact limits are documented in SVG visuals.

Security restrictions

HyperPBI JSON cannot provide JavaScript, functions, eval, event handlers, script/embed/iframe content, arbitrary network datasets, SQL, credentials, or AI keys. HTML, CSS, ECharts options, SVG, URLs, map hosts, and provider access each pass dedicated allowlists/policies. See Security.

Preparation and diagnostics

Preparation returns authoring JSON, a renderable schema only when no errors remain, structured diagnostics, text error/warning summaries, applied repair records, and resolved dataset schemas.

Common diagnostic families include invalid/unknown properties, unsupported version/type/enum, missing required properties, duplicate/invalid IDs, unknown/ambiguous fields, unknown dataset/source, dataset/definition cycles, invalid dataset operations/collisions, nonnumeric fields, invalid interactions/targets, reference errors, and SVG dashboard limits.

The optional non-runtime authoring repair helper is intentionally narrow:

• correct meausre→measure, catgory→category, componets→components, aggregration→aggregation
• convert numeric strings for span, height, width, limit, pageSize, maxRows, columns, and gap

Production loading, Edit Mode, AI import, preview, save, and renderer startup use strict preparation. They reject missing versions, missing IDs, comments, smart quotes, truncation, unknown types/fields, unsafe content, and ambiguous intent.

Schema 1.0 conversion

Schema 1.0 is not active runtime material. Visual loading, Edit Mode, AI import, validation/preview, save, renderer startup, and shared runtime modules reject it with a schema 2.0-only diagnostic.

Developers may explicitly convert a supported legacy file with npm run schema:migrate-v1 -- input.json output.json. The temporary converter is outside src, validates the converted schema 2.0 result, and is not part of PBIVIZ packages. See migration/versioning for the removed aliases and converter limitations.