Chart Editing

Edit .chart.yml files that define OWID Grapher chart configurations, then preview changes.

File Locations

• Chart configs: etl/steps/graph/<namespace>/<version>/<short_name>.chart.yml

• Schema: schemas/chart-schema.json (read this to understand valid fields)

• DAG definitions: dag/graph/<namespace>.yml (maps graph steps to data dependencies)

Before Editing

• Read the schema at schemas/chart-schema.json to understand all valid fields, enums, and nested structures

• Read the target .chart.yml to understand current config

• Check the DAG in dag/graph/<namespace>.yml to understand which dataset the chart depends on

Chart Config Formats

Simple format (single indicator)

Used for charts with one indicator and no dimension toggles:

title: Which countries have banned chick culling? tab: map hasMapTab: true chartTypes: [] yAxis: min: auto map: hideTimeline: true colorScale: customCategoryColors: Banned: '#4881c6' No laws: '#b6a28c' customNumericColorsActive: true $schema: https://files.ourworldindata.org/schemas/grapher-schema.010.json originUrl: /animal-welfare dimensions:

• property: y catalogPath: status

Key fields: dimensions[].property (y/x/size/color) and dimensions[].catalogPath (column name in the dataset).

Multi-dimensional format (explorer-like)

Used for charts with multiple indicator combinations selectable via dropdowns:

slug: covid/covid#covid_cases

definitions: common_views: - config: tab: map originUrl: ourworldindata.org/coronavirus

title: title: COVID-19 confirmed cases title_variant: ""

default_selection:

• World
• Europe
• Asia

topic_tags:

• COVID-19

dimensions:

• slug: period name: Period choices:

  • slug: weekly name: Weekly
  • slug: biweekly name: Biweekly

• slug: metric name: Indicator choices:

  • slug: absolute name: Absolute number
  • slug: per_capita name: Per million people

views:

• dimensions: period: weekly metric: absolute indicators: y: - catalogPath: weekly_cases

• dimensions: period: weekly metric: per_capita indicators: y: - catalogPath: weekly_cases_per_million

Key differences from simple: title is an object {title, title_variant} , dimensions defines UI facets (not indicators), actual indicators are in views[].indicators.y[].catalogPath .

Previewing Charts

Charts are previewed via the staging server. The staging URL follows this pattern:

http://staging-site-{branch}/grapher/{slug}

where {branch} is the current git branch name (with /._ replaced by - , truncated to 28 chars).

PNG screenshot (for visual inspection)

Fetch the PNG directly from the staging server using WebFetch :

http://staging-site-{branch}/grapher/{slug}.png?nocache

Add &tab=map or &tab=chart to control which tab is shown.

Prerequisite: The chart must be pushed to staging first. If the user has the VSCode chart preview extension open, this happens automatically via etlr --watch . Otherwise push manually:

.venv/bin/etlr graph://<namespace>/<version>/<slug> --graph --graph-push --private

Editing Workflow

• Read the chart file and schema

• Make edits using the Edit tool (preserve YAML comments with ruamel if needed)

• Push to staging: .venv/bin/etlr graph://<namespace>/<version>/<slug> --graph --graph-push --private

• Fetch the PNG from http://staging-site-{branch}/grapher/{slug}.png?nocache to verify visually

• If the chart looks wrong, read the schema for correct field names/values

Common Edits

• Change default tab: Set tab to chart , map , table , line , slope , discrete-bar , or marimekko

• Change selected entities: Edit selectedEntityNames array

• Change colors: Edit map.colorScale.customCategoryColors or colorScale.customCategoryColors

• Change color scheme: Set baseColorScheme or map.colorScale.baseColorScheme (see schema for valid values)

• Hide/show map tab: Set hasMapTab: true/false

• Add chart note: Set note field

• Change axis: Edit yAxis or xAxis with min , max , scaleType , label

Validation

Chart configs should conform to schemas/chart-schema.json . Key constraints:

• tab enum: chart , map , table , line , slope , discrete-bar , marimekko

• chartTypes enum items: LineChart , ScatterPlot , StackedArea , DiscreteBar , StackedDiscreteBar , SlopeChart , StackedBar , Marimekko

• dimensions[].property enum: y , x , size , color , table

• addCountryMode enum: add-country , change-country , disabled