@microsoft/powerbi-core-visual-schema

Static visual capabilities catalog, VCO (Visual Container Object) catalog, and instance selector catalog for Power BI report authoring. All metadata is precomputed at build time and shipped as JSON inside the package, so lookups are local, synchronous, and have zero runtime dependencies.

💡 What can you do?

• 📋 Enumerate visual types — list every registered Power BI visual identifier (e.g. barChart, lineChart, card, actionButton)
• 🔍 Look up visual capabilities — retrieve a visual's data roles, formatting objects, behavioral flags (selection, highlight, keyboard focus, …) and more
• 🧩 Inspect VCOs — browse the shared container-level formatting objects (title, subTitle, background, border, dropShadow, padding, …) along with each one's properties and types
• 🎯 Look up instance selectors — discover which visuals (and non-visual elements like filterCard) expose state-keyed formatting buckets (default/hover/selected/disabled/…) and which formatting objects each state applies to

📦 Installation

npm install @microsoft/powerbi-core-visual-schema
# or
pnpm add @microsoft/powerbi-core-visual-schema

The package is ESM-only (Node ≥ 20.10) and ships full TypeScript types.

🚀 Quick start

import {
    // Visual catalog
    listVisualTypes,
    getCapabilities,

    // VCO catalog
    listVcoKeys,
    getVcoCapabilities,

    // Instance selector catalog
    listInstanceSelectorKeys,
    getInstanceSelectors,
    getSelectorHints,
} from '@microsoft/powerbi-core-visual-schema';

// 1. All visual types
const types = listVisualTypes();
// → ['actionButton', 'areaChart', 'barChart', 'card', ...]  (~55 entries)

// 2. Full capabilities for one visual
const lineChart = getCapabilities('lineChart');
// → { dataRoles: [...], objects: { dataPoint: {...}, ... }, ... } | undefined

// 3. All visual container objects
const vcoKeys = listVcoKeys();
// → ['title', 'subTitle', 'divider', 'background', 'border', 'dropShadow', ...]

const titleVco = getVcoCapabilities('title');
// → { displayName: 'Title', properties: { show: {...}, text: {...}, fontColor: {...} } }

// 4. Instance selector catalog
const selectorKeys = listInstanceSelectorKeys();
// → ['actionButton', 'advancedSlicer', 'bookmarkNavigator', 'cardVisual',
//    'filterCard', 'pageNavigator', 'pivotTable', 'shape']

const buttonSelectors = getInstanceSelectors('actionButton');
// → { fill: ['default','hover','selected','disabled'], outline: [...], text: [...], ... }

const filterCardSelectors = getInstanceSelectors('filterCard');
// → { filterCard: ['Available', 'Applied'] }

const hints = getSelectorHints('actionButton', ['fill', 'text']);
// → [
//     { objectName: 'fill', selectorIds: ['default','hover','selected','disabled'] },
//     { objectName: 'text', selectorIds: ['default','hover','selected','disabled'] },
//   ]

🛠️ Public API

All exports come from the package root.

Visual capabilities

| Export | Returns | Description | |---|---|---| | listVisualTypes() | string[] | Sorted list of all registered visual type identifiers | | getCapabilities(visualType) | VisualCapabilities \| undefined | Full capabilities descriptor, or undefined if not registered |

Image-typed visual properties expose the serialized ImageDefinition value shape under type.image.subProperties:

const imageProperty = getCapabilities('actionButton')?.objects?.fill.properties.image;
const imageSubProperties = imageProperty?.type?.image?.subProperties;
// → {
//     name: { type: 'expr', required: true },
//     url: { type: 'expr', required: true },
//     scaling: { type: 'expr', required: false },
//   }

VCO catalog (Visual Container Objects)

| Export | Returns | Description | |---|---|---| | listVcoKeys() | string[] | All registered VCO object names | | getVcoCapabilities(name) | VcoCatalogEntry \| undefined | Full descriptor for one VCO, or undefined if not registered |

Instance selectors

| Export | Returns | Description | |---|---|---| | listInstanceSelectorKeys() | string[] | Sorted list of every instance-selector key (visuals and non-visual elements like filterCard) | | getInstanceSelectors(key) | VisualSelectorMap \| undefined | Map of objectName → state IDs[], or undefined if not registered | | getSelectorHints(key, names) | SelectorHint[] | Convenience: hints only for the requested object names |

Note: All get* functions return undefined for unknown identifiers — no exceptions are thrown for missing data. This keeps consumer code simple (no try/catch noise).

Types

import type {
    // Visual capabilities
    VisualType,
    VisualCapabilities,
    CapabilitiesByVisualType,
    DataRoleDescriptor,
    DataRoleKind,
    CartesianKind,
    ObjectDescriptor,
    ObjectPropertyDescriptor,
    PropertyTypeDescriptor,
    EnumMember,
    ImageSubPropertyDescriptor,
    ImageTypeDescriptor,

    // VCOs
    VcoKey,
    VcoCatalog,
    VcoCatalogEntry,
    VcoProperty,
    VcoPropertyType,
    VcoEnumMember,

    // Instance selectors
    InstanceSelectorCatalog,
    VisualSelectorMap,
    SelectorHint,
} from '@microsoft/powerbi-core-visual-schema';

📁 Package contents

@microsoft/powerbi-core-visual-schema/
├── index.{js,d.ts}                  # Public API
├── lib/
│   ├── visual-catalog.{js,d.ts}     # listVisualTypes, getCapabilities
│   ├── vco-catalog.{js,d.ts}        # listVcoKeys, getVcoCapabilities
│   └── instance-selectors.{js,d.ts} # listInstanceSelectorKeys, getInstanceSelectors, getSelectorHints
├── types/index.d.ts                 # All public type definitions
└── data/
    ├── capabilities.json            # ~55 visuals, ~850 KB
    ├── vco-capabilities.json        # 15 VCOs, ~18 KB
    └── instance-selectors.json      # 8 selector keys, ~3 KB

🧠 Three independent catalogs

The package exposes three orthogonal catalogs because the underlying data is genuinely orthogonal:

• Visual capabilities describe what a chart/visual can do: which data roles it accepts, which formatting objects it has, whether it supports highlight/selection/etc.
• VCO descriptors describe the container chrome that wraps every visual (title, background, border, …) — these properties live one level above the visual.
• Instance selectors describe state-keyed formatting buckets for elements that have multiple variants of the same property (e.g. an action button has different fill colors for default/hover/selected/disabled). Most selector keys are visual identifiers, but some are non-visual chrome elements like filterCard.

Each catalog is queried independently, so consumers can pick the right one for the question they're asking.