Charts reference¶

AI-Generated Documentation

This documentation was generated with AI assistance and is currently under construction. The content is dynamically generated from schemas/multidim-schema.json. If you notice any inconsistencies or missing information, please check the source schema file or report the issue.

Charts and multidims are defined in ETL by a config that names their dimensions, views and metadata. This reference documents that schema.

Chart - Main chart configuration
View Config - Chart and visualization configuration
View Metadata - Data presentation metadata

`chart`¶

`chart.catalog_path`¶

type: string | required

Unique identifier for the chart in the format 'namespace/version/dataset#name'.

Guidelines Examples

Must follow the pattern 'namespace/version/dataset#name'.
Must be unique across all charts.
Should use descriptive names that identify the chart's purpose.

DO	DON'T
«`energy/2024-01-01/energy_mix#renewable_energy`»	«`energy`», «`energy/2024-01-01`», «`energy/2024-01-01/energy_mix`»
«`demography/2023-12-15/population#age_structure`»	«`demography`», «`population#age_structure`»

`chart.chart_config_id`¶

type: string | required for single charts (dimensions: []), otherwise must be omitted

Identity of the single chart this config authors, as stored in grapher's charts.configId.

Guidelines Examples

Only valid on single charts (dimensions: []); multidims are identified by their catalog path.
When bringing an existing chart into ETL, use that chart's charts.configId so the config lands on the existing chart instead of creating a new one.
For a brand-new chart, mint a UUIDv7 with python -c 'from etl.viz.chart.upsert import new_chart_config_id; print(new_chart_config_id())'.
Never change it once set — it is the chart's identity in every environment (local, staging, production).
Must be in canonical lower-case dashed form; it is used verbatim as grapher's lookup key.

DO	DON'T
«`0191b6c7-5595-70b2-8d30-fa03fccd7add`»	«`7118`», «`banning-of-chick-culling`», «`0191B6C7-5595-70B2-8D30-FA03FCCD7ADD`», «`0191b6c7559570b28d30fa03fccd7add`»

`chart.default_dimensions`¶

Mapping of dimension slugs to their default choice slugs for the initial view.

`chart.default_selection`¶

type: array | conditional

List of entity names (e.g., countries) selected by default when the chart loads. Conditional: required for multidims with at least one view that has chart tabs (line/bar/scatter/etc.) and no per-view selectedEntityNames fallback. Optional for single charts (dimensions: []) and map-only mdims.

Guidelines Examples

Can be omitted when every view either has its own selectedEntityNames or is map-only.
When present, must contain at least one entity.
Entity names must be harmonized country names from the OWID catalog.
Should include 3-8 entities for optimal visualization.
Should represent a diverse and meaningful set of entities.

DO	DON'T
«`["United States", "China", "Germany", "India"]`»	«`[]`», «`["USA", "PRC"]`»
«`["World"]`»	«`["Earth"]`», «`["Global"]`»
«`["Europe", "North America", "Asia"]`»	«`["EU", "NA", "AS"]`», «`["Too many entities..."]`»

`chart.definitions`¶

Common definitions and configurations that can be referenced across multiple views.

`chart.definitions.common_views`¶

type: array

List of partial view configurations that are merged into all matching views. Each item can optionally specify dimensions to match specific views.

`chart.dependencies`¶

type: array | optional

List of dataset URIs that this chart depends on for its indicators.

Guidelines Examples

Used internally to validate that all indicators come from specified datasets.
Should contain dataset paths in the format 'namespace/version/dataset'.
Can optionally include protocol prefixes like 'data://garden/namespace/version/dataset'.
Dependencies are automatically resolved during chart creation if not explicitly provided.

DO	DON'T
«`["energy/2024-01-01/energy_mix", "demography/2023-12-15/population"]`»	«`["energy/renewable_share"]`», «`["incomplete/path"]`»
«`["data://garden/energy/2024-01-01/energy_mix"]`»	«`["data://invalid/format"]`», «`["namespace/version"]`»

`chart.dimensions`¶

type: array | required

Array of dimension objects that define the filter dropdowns available to users. An empty array (and a single view) means the chart is pushed as a regular Grapher chart instead of a multi-dim page.

Guidelines

Can be empty for a single chart (no dimension dropdowns).
Each dimension creates a dropdown filter in the user interface.
Dimension slugs must be unique within the chart.
Should be ordered by importance or logical flow.

`chart.download_package`¶

Where the pre-built "download the complete dataset" package for this chart was published. Not authored by hand: Chart.save() builds the package, uploads it to R2, and fills this in. Absent when no package was built.

`chart.download_package.indicatorCount`¶

type: integer

Number of indicator columns in the package.

`chart.download_package.metadataUrl`¶

type: string

Public URL of the standalone metadata.json accompanying the Parquet.

`chart.download_package.parquetUrl`¶

type: string

Public URL of the same data as Parquet, for reading with code.

`chart.download_package.rowCount`¶

type: integer

Number of data rows in the package.

`chart.download_package.sizeBytes`¶

type: integer

Size of the zip in bytes.

`chart.download_package.url`¶

type: string

Public URL of the zip (wide CSV + metadata.json + readme.md), for the download button.

`chart.grapher_schema`¶

type: string | required

Version of the OWID Grapher chart-config schema that this chart's view configs were authored against. Grapher uses it as the $schema of every view config, and migrates outdated configs forward to the current version.

Guidelines Examples

Pin the version explicitly — ETL fails without it. There is no fallback on purpose: an unpinned config would resolve to whatever DEFAULT_GRAPHER_SCHEMA is on the day the step runs, which both claims the config is already current (so a breaking schema change skips the migration) and silently changes on the next run after a version bump.
Two forms are accepted: the short three-digit version ("011") or the full schema URL.
Quote the short form. YAML parses a bare 011 as an octal number, which silently resolves to a different version.
Leave the pin alone once set — it records what the config was authored against, which is what lets Grapher migrate it after a breaking change.
Pin here and nowhere else. A $schema inside a view's config overrides this field (grapher spreads the view config last) while being much less visible, so the two silently disagree. ETL logs a warning when a view shadows this pin.
The exception is a pin that contradicts the config body (e.g. pinned 005 while using chartTypes, which only exists from 006). That is a stale pin, not a record: Grapher would run migrations over a config they were never meant to touch. Correct it to the version the config is actually written against.

DO	DON'T
«`011`»	«`11`», «`0.11`», «`latest`»
«`https://files.ourworldindata.org/schemas/grapher-schema.011.json`»	«`grapher-schema.011.json`», «`https://files.ourworldindata.org/schemas/grapher-schema.latest.json`»

`chart.metadata`¶

`chart.metadata.description_from_producer`¶

type: string | recommended (if existing)

Description of the indicator written by the producer, if any was given.

Guidelines

Must start with a capital letter.
Must end with a period.
Should be identical to the producer's text, except for some formatting changes, typo corrections, or other appropriate minor edits.
Should only be given if the producer clearly provides such definitions in a structured way. Avoid spending time searching for a definition given by the producer elsewhere.

`chart.metadata.description_key`¶

type: string, array | recommended (for curated indicators)

Key information about the indicator as free-form markdown text. A YAML list of bullet points is also accepted and converted to a markdown list on load.

Guidelines

Must be free-form markdown text with the key information about the indicator, or a list of bullet points.
- The text is rendered as markdown (paragraphs, links and lists are supported).
- A YAML list is authoring sugar for a markdown list; each bullet must start with a capital letter and end with a period.
Must not contain description_short (although there might be some overlap of information).
Should contain all the key information about the indicator (except that already given in description_short).
Should include the key information given in other fields like grapher_config.subtitle (if different from description_short) and grapher_config.note.
Should not contain information about processing (which should be in description_processing).
Should only contain information that is key to the public.
- Anything that is too detailed or technical should be left in the code.

`chart.metadata.description_processing`¶

type: string | required (if applicable)

Relevant information about the processing of the indicator done by OWID.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be used if important editorial decisions have been taken during data processing.
Must not be used to describe common processing steps like country harmonization.
Should only contain key processing information to the public.
- Anything that is too detailed or technical should be left in the code.

`chart.metadata.description_short`¶

type: string | required

One or a few lines that complement the title to have a short description of the indicator.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be one short paragraph (for example suitable to fit in a chart subtitle).
Should not mention any other metadata fields (like information about the processing, or the origins, or the units). Exceptions:
- The unit can be mentioned if it is crucial for the description.

`chart.metadata.display`¶

We keep display for the time being as the 'less powerful sibling' of grapher config.

`chart.metadata.display.color`¶

type: string

Color to use for the indicator in e.g. line charts.

`chart.metadata.display.conversionFactor`¶

type: number

Conversion factor to apply to indicator values.

Guidelines

Note: We should avoid using this, and instead convert data and units (and possibly other metadata fields where the units are mentioned) consistently in the ETL grapher step.

`chart.metadata.display.description`¶

type: string

Description to display for the indicator, to replace the indicator's description.

`chart.metadata.display.entityAnnotationsMap`¶

type: string

Entity annotations

`chart.metadata.display.includeInTable`¶

type: boolean

Whether to render this indicator in the table sheet.

`chart.metadata.display.isProjection`¶

type: boolean, string, string

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

`chart.metadata.display.name`¶

type: string | required

Indicator's title to display in the legend of a chart. NOTE: For backwards compatibility, display.name also replaces the indicator's title in other public places. Therefore, whenever display.name is defined, title_public should also be defined.

Guidelines Examples

Must be very short, to fit the legend of a chart.
Must not end with a period.
Should not mention other metadata fields like producer or version.

DO	DON'T
«`Agriculture`»	«`Nitrous oxide emissions from agriculture`»
«`Area harvested`»	«`Barley \| 00000044 \|\| Area harvested \| 005312 \|\| hectares`»

`chart.metadata.display.numDecimalPlaces`¶

type: integer, string, string

Number of decimal places to show in charts (and in the table tab).

`chart.metadata.display.numSignificantFigures`¶

type: integer, string

Number of significant rounding figures in charts.

`chart.metadata.display.roundingMode`¶

type: string

Specifies the rounding mode to use.

`chart.metadata.display.shortUnit`¶

type: string

Short unit to use in charts instead of the indicator's short_unit.

`chart.metadata.display.tableDisplay`¶

Configuration for the table tab for this indicator, with options hideAbsoluteChange and hideRelativeChange.

`chart.metadata.display.tableDisplay.hideAbsoluteChange`¶

type: boolean

Whether to hide the absolute change.

`chart.metadata.display.tableDisplay.hideRelativeChange`¶

type: boolean

Whether to hide the relative change.

`chart.metadata.display.timeInterval`¶

type: string, string

Interval that each value in the year/time column represents. Sub-yearly intervals (day, week, month, quarter) are encoded as days-since-zeroDay integers.

`chart.metadata.display.tolerance`¶

type: integer

Tolerance (in years or days) to use in charts. If data points are missing, the closest data point will be shown, if it lies within the specified tolerance.

`chart.metadata.display.unit`¶

type: string

Unit to use in charts instead of the indicator's unit.

`chart.metadata.display.zeroDay`¶

type: string

ISO date string for the day that time value 0 represents, for sub-yearly (day/week/month) timeInterval data encoded as days-since-zeroDay integers.

`chart.metadata.license`¶

type: string | required (in the future this could be automatic)

License of the indicator, which depends on the indicator's processing level and the origins' licenses.

Guidelines

If the indicator's processing_level is major, assign CC BY 4.0.
If the indicator's processing_level is minor, choose the most strict license among the origins' licenses.

`chart.metadata.origins`¶

type: array

List of all origins of the indicator.

Guidelines

Note: Origins should be propagated automatically from snapshots. Therefore, this field should only be manually filled out if automatic propagation fails.

`chart.metadata.presentation`¶

An indicator's presentation defines how the indicator's metadata will be shown on our website (e.g. in data pages). The indicator presentation metadata fields are the attributes of the VariablePresentationMetaobject in ETL.

`chart.metadata.presentation.attribution`¶

type: string | optional

Citation of the indicator's origins, to override the automatic format producer1 (year1); producer2 (year2).

Guidelines Examples

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must join multiple attributions by a ;.
Must separate a producer from a data product with a spaced en dash (–), not a hyphen.
Must not end in a period (and must not end in ;).
Must contain the year of date_published, for each origin, in parenthesis.
Should only be used when the automatic format producer1 (year1); producer2 (year2) needs to be overridden.

DO	DON'T
«`Energy Institute – Statistical Review of World Energy (2023); Ember (2022)`»	«`UN (2023), WHO (2023)`»

`chart.metadata.presentation.attribution_short`¶

type: string | recommended (for curated indicators)

Very short citation of the indicator's main producer(s).

Guidelines

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must not end in a period.
Should be very short.
Should be used if the automatic concatenation of origin's attribution_short are too long. In those cases, choose the most important attribution (e.g. the main producer of the data).

`chart.metadata.presentation.faqs`¶

type: array | recommended (for curated indicators)

List of references to questions in an FAQ google document, relevant to the indicator.

Guidelines

Each reference must contain fragment_id (question identifier) and gdoc_id (document identifier).

`chart.metadata.presentation.grapher_config`¶

Our World in Data grapher configuration. Most of the fields can be left empty and will be filled with reasonable default values. Validated by the grapher admin API when the config is upserted, not here. See the grapher schema for the available fields.

`chart.metadata.presentation.title_public`¶

type: string | optional

Indicator title to be shown in public places like data pages, that overrides the indicator's title.

Guidelines

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
Should not mention other metadata fields like producer or version.
Should help OWID and expert users identify the indicator.
For big datasets where constructing human-readable titles is hard (e.g. FAOSTAT), this field is mandatory, to improve the public appearance of the title.
When display.name is defined (to edit the default title in the legend of a chart), title_public must also be defined (otherwise display.name will be used as a public title).

`chart.metadata.presentation.title_variant`¶

type: string | optional

Short disambiguation of the title that references a special feature of the methods or nature of the data.

Guidelines Examples

Must start with a capital letter.
Must not end in a period.
Should be very short.
Should only be used if the indicator's title is ambiguous (e.g. if there are multiple indicators with the same title).
Should not reference the data producer. For that, instead, use attribution_short.

DO	DON'T
«`Age-standardized`»	«`The data is age-standardized`»
«`Historical data`»	«`Historical data from 1800 to 2010`»

`chart.metadata.presentation.topic_tags`¶

type: array | recommended (for curated indicators)

List of topics where the indicator is relevant.

Guidelines

Must be an existing topic tag, and be spelled correctly (see the list of topic tags in datasette.
The first tag must correspond to the most relevant topic page (since that topic page will be used in citations of this indicator).
Should contain 1, 2, or at most 3 tags.

`chart.metadata.presentation_license`¶

License to display for the indicator, overriding license.

`chart.metadata.presentation_license.name`¶

type: string

`chart.metadata.presentation_license.url`¶

type: string

`chart.metadata.processing_level`¶

type: ['minor', 'major'], string | required (in the future this could be automatic).

Level of processing that the indicator values have experienced.

Guidelines

Must be minor if the indicator has undergone only minor operations since its origin:
- Rename entities (e.g. countries or columns)
- Multiplication by a constant (e.g. unit change)
- Drop missing values.
Must be major if any other operation is used:
- Data aggregates (e.g. sum data for continents or income groups)
- Operations between indicators (e.g. per capita, percentages, annual changes)
- Concatenation of indicators, etc.

`chart.metadata.short_unit`¶

type: string | required

Characters that represent the unit we use to measure the indicator value.

Guidelines Examples

Must follow the rules of capitalization of the International System of Units, when applicable.
Must not end with a period.
Must be empty if the indicator has no units.
Should not contain spaces.
If, for clarity, we prefer to simplify the units in a chart, e.g. to show kWh instead of kWh/person, use display.short_unit for the simplified units, and keep the correct one in indicator.short_unit (and ensure there is no ambiguity in the chart).

DO	DON'T
«`t/ha`»	«`t / ha`»
«`%`»	«`pct`»
«`kWh/person`»	«`pc`»

`chart.metadata.sort`¶

type: array

`chart.metadata.title`¶

type: string | required

Title of the indicator, which is a few words definition of the indicator.

Guidelines Examples

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
For 'small datasets', this should be the publicly displayed title. For 'big datasets' (like FAOSTAT, with many dimensions), it can be less human-readable, optimized for internal searches (then, use presentation.title_public for the public title).
Should not mention other metadata fields like producer or version.

DO	DON'T
«`Number of neutron star mergers in the Milky Way`»	«`Number of neutron stars (NASA)`»
«`Share of neutron star mergers that happen in the Milky Way`»	«`Share of neutron star mergers that happen in the Milky Way (2023)`»
«`Barley \| 00000044 \|\| Area harvested \| 005312 \|\| hectares`»	«`Barley`»

`chart.metadata.type`¶

type: string

Indicator type is usually automatically inferred from the data, but must be manually set for ordinal and categorical types.

`chart.metadata.unit`¶

type: string | required

Very concise name of the unit we use to measure the indicator values.

Guidelines Examples

Must not start with a capital letter.
Must not end with a period.
Must be empty if the indicator has no units.
Must be in plural.
Must be a metric unit when applicable.
Should not use symbols like “/”.
- If it is a derived unit, use 'per' to denote a division, e.g. '... per hectare', or '... per person'.
Should be '%' for percentages.

DO	DON'T
«`tonnes per hectare`»	«`tonnes/hectare`»
«`kilowatts per person`»	«`kilowatts per capita`»

`chart.presentation`¶

Optional settings for the kind of page a multidim is shown as. Without it, the multidim is a plain data page.

`chart.presentation.explorer_subtitle`¶

type: string | required

Short text shown on the multidim's card on the explorers page.

Guidelines

Must start with a capital letter.
Must end with a period.

`chart.presentation.page_type`¶

type: string | required

The kind of page. data-explorer presents the multidim as a data explorer and lists it on the explorers page (ourworldindata.org/explorers).

`chart.slug`¶

type: string | required for single charts (dimensions: []), optional for multidims

The chart's public URL slug, as in ourworldindata.org/grapher/<slug>.

Guidelines Examples

Lowercase words separated by dashes.
Applied only when grapher creates the chart, or when the mdim has no slug yet. An existing slug is never changed from ETL: rename it in the admin, which also creates the redirect.
A multidim without it gets its slug in the admin.
The step's short name (its file name, e.g. foreign_aid_given_climate) should match the slug, with underscores instead of dashes. This is not required, but strongly recommended, so the file and the URL match.

DO	DON'T
«`foreign-aid-given-climate`»	«`foreign_aid_given_climate`», «`/grapher/foreign-aid-given-climate`»
«`academic-performance`»	«`Academic-Performance`», «`academic performance`»

`chart.title`¶

Title configuration for the chart display. Required for multidims (with non-empty dimensions); ignored for single charts (with dimensions: []).

`chart.title.title`¶

type: string | required

Primary title displayed for the chart.

Guidelines Examples

Must start with a capital letter.
Must not end with a period.
Should be concise but descriptive.
Should clearly indicate the chart's purpose.

DO	DON'T
«`Energy Mix`»	«`energy mix`», «`Energy Mix.`», «`Energy`»
«`Global Population Demographics`»	«`global population demographics`», «`Demographics`»
«`Climate Change Indicators`»	«`climate change indicators`», «`Climate`»

`chart.title.title_variant`¶

type: string | optional

Additional context or variant information for the title.

Guidelines

Must not end with a period.
Should provide disambiguation or additional context.
Should be shorter than the main title.

`chart.topic_tags`¶

type: array | optional

List of topic categories that this chart relates to.

Guidelines Examples

Must use existing OWID topic tags.
Should include 1-3 relevant topic tags.
The first tag should be the most relevant topic.

DO	DON'T
«`["Energy"]`»	«`["energy"]`», «`["Invalid Topic"]`»
«`["Climate Change", "Energy"]`»	«`["climate change", "energy"]`», «`["Too", "Many", "Tags"]`»
«`["Population Growth", "Demography"]`»	«`["population growth", "demography"]`», «`["Nonexistent Topic"]`»

`chart.views`¶

type: array | required

Array of view configurations that define specific chart instances.

Guidelines

Must contain at least one view.
Each view represents a specific combination of dimension choices and chart configuration.
Views are generated automatically based on dimension combinations, but can be customized.

`view.config`¶

Chart configuration options that override default settings for this view. Validated by the grapher admin API when the config is upserted, not here. See the grapher schema for the available fields.

For the complete list of available configuration options, see the Grapher schema.

`view.metadata`¶

`view.metadata.description_from_producer`¶

type: string | recommended (if existing)

Description of the indicator written by the producer, if any was given.

Guidelines

Must start with a capital letter.
Must end with a period.
Should be identical to the producer's text, except for some formatting changes, typo corrections, or other appropriate minor edits.
Should only be given if the producer clearly provides such definitions in a structured way. Avoid spending time searching for a definition given by the producer elsewhere.

`view.metadata.description_key`¶

type: string, array | recommended (for curated indicators)

Key information about the indicator as free-form markdown text. A YAML list of bullet points is also accepted and converted to a markdown list on load.

Guidelines

Must be free-form markdown text with the key information about the indicator, or a list of bullet points.
- The text is rendered as markdown (paragraphs, links and lists are supported).
- A YAML list is authoring sugar for a markdown list; each bullet must start with a capital letter and end with a period.
Must not contain description_short (although there might be some overlap of information).
Should contain all the key information about the indicator (except that already given in description_short).
Should include the key information given in other fields like grapher_config.subtitle (if different from description_short) and grapher_config.note.
Should not contain information about processing (which should be in description_processing).
Should only contain information that is key to the public.
- Anything that is too detailed or technical should be left in the code.

`view.metadata.description_processing`¶

type: string | required (if applicable)

Relevant information about the processing of the indicator done by OWID.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be used if important editorial decisions have been taken during data processing.
Must not be used to describe common processing steps like country harmonization.
Should only contain key processing information to the public.
- Anything that is too detailed or technical should be left in the code.

`view.metadata.description_short`¶

type: string | required

One or a few lines that complement the title to have a short description of the indicator.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be one short paragraph (for example suitable to fit in a chart subtitle).
Should not mention any other metadata fields (like information about the processing, or the origins, or the units). Exceptions:
- The unit can be mentioned if it is crucial for the description.

`view.metadata.display`¶

We keep display for the time being as the 'less powerful sibling' of grapher config.

`view.metadata.display.color`¶

type: string

Color to use for the indicator in e.g. line charts.

`view.metadata.display.conversionFactor`¶

type: number

Conversion factor to apply to indicator values.

Guidelines

Note: We should avoid using this, and instead convert data and units (and possibly other metadata fields where the units are mentioned) consistently in the ETL grapher step.

`view.metadata.display.description`¶

type: string

Description to display for the indicator, to replace the indicator's description.

`view.metadata.display.entityAnnotationsMap`¶

type: string

Entity annotations

`view.metadata.display.includeInTable`¶

type: boolean

Whether to render this indicator in the table sheet.

`view.metadata.display.isProjection`¶

type: boolean, string, string

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

`view.metadata.display.name`¶

type: string | required

Indicator's title to display in the legend of a chart. NOTE: For backwards compatibility, display.name also replaces the indicator's title in other public places. Therefore, whenever display.name is defined, title_public should also be defined.

Guidelines Examples

Must be very short, to fit the legend of a chart.
Must not end with a period.
Should not mention other metadata fields like producer or version.

DO	DON'T
«`Agriculture`»	«`Nitrous oxide emissions from agriculture`»
«`Area harvested`»	«`Barley \| 00000044 \|\| Area harvested \| 005312 \|\| hectares`»

`view.metadata.display.numDecimalPlaces`¶

type: integer, string, string

Number of decimal places to show in charts (and in the table tab).

`view.metadata.display.numSignificantFigures`¶

type: integer, string

Number of significant rounding figures in charts.

`view.metadata.display.roundingMode`¶

type: string

Specifies the rounding mode to use.

`view.metadata.display.shortUnit`¶

type: string

Short unit to use in charts instead of the indicator's short_unit.

`view.metadata.display.tableDisplay`¶

Configuration for the table tab for this indicator, with options hideAbsoluteChange and hideRelativeChange.

`view.metadata.display.tableDisplay.hideAbsoluteChange`¶

type: boolean

Whether to hide the absolute change.

`view.metadata.display.tableDisplay.hideRelativeChange`¶

type: boolean

Whether to hide the relative change.

`view.metadata.display.timeInterval`¶

type: string, string

Interval that each value in the year/time column represents. Sub-yearly intervals (day, week, month, quarter) are encoded as days-since-zeroDay integers.

`view.metadata.display.tolerance`¶

type: integer

Tolerance (in years or days) to use in charts. If data points are missing, the closest data point will be shown, if it lies within the specified tolerance.

`view.metadata.display.unit`¶

type: string

Unit to use in charts instead of the indicator's unit.

`view.metadata.display.zeroDay`¶

type: string

ISO date string for the day that time value 0 represents, for sub-yearly (day/week/month) timeInterval data encoded as days-since-zeroDay integers.

`view.metadata.license`¶

type: string | required (in the future this could be automatic)

License of the indicator, which depends on the indicator's processing level and the origins' licenses.

Guidelines

If the indicator's processing_level is major, assign CC BY 4.0.
If the indicator's processing_level is minor, choose the most strict license among the origins' licenses.

`view.metadata.origins`¶

type: array

List of all origins of the indicator.

Guidelines

Note: Origins should be propagated automatically from snapshots. Therefore, this field should only be manually filled out if automatic propagation fails.

`view.metadata.presentation`¶

An indicator's presentation defines how the indicator's metadata will be shown on our website (e.g. in data pages). The indicator presentation metadata fields are the attributes of the VariablePresentationMetaobject in ETL.

`view.metadata.presentation.attribution`¶

type: string | optional

Citation of the indicator's origins, to override the automatic format producer1 (year1); producer2 (year2).

Guidelines Examples

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must join multiple attributions by a ;.
Must separate a producer from a data product with a spaced en dash (–), not a hyphen.
Must not end in a period (and must not end in ;).
Must contain the year of date_published, for each origin, in parenthesis.
Should only be used when the automatic format producer1 (year1); producer2 (year2) needs to be overridden.

DO	DON'T
«`Energy Institute – Statistical Review of World Energy (2023); Ember (2022)`»	«`UN (2023), WHO (2023)`»

`view.metadata.presentation.attribution_short`¶

type: string | recommended (for curated indicators)

Very short citation of the indicator's main producer(s).

Guidelines

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must not end in a period.
Should be very short.
Should be used if the automatic concatenation of origin's attribution_short are too long. In those cases, choose the most important attribution (e.g. the main producer of the data).

`view.metadata.presentation.faqs`¶

type: array | recommended (for curated indicators)

List of references to questions in an FAQ google document, relevant to the indicator.

Guidelines

Each reference must contain fragment_id (question identifier) and gdoc_id (document identifier).

`view.metadata.presentation.grapher_config`¶

Our World in Data grapher configuration. Most of the fields can be left empty and will be filled with reasonable default values. Validated by the grapher admin API when the config is upserted, not here. See the grapher schema for the available fields.

`view.metadata.presentation.title_public`¶

type: string | optional

Indicator title to be shown in public places like data pages, that overrides the indicator's title.

Guidelines

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
Should not mention other metadata fields like producer or version.
Should help OWID and expert users identify the indicator.
For big datasets where constructing human-readable titles is hard (e.g. FAOSTAT), this field is mandatory, to improve the public appearance of the title.
When display.name is defined (to edit the default title in the legend of a chart), title_public must also be defined (otherwise display.name will be used as a public title).

`view.metadata.presentation.title_variant`¶

type: string | optional

Short disambiguation of the title that references a special feature of the methods or nature of the data.

Guidelines Examples

Must start with a capital letter.
Must not end in a period.
Should be very short.
Should only be used if the indicator's title is ambiguous (e.g. if there are multiple indicators with the same title).
Should not reference the data producer. For that, instead, use attribution_short.

DO	DON'T
«`Age-standardized`»	«`The data is age-standardized`»
«`Historical data`»	«`Historical data from 1800 to 2010`»

`view.metadata.presentation.topic_tags`¶

type: array | recommended (for curated indicators)

List of topics where the indicator is relevant.

Guidelines

Must be an existing topic tag, and be spelled correctly (see the list of topic tags in datasette.
The first tag must correspond to the most relevant topic page (since that topic page will be used in citations of this indicator).
Should contain 1, 2, or at most 3 tags.

`view.metadata.presentation_license`¶

License to display for the indicator, overriding license.

`view.metadata.presentation_license.name`¶

type: string

`view.metadata.presentation_license.url`¶

type: string

`view.metadata.processing_level`¶

type: ['minor', 'major'], string | required (in the future this could be automatic).

Level of processing that the indicator values have experienced.

Guidelines

Must be minor if the indicator has undergone only minor operations since its origin:
- Rename entities (e.g. countries or columns)
- Multiplication by a constant (e.g. unit change)
- Drop missing values.
Must be major if any other operation is used:
- Data aggregates (e.g. sum data for continents or income groups)
- Operations between indicators (e.g. per capita, percentages, annual changes)
- Concatenation of indicators, etc.

`view.metadata.short_unit`¶

type: string | required

Characters that represent the unit we use to measure the indicator value.

Guidelines Examples

Must follow the rules of capitalization of the International System of Units, when applicable.
Must not end with a period.
Must be empty if the indicator has no units.
Should not contain spaces.
If, for clarity, we prefer to simplify the units in a chart, e.g. to show kWh instead of kWh/person, use display.short_unit for the simplified units, and keep the correct one in indicator.short_unit (and ensure there is no ambiguity in the chart).

DO	DON'T
«`t/ha`»	«`t / ha`»
«`%`»	«`pct`»
«`kWh/person`»	«`pc`»

`view.metadata.sort`¶

type: array

`view.metadata.title`¶

type: string | required

Title of the indicator, which is a few words definition of the indicator.

Guidelines Examples

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
For 'small datasets', this should be the publicly displayed title. For 'big datasets' (like FAOSTAT, with many dimensions), it can be less human-readable, optimized for internal searches (then, use presentation.title_public for the public title).
Should not mention other metadata fields like producer or version.

DO	DON'T
«`Number of neutron star mergers in the Milky Way`»	«`Number of neutron stars (NASA)`»
«`Share of neutron star mergers that happen in the Milky Way`»	«`Share of neutron star mergers that happen in the Milky Way (2023)`»
«`Barley \| 00000044 \|\| Area harvested \| 005312 \|\| hectares`»	«`Barley`»

`view.metadata.type`¶

type: string

Indicator type is usually automatically inferred from the data, but must be manually set for ordinal and categorical types.

`view.metadata.unit`¶

type: string | required

Very concise name of the unit we use to measure the indicator values.

Guidelines Examples

Must not start with a capital letter.
Must not end with a period.
Must be empty if the indicator has no units.
Must be in plural.
Must be a metric unit when applicable.
Should not use symbols like “/”.
- If it is a derived unit, use 'per' to denote a division, e.g. '... per hectare', or '... per person'.
Should be '%' for percentages.

DO	DON'T
«`tonnes per hectare`»	«`tonnes/hectare`»
«`kilowatts per person`»	«`kilowatts per capita`»

For the complete metadata structure, see the Dataset schema.

Charts reference¶

chart¶

chart.catalog_path¶

chart.chart_config_id¶

chart.default_dimensions¶

chart.default_selection¶

chart.definitions¶

chart.definitions.common_views¶

chart.dependencies¶

chart.dimensions¶

chart.download_package¶

chart.download_package.indicatorCount¶

chart.download_package.metadataUrl¶

chart.download_package.parquetUrl¶

chart.download_package.rowCount¶

chart.download_package.sizeBytes¶

chart.download_package.url¶

chart.grapher_schema¶

chart.metadata¶

chart.metadata.description_from_producer¶

chart.metadata.description_key¶

chart.metadata.description_processing¶

chart.metadata.description_short¶

chart.metadata.display¶

chart.metadata.display.color¶

chart.metadata.display.conversionFactor¶

chart.metadata.display.description¶

chart.metadata.display.entityAnnotationsMap¶

chart.metadata.display.includeInTable¶

chart.metadata.display.isProjection¶

chart.metadata.display.name¶

chart.metadata.display.numDecimalPlaces¶

chart.metadata.display.numSignificantFigures¶

chart.metadata.display.roundingMode¶

chart.metadata.display.shortUnit¶

chart.metadata.display.tableDisplay¶

chart.metadata.display.tableDisplay.hideAbsoluteChange¶

chart.metadata.display.tableDisplay.hideRelativeChange¶

chart.metadata.display.timeInterval¶

chart.metadata.display.tolerance¶

chart.metadata.display.unit¶

chart.metadata.display.zeroDay¶

chart.metadata.license¶

chart.metadata.origins¶

chart.metadata.presentation¶

chart.metadata.presentation.attribution¶

chart.metadata.presentation.attribution_short¶

chart.metadata.presentation.faqs¶

chart.metadata.presentation.grapher_config¶

chart.metadata.presentation.title_public¶

chart.metadata.presentation.title_variant¶

chart.metadata.presentation.topic_tags¶

chart.metadata.presentation_license¶

chart.metadata.presentation_license.name¶

chart.metadata.presentation_license.url¶

chart.metadata.processing_level¶

chart.metadata.short_unit¶

chart.metadata.sort¶

chart.metadata.title¶

chart.metadata.type¶

chart.metadata.unit¶

chart.presentation¶

chart.presentation.explorer_subtitle¶

chart.presentation.page_type¶

chart.slug¶

chart.title¶

chart.title.title¶

chart.title.title_variant¶

chart.topic_tags¶

chart.views¶

view.config¶

view.metadata¶

view.metadata.description_from_producer¶

view.metadata.description_key¶

view.metadata.description_processing¶

view.metadata.description_short¶

view.metadata.display¶

view.metadata.display.color¶

view.metadata.display.conversionFactor¶

view.metadata.display.description¶

`chart`¶

`chart.catalog_path`¶

`chart.chart_config_id`¶

`chart.default_dimensions`¶

`chart.default_selection`¶

`chart.definitions`¶

`chart.definitions.common_views`¶

`chart.dependencies`¶

`chart.dimensions`¶

`chart.download_package`¶

`chart.download_package.indicatorCount`¶

`chart.download_package.metadataUrl`¶

`chart.download_package.parquetUrl`¶

`chart.download_package.rowCount`¶

`chart.download_package.sizeBytes`¶

`chart.download_package.url`¶

`chart.grapher_schema`¶

`chart.metadata`¶

`chart.metadata.description_from_producer`¶

`chart.metadata.description_key`¶

`chart.metadata.description_processing`¶

`chart.metadata.description_short`¶

`chart.metadata.display`¶

`chart.metadata.display.color`¶

`chart.metadata.display.conversionFactor`¶

`chart.metadata.display.description`¶

`chart.metadata.display.entityAnnotationsMap`¶

`chart.metadata.display.includeInTable`¶

`chart.metadata.display.isProjection`¶

`chart.metadata.display.name`¶

`chart.metadata.display.numDecimalPlaces`¶

`chart.metadata.display.numSignificantFigures`¶

`chart.metadata.display.roundingMode`¶

`chart.metadata.display.shortUnit`¶

`chart.metadata.display.tableDisplay`¶

`chart.metadata.display.tableDisplay.hideAbsoluteChange`¶

`chart.metadata.display.tableDisplay.hideRelativeChange`¶

`chart.metadata.display.timeInterval`¶

`chart.metadata.display.tolerance`¶

`chart.metadata.display.unit`¶

`chart.metadata.display.zeroDay`¶

`chart.metadata.license`¶

`chart.metadata.origins`¶

`chart.metadata.presentation`¶

`chart.metadata.presentation.attribution`¶

`chart.metadata.presentation.attribution_short`¶

`chart.metadata.presentation.faqs`¶

`chart.metadata.presentation.grapher_config`¶

`chart.metadata.presentation.title_public`¶

`chart.metadata.presentation.title_variant`¶

`chart.metadata.presentation.topic_tags`¶

`chart.metadata.presentation_license`¶

`chart.metadata.presentation_license.name`¶

`chart.metadata.presentation_license.url`¶

`chart.metadata.processing_level`¶

`chart.metadata.short_unit`¶

`chart.metadata.sort`¶

`chart.metadata.title`¶

`chart.metadata.type`¶

`chart.metadata.unit`¶

`chart.presentation`¶

`chart.presentation.explorer_subtitle`¶

`chart.presentation.page_type`¶

`chart.slug`¶

`chart.title`¶

`chart.title.title`¶

`chart.title.title_variant`¶

`chart.topic_tags`¶

`chart.views`¶

`view.config`¶

`view.metadata`¶

`view.metadata.description_from_producer`¶

`view.metadata.description_key`¶

`view.metadata.description_processing`¶

`view.metadata.description_short`¶

`view.metadata.display`¶

`view.metadata.display.color`¶

`view.metadata.display.conversionFactor`¶

`view.metadata.display.description`¶

`view.metadata.display.entityAnnotationsMap`¶