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 usegraph_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
Recommended special fields¶
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 statisticscomputation_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 falsesource_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, thetags
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
Footer¶
The following fields will appear on indicator pages below the graph and the table.
computation_units
- mentioned abovecopyright
- 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