Metadata format

In your data repository the metadata is maintained on an indicator-by-indicator basis. This metadata can include any number of custom fields, as defined in a schema file (see the "Schema" section below) in your data repository. Some fields, however, are mandatory and/or have specific uses in Open SDG. This page details those fields.

Note about translation keys

Metadata values can either be filled in with normal text ("My field value") or with translation keys (my_translations.my_translation). In the examples below, we will try to demonstrate both possibilities.

As an optional shorthand, if the translation key is in the data group, then the group can be omitted. For example, the translation key data.female can be written as simply female.

Mandatory fields

The following fields are required on all indicators:

  • data_non_statistical - whether the indicator is statistical (can be charted/graphed) or not. Examples:
    • true (if non-statistical)
    • false (if statistical)
  • indicator_name - the name for the indicator, which displays at the top of the indicator page. Examples:
    • Proportion of population living below the national poverty line, by sex and age
    • global_indicators.1-2-1-title
  • indicator_number - the number (or "id") for the indicator. Examples:
    • 1.1.1
    • 1.2.1
  • reporting_status - the status of the indicator. Examples:
    • complete
    • notstarted

Mandatory for statistical indicators

If the indicator is going to display a graph, the following fields are required:

  • graph_title - the title that displays above the graph/chart. This can be simple text (or a translation key) if you would like the chart title to be the same for all units of measurement. Examples:
    • My graph title for 1.1.1
    • my_translations.1-1-1-graph_title

  • graph_titles - However if you would like the chart title to depend on the user-selected unit of measurement, then you can use graph_titles (plural) with a more complex structure:

    graph_titles:
  - unit: Percent
    title: My title for percentages
  - unit: Total
    title: My alternate title for totals

  • graph_type - what type of graph to use for the indicator. More information here. Examples:

    • line
    • bar
    • binary
  • national_geographical_coverage - a label used in the absence of any disaggregation. Examples:
    • Australia
    • my_translations.australia

The following fields are not strictly required, but are recommended because they serve special purposes:

  • indicator_available - an alternate name for the indicator, intended for when the global indicator name might not accurately describe the available national/regional statistics
  • computation_units - the unit used in the headline series for this indicator. Examples:
    • Metric tons * my_translations.metric_tons
  • source_active_1 - whether source #1 should be displayed. Examples: true false
  • source_organisation_1 - the name of the source #1 organisation. Examples:
    • My organisation name my_translations.my_organisation
  • source_url_1 - the URL of the source #1 website. Examples:
    • http://example.com
  • source_url_text_1 - the text to display as the link to the source #1 website. Examples:
    • Click here for my organisation's website
    • my_translations.click_here
  • un_designated_tier - the "tier" for this indicator. Examples:
    • 1
    • 2.
  • un_custodian_agency - the custodian agency for this indicator. Examples:
    • World Bank
  • goal_meta_link - URL of the official UN metadata for this indicator. Examples:
    • https://unstats.un.org/sdgs/metadata/files/Metadata-01-01-01a.pdf
  • goal_meta_link_text - the text to display as the link to the official UN metadata for this indicator. Examples:
    • United Nations Sustainable Development Goals Metadata (pdf 894kB)
  • tags - an optional list of "tags" to display under an indicator when it is listed on its goal page. Unlike most other fields, the tags field should be a list. Here is an example of what it might look like, in YAML form: ``` tags:
    • My tag
    • My other tag ```

Data Sources Metadata

Metadata about "data sources" must follow a special format. The keys for the metadata fields must start with source_ and end with a _#, where "#" is number like 1, 2, 3, etc. For example: * source_organisation_1 * source_contact_1 * source_organisation_2 * source_contact_2 * etc.

In this way, all of the source fields ending in "_1" refer to source #1. And all the source fields ending in "_2" refer to source #2, etc.

Caution about URLs

Especially long sequences of characters, like those in a long URL, can cause formatting issues on webpages. It is recommended that particularly long URLs be included as links, instead of as plain text. For example:

Good:

[This is a link to a long URL](https://example.com/abc/def/ghi/jkl/mno/pqr/stu?vwxyz=foo&bar=1234567890)

Avoid:

This a long plain-text URL: https://example.com/abc/def/ghi/jkl/mno/pqr/stu?vwxyz=foo&bar=1234567890

Data Info

Some of the metadata are not intended to be displayed on the site. These are put into a "scope" called "data" in the _prose.yml file. For example, see the data_non_statistical field.

Use this method to hide any fields needed, by putting them into the "data" scope.

Starting values

If you would like an indicator load with certain disaggregation values already selected, you can use the data_start_values field. For example by setting this in the metadata for an indicator...

data_start_values:
  - field: Fruit
    value: Apples
  - field: Grade
    value: A

...Open SDG will start with both "Apples" and "A" selected, instead of "Oranges".

Graph Metadata

The following fields affect the display of graphs. Currently only longitudinal graphs are available but more are planned. These fields are experimental. Graph fields do not show up on the web page as metadata; we will use them in the future for setting how a graphic should render, some extra labels etc.

  • graph_limits - a list of min/max limits controlling the lowest/highest values to be shown on the y-axis. Optionally they can refer to a specific unit of measurement. Note that this involves a slightly more complex metadata structure. If using Prose.io, this will need to be set under "Raw Metadata". For example:

    graph_limits:
  - unit: tons
    minimum: 2
    maximimum: 20
  - unit: passengers
    minimum: 200
    maximum: 2000

  • graph_stacked_disaggregation - this can be used with the "bar" graph type to place a certain disaggregation (such as "Age") into the same "stacked" bars. For example:

    graph_stacked_disaggregation: Age

  • graph_title - mentioned above

  • graph_type - mentioned above

The following fields will appear on indicator pages below the graph and the table.

  • computation_units - mentioned above
  • copyright - information about the copyright. Examples:
    • Copyright 2019 - My organisation
    • my_translations.copyright_message
  • data_footnote - additional information on the data. Examples:
    • My additional information
    • my_translations.1-1-1-footnote
  • national_geographical_coverage - mentioned above

Embedded Feature Metadata

You may want to add an additional feature which isn't created from data, such as an iframe. You can create an extra tab to display this feature by adding the following fields to the metadata file.

  • embedded_feature_footer - information about the embedded feature which displays below embed. Examples:
    • This graph provided by "My Organisation"
    • my_translations.info_about_my_organisation
  • embedded_feature_tab_title - tab title. Examples:
    • Embedded Chart
    • my_translations.embedded_chart
  • embedded_feature_title - the title to be shown above the embedded feature. Examples:
    • My embedded chart
    • my_translatins.1-1-1-embedded-chart

You can either specify a URL or some HTML for the feature you want to embed:

  • embedded_feature_url - the URL of feature that you want to embed. You may use this when you have control over the original feature that you want to embed, and don't need to make any changes e.g. if the feature is already the correct size. Examples:
    • http://example.com/embed-1-1-1.html
  • embedded_feature_html - HTML code of the feature that you want to embed. You may use this when you don't have control of the original feature that you want to embed, and so need to make some changes e.g. to the size, title, or other attributes. Example:
    • <iframe width="1110" height="700" title="Childhood Vaccination Coverage Statistics" src="https://app.powerbi.com/view?r=eyJrIjoiZTI3NWZhNzItMTIyZS00OWM2LTg0MzMtOGY5YTJjMGY0MjI1IiwidCI6IjUwZjYwNzFmLWJiZmUtNDAxYS04ODAzLTY3Mzc0OGU2MjllMiIsImMiOjh9&pageName=ReportSection" frameborder="0" allowFullScreen="true"></iframe>

Non-Standard Information

In the Prose editor, you can add free Markdown text in the same file as the metadata. This is the edit section in prose and is part of the metadata. In the raw .md file this is the content underneath the yaml header. You can add any content you like in this section and the content will be converted to html and placed above the graph near the top of the screen.

A guide to writing Markdown is here and you can write your own tables, lists, links, headings, and so on. This is a useful place to add information about an indicator that doesn't fit in with the rest of the metadata.

Data Notice

You may want to display some very important information which site viewers must keep in mind when using the data provided. To display a notice above the graph in a coloured box, you can use the following fields within the metadata file.

  • data_notice_heading - title of data notice. Examples:
    • Important Note
    • my_translations.important_note
  • data_notice_text - text you want to display within the notice. Examples:
    • My note text
    • my_translations.1-1-1-data-notice
  • data_notice_class - a CSS class to set on the notice. Examples:
    • success (green)
    • warning (amber)
    • danger (red)

Schema

The actual fields available on each indicator is fully configurable by editing the _prose.yml file in your data repository. For a full list of fields available out-of-the-box in the starter repository, see the starter repository's _prose.yml file. This file also serves to control the behavior of the Prose.io service, which is the usual way that metadata is edited. (For technical information about Prose.io schema, see the official Prose.io documentation.)

Renaming metadata fields

In the schema file mentioned above, each field can have a translation_key property. These can be changed from the defaults, as needed, to control the public-facing name for each field. For example, perhaps you want to change the public-facing label for the indicator_name field. You could update the schema, changing it from this:

- name: "indicator_name"
  field:
    element: text
    label: "Indicator name"
    translation_key: metadata_fields.indicator_name
    scope: global

To this:

- name: "indicator_name"
  field:
    element: text
    label: "Indicator name"
    translation_key: my_custom_translations.another_translation
    scope: global

Advanced - label vs translation_key

You may think that it would make more sense for the label property above to control the public-facing name for the field. Indeed, if you are not using Prose.io, you are free to use label instead of translation_key. But Prose.io needs that label property for a special purpose: this is what data editors/managers will see when they're editing metadata. The Prose.io service is not multilingual, so its label property needs to already be translated. (This is why it is plain English out-of-the-box.)

Metadata tabs

The metadata fields can be displayed on indicator pages in a tabbed format. For more information, see the configuration page in the "metadata tabs" section.

Reserved metadata fields

The following keys cannot be used as metadata fields, because they are used for special purposes in Open SDG:

  • goals
  • goal
  • targets
  • target
  • indicators
  • indicator
  • language
  • name
  • number
  • sort
  • global
  • url
  • goal_number
  • target_number