Chart definition JSON

The Chart content element is configured entirely from a single JSON string. That string is accepted by:

• AddChart(width, height, definition) : Creates a chart from a definition.

• SetDefinition(definition) : Replaces the definition of an existing chart.

Info

SetDefinition replaces the chart entirely. Any previously applied definition and derived styling is discarded. The chart width and height are not part of the definition and are preserved.

See Charts for the API that hosts these definitions.

Chart definition JSON example

JSON

{
    "chartType": "bar",
    "title": "Revenue by region (thousands CAD)",
    "theme": "nature",
    "data": {
        "categories": { "data": ["Q1", "Q2", "Q3", "Q4"] },
        "series": [
            { "name": { "data": ["North America"] }, "data": { "data": [1250, 1410, 1580, 1720] } },
            { "name": { "data": ["Europe"] },        "data": { "data": [910, 980, 1120, 1180] } },
            { "name": { "data": ["Asia Pacific"] },  "data": { "data": [640, 720, 905, 1010] } }
        ]
    }
}

Definition structure

The definition is a JSON object. All members are optional; anything omitted keeps its default.

Member	Type	Description
chartType	string	Chart family. One of bar, pie, radar. Case insensitive. Default is bar.
title	string	Chart title, rendered above the plot area.
theme	string	Named color palette applied to the series. See Themes.
data	object	Categories and data series. See Data.

Value ranges

Most leaf values in a chart definition are not plain arrays, but range objects. A range object carries the literal values and, optionally, a spreadsheet-style reference.

Member	Type	Description
data	array	The literal values.
ref	string	Optional source range reference, retained as metadata so the chart can be re-linked to a spreadsheet. Ignored when rendering.

{ "data": [1250, 1410, 1580], "ref": "Sheet1!$B$2:$D$2" }

This wrapper is used for categories, series name, data, dataDomain, markerSize, and labels.

Data

The data object holds the category axis values and the list of series.

Member	Type	Description
categories	range of strings	Labels for the category axis, shared by all series.
series	array of objects	One entry per data series. See Series.

Series

Each element of series is an object.

Member	Type	Description
name	range of strings	The series name, taken from the first array element. Used in the legend.
data	range of numbers	The series values, one per category.
dataDomain	range of numbers	Explicit X values, for scatter-style data where categories are not evenly spaced.
markerSize	range of numbers	Per-point marker sizes, producing a bubble-style rendering.
labels	range of strings	Explicit per-point data labels, overriding the formatted values.
showLabels	bool	Show data labels for every point of the series.
line	bool	Render the series as a line instead of columns. Radar series are always lines.
trendlineType	string	Adds a trendline. See Trendlines. Bar/Column series only.
showTrendlineEq	bool	Display the fitted equation next to the trendline.

Series are matched to the existing chart series by their index in the array, which makes it possible to update only the data of an already configured chart.

Chart types

Chart types include:

• Bar

• Pie

• Radar

Bar

The default family: a clustered column chart with a category axis and a value axis, gridlines, and a legend at the bottom. Individual series can be switched to lines with "line": true, which lets you mix columns and lines in one chart.

Pie

A single-series proportional chart. When the definition creates more than one series, a doughnut hole is applied automatically.

JSON

{
    "chartType": "pie",
    "title": "Support tickets by category",
    "theme": "sunset",
    "data": {
        "categories": { "data": ["Billing", "Installation", "Bugs", "Other"] },
        "series": [
            { "name": { "data": ["Tickets"] }, "data": { "data": [340, 210, 480, 95] } }
        ]
    }
}

Radar

A polar chart where every category is an axis radiating from the center. Radar series are always rendered as lines, which makes this type well suited to scorecards and comparisons across several dimensions.

JSON

{
    "chartType": "radar",
    "title": "Product scorecard",
    "theme": "vivid",
    "data": {
        "categories": { "data": ["Speed", "Quality", "Price", "Support", "Docs"] },
        "series": [
            { "name": { "data": ["Current"] },  "data": { "data": [8, 9, 6, 7, 8] } },
            { "name": { "data": ["Previous"] }, "data": { "data": [6, 7, 7, 5, 6] } }
        ]
    }
}

Themes

theme selects a palette that is applied to the series in order, cycling through eight colors. Values are case insensitive.

Theme	Palette
pastel	Soft pinks, peaches, mints and lavenders.
grayscale	Neutral grays, from near-black to near-white.
vivid	Saturated spectrum colors.
nature	Greens, olives and khakis.
sunset	Corals, ambers and deep purples.

If theme is omitted, the default series palette is used. Fill colors of column and pie series are applied with slight transparency, while line series use the palette color at full opacity.

Trendlines

Setting trendlineType on a bar/column series fits a curve through the data and draws it as a dashed line in a translucent variant of the series color. The trendline is named "<series name> (Trend)" in the legend.

Value	Fit
Exp	Exponential
Linear	Least-squares straight line
Log	Logarithmic
MovingAvg	Moving average
Poly	Polynomial
Power	Power law

Values are matched case insensitively. Set "showTrendlineEq": true to print the fitted equation on the chart.

JSON

{
    "chartType": "bar",
    "title": "Monthly active users",
    "theme": "pastel",
    "data": {
        "categories": { "data": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"] },
        "series": [
            {
                "name": { "data": ["Users"] },
                "data": { "data": [120, 160, 150, 210, 260, 290] },
                "line": true,
                "showLabels": true,
                "trendlineType": "Linear",
                "showTrendlineEq": true
            }
        ]
    }
}

Using a definition from code

A complete definition is just a JSON object, so build it with your JSON library of choice and pass the serialized result to the chart API.

{
  "chartType": "pie",
  "title": "Support tickets by category",
  "theme": "sunset",
  "data": {
    "categories": { "data": ["Billing", "Installation", "Bugs", "Other"] },
    "series": [
      { "name": { "data": ["Tickets"] }, "data": { "data": [340, 210, 480, 95] } }
    ]
  }
}

See Charts for the code that adds a chart in each supported language, along with sizing and replacement semantics.

Notes and troubleshooting

• The definition must be a JSON object. A definition that is not a JSON object, or that is malformed, raises an exception.

• Unknown members are ignored, so definitions can carry extra metadata safely.

• Series values should align with categories. A series with fewer values than categories simply leaves the remaining categories empty.

• Chart size lives in the API, not the JSON. Use AddChart(width, height, ...) or SetWidth and SetHeight.

• Sizes are in points (1/72 inch), consistent with the rest of the document creation API.

Further Reading

Charts for the Chart API that hosts these definitions.