How to use IATI Reference

The IATI reference pages are written from a technical viewpoint. They’re taken from the 'single source of truth', which is the core of the data standard. The reference pages give full descriptions of the many different items the Standard covers.

Use the reference pages to help you create properly structured, well-formed XML files that comply with the Standard. Think of the reference area as your workshop manual.

If you use a publishing tool that complies with the Standard, it will usually provide fields for you to enter your data, so you don’t need to worry about the structure or refer to the reference material. But you might still need to check definitions in the reference pages.

What the reference pages include

The reference pages cover the IATI schema, codelists, elements and attributes, and give detail on namespaces and extensions, and rulesets.

Schema

• This is the list of all the data elements, presented in the order they must appear. There’s a page for each element. Each page gives a definition, any rules that must be followed, and any extra information that can be included. There’s an example of how each element should be presented.

Codelists

• The data you report in IATI is made up of free text and set values, or codes. Codes are used when there are a limited number of options, and are reported using an attribute. For example, there are a finite number of languages you could report in and each has a code. The IATI codelists contain the names and descriptions of all available values.

Elements

• Elements allow you to add details:
  • for example, <title> is an element
  • this tells you that the information that directly follows is the 'title' of the activity.
• Each element may have a 'sub-element'; these are additional details that can be included:
  • within the <title> element you can add a <narrative> element
  • in the <narrative> you can add free text, giving the 'title' of your activity.

Attributes

• Attributes are a set of values that give information about an element. Each element may have one or more attributes, for example:
  • the element <narrative> has the attribute @xml:lang
  • this attribute allows you to specify the language your narrative is written in
  • there is a value (or a code) for each language, for example English is ‘en’.

Usage example:

<title>

<narrative xml:lang="en">Activity title</narrative>

</title>

Advanced documentation

If you want to extend the IATI schema for your own use or build in bespoke validation for your IATI publishing, use these pages:

Namespaces and extensions

• These allow organisations to publish extra information not currently covered by the available IATI elements.

Rulesets

• These are an agreed way of checking that an IATI XML file complies with the IATI data Standard.

Using IATI Reference with a publishing tool

When using a publishing tool, most of the technical work is done for you. In that case, the key reason to use IATI reference pages is to look up definitions.

To find an element or attribute definition:

• go to the IATI Activity or IATI Organisation page and select the element you wish to view or the one that contains your attribute
• or use search to find the relevant element, for example ‘IATI Standard Title’.

To find the definition of a value on a codelist you can:

• go to the IATI Codelists page and select the codelist you want
• or use search to find the relevant codelist, for example the ‘IATI Standard Language Codelist’.

Most publishing tools provide a template or form to enter your data. This means you shouldn’t have to worry about its structure.

Tools should also contain information and checks about rules you need to comply to. But if you have a problem with your XML file not validating, check what the rule is by going to the relevant IATI reference element page.