Chart config schema¶

Schema version 011 — the canonical JSON Schema is published at grapher-schema.011.json.

Our World In Data grapher configuration. Most of the fields can be left empty and will be filled with reasonable default values.

In a persisted config, only $schema and dimensions are required; every other field is optional, with defaults listed below where the schema defines one. Unknown properties are rejected.

Core¶

Identity of the chart and the schema it validates against.

$schema¶

Type: string · Must be "https://files.ourworldindata.org/schemas/grapher-schema.011.json" · Required

Url of the concrete schema version to use to validate this document

id¶

Type: integer · Minimum: 0

Internal database id

version¶

Type: integer · Minimum: 0

Chart config version

slug¶

Type: string

Slug of the chart on Our World In Data

isPublished¶

Type: boolean

Indicates if the chart is published on Our World In Data or still in draft

Text and metadata¶

Everything that ends up as text in the chart header and footer.

title¶

Type: string

Big title text of the chart

subtitle¶

Type: string

The longer subtitle text to show beneath the title

note¶

Type: string

Note displayed in the footer of the chart

sourceDesc¶

Type: string

Short comma-separated list of source names

originUrl¶

Type: string

The page containing this chart where more context can be found

license¶

Type: string · Default: "cc-by"

The license the chart is published under, linked in the chart footer

Values: "cc-by", "cc-by-sa", "cc-by-nc", "cc-by-nc-sa", "cc-by-nd", "cc-by-nc-nd"

internalNotes¶

Type: string

Additional text used internally to differentiate charts with the same title

variantName¶

Type: string

Optional internal variant name for distinguishing charts with the same title

entityType¶

Type: string · Default: "country or region"

Display string for naming the primary entities of the data. The default is 'country or region', but you can specify a different one such as 'state' or 'region'

entityTypePlural¶

Type: string · Default: "countries and regions"

Plural of the entity type (i.e. when entityType is 'country' this would be 'countries')

facettingLabelByYVariables¶

Type: string · Default: "metric"

Display string that replaces 'metric' in the 'Split by metric' label in facet controls (e.g. 'product' displays 'Split by product')

hideAnnotationFieldsInTitle¶

Type: object

Whether to hide any automatically added title annotations like the selected year

hideAnnotationFieldsInTitle.entity¶

Type: boolean · Default: false

Whether to hide the entity annotation

hideAnnotationFieldsInTitle.time¶

Type: boolean · Default: false

Whether to hide the time annotation

hideAnnotationFieldsInTitle.changeInPrefix¶

Type: boolean · Default: false

Whether to hide "Change in" in relative line charts

relatedQuestions¶

Type: object[] · Default: []

Links to related questions

relatedQuestions[].url¶

Type: string

relatedQuestions[].text¶

Type: string

Data and dimensions¶

Which indicators the chart plots, and how their values are formatted.

dimensions¶

Type: object[] · Required

List of dimensions and their mapping to variables

dimensions[].targetYear¶

Type: integer

Charts that can display more than one primary dimensions (i.e. scatter and marimekko) sometimes need to "hardcode" one dimension to a specific year. This happens e.g. when mixing a daily X variable in a scatter plot with a yearly one, e.g. population.

dimensions[].property¶

Type: string · Required

Which dimension this property maps to

Values: "y", "x", "size", "color", "table"

dimensions[].display¶

Type: object

dimensions[].display.isProjection¶

Type: boolean · Default: false

Indicates if this time series is a forward projection (if yes then this is rendered differently in e.g. line charts)

dimensions[].display.plotMarkersOnlyInLineChart¶

Type: boolean · Default: false

Indicates if data points should be connected with a line in a line chart

dimensions[].display.name¶

Type: string

The display string for this variable

dimensions[].display.description¶

Type: string

Variable description

dimensions[].display.tableDisplay¶

Type: object

Configuration for the table sheet for this variable

dimensions[].display.tableDisplay.hideAbsoluteChange¶

Type: boolean · Default: false

dimensions[].display.tableDisplay.hideRelativeChange¶

Type: boolean · Default: false

dimensions[].display.tolerance¶

Type: integer · Default: 0 · Minimum: 0

Tolerance to use. If data points are missing for a time point, a match is accepted if it lies within the specified time period. The unit is the dominating time unit, either years or days.

dimensions[].display.entityAnnotationsMap¶

Type: string

Entity annotations

dimensions[].display.timeInterval¶

Type: string · Default: "year"

Resolution at which the time values should be interpreted and formatted.

Values: "day", "week", "month", "quarter", "year", "decade"

dimensions[].display.color¶

Type: string

Default color for this time series

dimensions[].display.includeInTable¶

Type: boolean · Default: true

Whether to render this time series in the table sheet

dimensions[].display.shortUnit¶

Type: string

Short unit symbol - This is used in tight UI spaces when the value is shown

dimensions[].display.conversionFactor¶

Type: number

Conversion factor to apply before showing values

dimensions[].display.unit¶

Type: string

Long unit text - This is shown in the UI when there is more space (e.g. tooltips) after values

dimensions[].display.roundingMode¶

Type: string · Default: "decimalPlaces"

Rounding strategy to use. Supported are rounding to a fixed number of decimals and rounding to significant figures. If 'decimalPlaces' is selected, then 'numDecimalPlaces' is used. If 'significantFigures' is selected, then 'numSignificantFigures' is used.

Values: "decimalPlaces", "significantFigures"

dimensions[].display.numDecimalPlaces¶

Type: integer · Default: 2 · Minimum: 0

Number of decimal places to show

dimensions[].display.numSignificantFigures¶

Type: integer · Default: 3 · Minimum: 1

Number of significant figures to show

dimensions[].display.zeroDay¶

Type: string · Default: "2020-01-21"

Iso date day string used as the reference date for day-encoded values

dimensions[].variableId¶

Type: integer · Minimum: 0 · Required

The variable id to get the values for this time series

Chart types and tabs¶

chartTypes¶

Type: string[] · Default: ["LineChart","DiscreteBar"]

Which chart types should be shown

Values: "LineChart", "ScatterPlot", "StackedArea", "DiscreteBar", "StackedDiscreteBar", "SlopeChart", "StackedBar", "Marimekko", "Dumbbell"

tab¶

Type: string · Default: "chart"

The tab that is shown initially

Values: "chart", "map", "table", "line", "slope", "discrete-bar", "marimekko", "scatter", "stacked-area", "stacked-bar", "stacked-discrete-bar", "dumbbell"

hasMapTab¶

Type: boolean · Default: false

Indicates if the map tab should be shown

Entity selection¶

Which entities (usually countries or regions) are shown, and how readers can change that selection.

selectedEntityNames¶

Type: string[] · Default: []

The initial selection of entities

focusedSeriesNames¶

Type: string[] · Default: []

The initially focused chart elements. Is either a list of entity or variable names. Only works for line and slope charts for now.

includedEntityNames¶

Type: string[] · Default: []

Entities that should be included (opposite of excludedEntityNames). If empty, all available entities are used. If set, all entities not specified here are excluded. excludedEntityNames are evaluated afterwards and can still remove entities even if they were included before.

excludedEntityNames¶

Type: string[] · Default: []

Entities that should be excluded (opposite of includedEntityNames)

inapplicableEntityNames¶

Type: string[] · Default: []

Entities the indicator's data can't apply to by construction, e.g. Mexico for "Where do Mexican emigrants live?". On the map, they are excluded from the color scale and rendered in a dedicated pattern.

selectedEntityColors¶

Type: object

Colors for selected entities

Keys can be any string; values are of type string.

addCountryMode¶

Type: string · Default: "add-country"

Whether the user can change countries, add additional ones or neither

Values: "add-country", "change-country", "disabled"

peerCountryStrategy¶

Type: string

Strategy for selecting peer countries for comparison

• "defaultSelection": Use the chart's default selection as peers
• "parentRegions": Use the containing continent, income group, and World as peers
• "gdpPerCapita": Use countries with similar GDP per capita as peers
• "population": Use countries with similar population as peers
• "dataRange": Use countries that represent the data range as peers
• "neighbors": Use neighboring countries as peers
• "none": Don't automatically add peer countries (useful in search)

Values: "defaultSelection", "parentRegions", "gdpPerCapita", "population", "dataRange", "neighbors", "none"

matchingEntitiesOnly¶

Type: boolean · Default: false

Exclude entities that do not belong in any color group

missingDataStrategy¶

Type: string · Default: "auto"

The desired strategy for handling entities with missing data

Values: "auto", "hide", "show"

zoomToSelection¶

Type: boolean · Default: false

Whether to zoom to the selected data points

Time¶

Time fields accept a number, or the strings "earliest" and "latest".

minTime¶

Type: number | "latest" | "earliest" · Default: "earliest"

Start point of the initially selected time span.

maxTime¶

Type: number | "latest" | "earliest" · Default: "latest"

End point of the initially selected time span.

timelineMinTime¶

Type: number | "earliest" · Default: "earliest"

The lowest year to show in the timeline. If this is set then the user is not able to see any data before this year. If set to "earliest", then the earliest year in the data is used.

timelineMaxTime¶

Type: number | "latest" · Default: "latest"

The highest year to show in the timeline. If this is set then the user is not able to see any data after this year. If set to "latest", then the latest year in the data is used.

hideTimeline¶

Type: boolean · Default: false

Whether to hide the timeline from the user. If it is hidden then the user can't change the time

Axes¶

xAxis and yAxis have the same shape.

xAxis¶

Type: object

xAxis.removePointsOutsideDomain¶

Type: boolean · Default: false

Whether to remove data points that fall outside the axis domain

xAxis.label¶

Type: string

Axis label

xAxis.min¶

Type: number | "auto"

Minimum domain value of the axis. Inferred from data if set to "auto". Usually defaults to "auto", but defaults to 0 for line and slope charts on the y-axis.

xAxis.scaleType¶

Type: string · Default: "linear"

Toggle linear/logarithmic

Values: "linear", "log"

xAxis.max¶

Type: number | "auto" · Default: "auto"

Maximum domain value of the axis. Inferred from data if set to "auto".

xAxis.canChangeScaleType¶

Type: boolean · Default: false

Allow user to change lin/log

xAxis.facetDomain¶

Type: string · Default: "shared"

Whether the axis domain should be the same across faceted charts (if possible)

Values: "independent", "shared"

yAxis¶

Type: object

yAxis.removePointsOutsideDomain¶

Type: boolean · Default: false

Whether to remove data points that fall outside the axis domain

yAxis.label¶

Type: string

Axis label

yAxis.min¶

Type: number | "auto"

Minimum domain value of the axis. Inferred from data if set to "auto". Usually defaults to "auto", but defaults to 0 for line and slope charts on the y-axis.

yAxis.scaleType¶

Type: string · Default: "linear"

Toggle linear/logarithmic

Values: "linear", "log"

yAxis.max¶

Type: number | "auto" · Default: "auto"

Maximum domain value of the axis. Inferred from data if set to "auto".

yAxis.canChangeScaleType¶

Type: boolean · Default: false

Allow user to change lin/log

yAxis.facetDomain¶

Type: string · Default: "shared"

Whether the axis domain should be the same across faceted charts (if possible)

Values: "independent", "shared"

Colors¶

baseColorScheme¶

Type: string

One of the predefined base color schemes. If not provided, a default is automatically chosen based on the chart type.

invertColorScheme¶

Type: boolean · Default: false

Reverse the order of colors in the color scheme

colorScale¶

Type: object

Color scale definition

colorScale.customNumericLabels¶

Type: (string | null)[]

Custom labels for each numeric bin. Only applied when strategy is manual. null falls back to default label.

colorScale.customCategoryColors¶

Type: object

Map of categorical values to colors. Colors are CSS colors, usually in the form #aa9944

Keys can be any string; values are of type string.

colorScale.baseColorScheme¶

Type: string

One of the predefined base color schemes. If not provided, a default is automatically chosen based on the chart type.

colorScale.customHiddenCategories¶

Type: object

Allow hiding categories from the legend

Keys can be any string; values are of type boolean.

colorScale.binningStrategy¶

Type: string · Default: "auto"

The strategy for generating the bin boundaries

Values: "manual", "auto", "log-auto", "log-1-2-5", "log-1-3", "log-10", "equalSizeBins-few-bins", "equalSizeBins-normal", "equalSizeBins-many-bins", "equalSizeBins-percent"

colorScale.minValue¶

Type: number

Minimum value of the color scale, for automated binning.

colorScale.maxValue¶

Type: number

Maximum value of the color scale, for automated binning.

colorScale.midpoint¶

Type: number · Default: 0

Midpoint value for the color scale, for automated binning around the midpoint.

colorScale.midpointMode¶

Type: string

How to handle the midpoint when generating bins. Undefined means automatically choosing between 'none' and 'symmetric'.

Values: "none", "symmetric", "same-num-bins", "asymmetric"

colorScale.createBinForMidpoint¶

Type: boolean · Default: false

Whether to create a separate bin that only contains the midpoint value.

colorScale.legendDescription¶

Type: string

A custom legend description. Only used in ScatterPlot legend titles for now.

colorScale.customNumericColors¶

Type: (string | null)[]

Override some or all colors for the numerical color legend. Colors are CSS colors, usually in the form #aa9944 null falls back the color scheme color.

colorScale.customNumericValues¶

Type: number[]

Custom maximum brackets for each numeric bin. Only applied when strategy is manual

colorScale.customNumericColorsActive¶

Type: boolean · Default: false

Whether customNumericColors are used to override the color scheme

colorScale.colorSchemeInvert¶

Type: boolean · Default: false

Reverse the order of colors in the color scheme

colorScale.customCategoryLabels¶

Type: object

Map of category values to color legend labels.

Keys can be any string; values are of type string.

Map¶

map¶

Type: object

Configuration of the world map chart

map.region¶

Type: string · Default: "World"

Which region to focus on

Values: "World", "Europe", "Africa", "Asia", "NorthAmerica", "SouthAmerica", "Oceania"

map.hideTimeline¶

Type: boolean · Default: false

Whether the timeline should be hidden in the map view and thus the user not be able to change the year

map.colorScale¶

Type: object

Color scale definition

map.colorScale.customNumericLabels¶

Type: (string | null)[]

Custom labels for each numeric bin. Only applied when strategy is manual. null falls back to default label.

map.colorScale.customCategoryColors¶

Type: object

Map of categorical values to colors. Colors are CSS colors, usually in the form #aa9944

Keys can be any string; values are of type string.

map.colorScale.baseColorScheme¶

Type: string

One of the predefined base color schemes. If not provided, a default is automatically chosen based on the chart type.

map.colorScale.customHiddenCategories¶

Type: object

Allow hiding categories from the legend

Keys can be any string; values are of type boolean.

map.colorScale.binningStrategy¶

Type: string · Default: "auto"

The strategy for generating the bin boundaries

Values: "manual", "auto", "log-auto", "log-1-2-5", "log-1-3", "log-10", "equalSizeBins-few-bins", "equalSizeBins-normal", "equalSizeBins-many-bins", "equalSizeBins-percent"

map.colorScale.minValue¶

Type: number

Minimum value of the color scale, for automated binning.

map.colorScale.maxValue¶

Type: number

Maximum value of the color scale, for automated binning.

map.colorScale.midpoint¶

Type: number · Default: 0

Midpoint value for the color scale, for automated binning around the midpoint.

map.colorScale.midpointMode¶

Type: string

How to handle the midpoint when generating bins. Undefined means automatically choosing between 'none' and 'symmetric'.

Values: "none", "symmetric", "same-num-bins", "asymmetric"

map.colorScale.createBinForMidpoint¶

Type: boolean · Default: false

Whether to create a separate bin that only contains the midpoint value.

map.colorScale.legendDescription¶

Type: string

A custom legend description. Only used in ScatterPlot legend titles for now.

map.colorScale.customNumericColors¶

Type: (string | null)[]

Override some or all colors for the numerical color legend. Colors are CSS colors, usually in the form #aa9944 null falls back the color scheme color.

map.colorScale.customNumericValues¶

Type: number[]

Custom maximum brackets for each numeric bin. Only applied when strategy is manual

map.colorScale.customNumericColorsActive¶

Type: boolean · Default: false

Whether customNumericColors are used to override the color scheme

map.colorScale.colorSchemeInvert¶

Type: boolean · Default: false

Reverse the order of colors in the color scheme

map.colorScale.customCategoryLabels¶

Type: object

Map of category values to color legend labels.

Keys can be any string; values are of type string.

map.timeTolerance¶

Type: integer · Minimum: 0

Tolerance to use. If data points are missing for a time point, a match is accepted if it lies within the specified time period. The unit is the dominating time unit, usually years but can be days for daily time series. If not provided, the tolerance specified in the metadata of the indicator is used. If that's not specified, 0 is used.

map.toleranceStrategy¶

Type: string · Default: "closest"

Tolerance strategy to use. Options include accepting matches that are "closest" to the time point in question (going forwards and backwards in time), and accepting matches that lie in the past ("backwards") or the future ("forwards").

Values: "closest", "forwards", "backwards"

map.tooltipUseCustomLabels¶

Type: boolean · Default: false

Show the label from colorSchemeLabels in the tooltip instead of the numeric value

map.time¶

Type: number | "latest" | "earliest" · Default: "latest"

Select a specific time to be displayed. If startTime is given, this acts as the end time.

map.startTime¶

Type: number | "latest" | "earliest"

Select a specific start time to be displayed. If given, two maps are shown next to each other.

map.columnSlug¶

Type: string

Column to show in the map tab. Can be a column slug (e.g. in explorers) or a variable ID (as string). If not provided, the first y dimension is used.

map.selectedEntityNames¶

Type: string[] · Default: []

The initial selection of entities to show on the map

map.globe¶

Type: object

Configuration of the globe

map.globe.isActive¶

Type: boolean

Whether the globe is initially shown

map.globe.rotation¶

Type: number[]

Latitude and Longitude of the globe rotation

map.globe.zoom¶

Type: number

Zoom level of the globe

Dumbbell charts¶

dumbbell¶

Type: object

Configuration of the dumbbell chart

dumbbell.connectorStyle¶

Type: string · Default: "arrow"

How the connector between dumbbell heads is drawn.

• arrow: draw an arrow pointing from start to end
• line: draw a simple line (only respected when two indicators are plotted)

Values: "arrow", "line"

dumbbell.valueLabelMode¶

Type: string · Default: "absolute"

What to display as value labels next to each dumbbell.

• absolute: show the raw values at the start and end
• change: show the absolute change (e.g. +50)
• percentChange: show the percentage change (e.g. +33%)
• none: hide value labels

Values: "absolute", "change", "percentChange", "none"

dumbbell.trendColorMap¶

Type: object

Custom colors for the time-range encoding

dumbbell.trendColorMap.increase¶

Type: string

Color for dumbbells whose value increased over time

dumbbell.trendColorMap.decrease¶

Type: string

Color for dumbbells whose value decreased over time

Sorting, stacking and faceting¶

sortBy¶

Type: string · Default: "total"

Sort criterion (used by discrete bar, stacked discrete bar, marimekko, and dumbbell charts).

• column: sort by the value of a specific column, identified by sortColumnSlug
• total: sort by the total across all columns
• entityName: sort alphabetically by entity name
• custom: preserve the specified entity order
• change: sort by the change between the start and end values (dumbbell charts only)
• startValue: sort by the start value (dumbbell charts only)
• endValue: sort by the end value (dumbbell charts only)

Values: "column", "total", "entityName", "custom", "change", "startValue", "endValue"

sortOrder¶

Type: string · Default: "desc"

Sort order

Values: "desc", "asc"

sortColumnSlug¶

Type: string

Sort column if sortBy is column

stackMode¶

Type: string · Default: "absolute"

Stack mode. Only absolute and relative are actively used.

Values: "absolute", "relative"

selectedFacetStrategy¶

Type: string · Default: "none"

The desired facetting strategy (none for no facetting)

Values: "none", "entity", "metric"

Display and interaction¶

logo¶

Type: string · Default: "owid"

Which logo to show on the upper right side

Values: "owid", "core+owid", "gv+owid"

hideLogo¶

Type: boolean · Default: false

Whether to hide the logo

hideSeriesLabels¶

Type: boolean · Default: false

Whether to hide the inline series labels drawn at the end of each series. Applies to line, slope, and stacked area charts

hideRelativeToggle¶

Type: boolean · Default: true

Whether to hide the relative mode UI toggle

hideFacetControl¶

Type: boolean · Default: true

Whether to hide the faceting control

hideTotalValueLabel¶

Type: boolean · Default: false

Whether to hide the total value label (used on stacked discrete bar charts)

hideConnectedScatterLines¶

Type: boolean · Default: false

Whether to hide connecting lines on scatter plots when a time range is selected

hideScatterLabels¶

Type: boolean · Default: false

Hide entity names in Scatter plots

showYearLabels¶

Type: boolean · Default: false

Whether to show year labels in bar charts

showNoDataArea¶

Type: boolean · Default: true

Whether to show an area for entities that have no data (used in marimekko charts)

compareEndPointsOnly¶

Type: boolean · Default: false

Drops in between points in scatter plots

scatterPointLabelStrategy¶

Type: string · Default: "year"

When a user hovers over a connected series line in a ScatterPlot we show a label for each point. By default that value will be from the "year" column but by changing this option the column used for the x or y axis could be used instead.

Values: "x", "y", "year"

comparisonLines¶

Type: object[] · Default: []

List of comparison lines to draw

Each entry is one of:

Comparison line of arbitrary shape defined by a formula. Defaults to yEquals = x if not specified

• label (string)
• yEquals (string)

Vertical comparison line drawn at a specific x-value

• label (string)
• xEquals (number, required)