Data visualization block

The data visualization block allows you to display data in line, bar, area, or pie chart format.

Fields

Field	Type	Description	Required?
`type`	String	The type of block. For a data visualization block, `type` is always `data_visualization`.	Required
`title`	String	A short label displayed above the chart. Maximum 50 characters.	Required
`chart`	Object	The chart-specific payload. Must be one of the following: `pie`, `bar`, `area`, or `line`.	Required
`block_id`	String	A unique identifier for a block. If not specified, a `block_id` will be generated.	Optional

Chart-specific fields

Pie

Field	Type	Description	Required?
`type`	String	The type of chart. In this case, `pie`.	Required
`segments`	array of Segment	Labeled slices that make up the pie. Min 1, max 6.	Required

Bar

Field	Type	Description	Required?
`type`	String	The type of chart. In this case, `bar`.	Required
`series`	array of Data Series	Series to plot as bar groups. Min 1, max 6. For multiple series, bars are grouped by label.	Required
`axis_config`	Axis Config	X-axis categories and axis titles.	Required

Area

Field	Type	Description	Required?
`type`	String	The type of chart. In this case, `area`.	Required
`series`	array of Data Series	Series to plot as filled areas. Min 1, max 6. Series are layered in array order (first at back).	Required
`axis_config`	Axis Config	X-axis categories and axis titles.	Required

Line

Field	Type	Description	Required?
`type`	String	The type of chart. In this case, `line`.	Required
`series`	array of Data Series	Series to plot as lines. Min 1, max 6.	Required
`axis_config`	Axis Config	X-axis categories and axis titles.	Required

Type fields

Segment

Field	Type	Description	Required?
`label`	String	Display name for this slice, shown in the legend and on hover. Maximum of 20 characters.	Required
`value`	number	Numeric weight of this slice. Must be greater than 0. Rendered percentage is the value divided by the sum of all segment values.	Required

Data Series

Field	Type	Description	Required?
`name`	String	Human-readable identifier displayed in the chart legend. Must be unique across all series in the same chart. Maximum 20 characters.	Required
`data`	array of Data Point	Ordered data points. Min 1, max 20. Must contain exactly one entry for every label in `axis_config.categories`.	Required

Data Point

Field	Type	Description	Required?
`label`	String	The x-axis category this point belongs to. Must match one of the values in axis_config.categories. Maximum of 20 characters.	Required
`value`	number	Numeric y-axis value. Negative values are permitted.	Required

Axis Config

Field	Type	Description	Required?
`categories`	array of strings	Category labels for the x-axis. Defines valid labels and their left-to-right display order. Each category label has a maximum of 20 characters.	Required
`x_label`	String	Descriptive title displayed below the x-axis (e.g., "Time of Day"). Maximum of 50 characters.	Optional
`y_label`	String	Descriptive title displayed beside the y-axis (e.g., "Latency (ms)"). Maximum of 50 characters.	Optional

Usage info

Validation rules (enforced at runtime)

Rule	Description
Label matching	Every `data_point.label` in every series must match a value in `axis_config.categories.` Series may not omit data points.
Unique series names	Each series within a chart must have a distinct name.
Category ordering	The order of `axis_config.categories` defines the x-axis display order.

Examples

A sample pie chart payload:

JSON

{
    "type": "data_visualization",
    "title": "My Favorite Candy Bars",
    "chart": {
        "type": "pie",
        "segments": [
            { "label": "Kit Kat", "value": 45 },
            { "label": "Twix", "value": 28 },
            { "label": "Crunch", "value": 18 },
            { "label": "Milky Way", "value": 9 }
        ]
    }
}

A sample bar chart payload:

JSON

{
    "type": "data_visualization",
    "title": "My Favorite Pies by Percentage of Tastiness",
    "chart": {
        "type": "bar",
        "series": [
            {
                "name": "Pies",
                "data": [
                    { "label": "Strawberry Rhubarb", "value": 85 },
                    { "label": "Pumpkin", "value": 70 },
                    { "label": "Lemon Meringue", "value": 72 },
                    { "label": "Blueberry", "value": 90 },
                    { "label": "Key Lime", "value": 56 },					
                ]
            }
        ],
        "axis_config": {
            "categories": ["Strawberry Rhubarb", "Pumpkin", "Lemon Meringue", "Blueberry", "Key Lime"],
            "x_label": "Pies",
            "y_label": "Percentage of Tastiness"
        }
    }
}

A sample area chart payload:

JSON

{
    "type": "data_visualization",
    "title": "Daily Active Users",
    "chart": {
        "type": "area",
        "series": [
            {
                "name": "Pied Piper Free Tier",
                "data": [
                    { "label": "Mon", "value": 12000 },
                    { "label": "Tues", "value": 13500 },
                    { "label": "Wed", "value": 15200 },
                    { "label": "Thurs", "value": 14800 },
                    { "label": "Fri", "value": 16400 }
                ]
            },
            {
                "name": "Pied Piper Paid Tier",
                "data": [
                    { "label": "Mon", "value": 4500 },
                    { "label": "Tues", "value": 4800 },
                    { "label": "Wed", "value": 5100 },
                    { "label": "Thurs", "value": 5600 },
                    { "label": "Fri", "value": 6200 }
                ]
            }
        ],
        "axis_config": {
            "categories": ["Mon", "Tues", "Wed", "Thur", "Fri"],
            "x_label": "Day",
            "y_label": "Users"
        }
    }
}

A sample line chart payload:

JSON

{
    "type": "data_visualization",
    "title": "Weekly Paper Sales",
    "chart": {
        "type": "line",
        "series": [
            {
                "name": "Dunder Mifflin Infinity Website",
                "data": [
                    { "label": "Week 1", "value": 32000 },
                    { "label": "Week 2", "value": 35000 },
                    { "label": "Week 3", "value": 29000 },
                    { "label": "Week 4", "value": 41000 },
                    { "label": "Week 5", "value": 45000 }
                ]
            },
            {
                "name": "Dunder Mifflin In-store",
                "data": [
                    { "label": "Week 1", "value": 32000 },
                    { "label": "Week 2", "value": 35000 },
                    { "label": "Week 3", "value": 29000 },
                    { "label": "Week 4", "value": 41000 },
                    { "label": "Week 5", "value": 45000 }
                ]
            }
        ],
        "axis_config": {
            "categories": ["Week 1", "Week 2", "Week 3", "Week 4", "Week 5"],
            "x_label": "Week",
            "y_label": "Paper Sales (USD)"
        }
    }
}

Fields​

Chart-specific fields​

Pie​

Bar​

Area​

Line​

Type fields​

Segment​

Data Series​

Data Point​

Axis Config​

Usage info​

Validation rules (enforced at runtime)​

Examples​