Self-defined Vocabularies

Definition

For several elements in the IATI activity standard and the IATI organisation standard, the vocabulary for a given code can be set via the @vocabulary attribute:

A good example of this is the sector element, which will typically be given a 5-digit code such as “11120”. However, this code only makes sense to data users if they know which sector codelist it is from.

To achieve this, the sector/@vocabulary should be set to the appropriate entry on the SectorVocabulary codelist. For “11120”, this would be vocabulary "1" - the OECD DAC CRS Purpose Codes (5 digit), and would hence denote the code for Education facilities and training.

It’s important to note that if there are multiple sectors given from the same vocabulary, their @percentage attributes should add up to 100.

Here is an example:

<iati-activity>
    <!-- Other elements -->
    <sector vocabulary="1" code="11120" percentage="50" />
    <sector vocabulary="1" code="11121" percentage="50" />
    <!-- Other elements -->
</iati-activity>

For any given element that has a @vocabulary attribute, the guidance on this site will link to the relevant codelist, which can be seen in the guidance for the sector element.

For each of these vocabularies, there is almost always the option for a publisher to provide their own. For instance, if a publisher wants to declare that an activity is “11120” for the OECD DAC 5-digit vocabulary, but also wants to declare it as “general_education” on their own codelist, they would simply have to set the vocabulary to “Reporting Organisation” (which is usually but not always "99"), and then use the @vocabulary-uri attribute to link through to their own (machine-readable) codelist.

Here is an example:

<iati-activity>
    <!-- Other elements -->
    <sector vocabulary="99" vocabulary-uri="http://example.com/vocab.html" code="general_education" percentage="100" />
    <!-- Other elements -->
</iati-activity>

Considerations

When using the IATI activity standard to declare budgets, the following should be considered:

• It is very important that @percentages add up to 100 per vocabulary.
• When a publisher uses code "99", or whichever other code denotes that they are using a Reporting Organisation provided codelist, they should provide the corresponding @vocabulary-uri (or equivalent) attribute.

Pre 2.02 Considerations

Not all of the elements mentioned above exist in some previous versions of the standard, but most of them do in version 2.01, and this practice should be standard in all 2.xx versions and above.