XML Schema Tutorial
Activities document walk-through
Basic structure and date/time generated
Top level of an activity report
Reporting and participating organizations
This section provides general background information about IATI documents.
IATI has defined two XML document types:
- The Organizations document, describing a single organization (such as a donor, foundation, agency, or NGO) involved in aid work. This document may include aggregate budget information for the organization.
- The Activities document, describing a single aid activity (such as a project or humanitarian appeal). This document may include specific budget information for the activity, including inflows and outflows of money.
For example, let’s say that in 2011 the fictitious ACME Aid Agency were funding three projects, divided evenly between Rwanda and Burundi, each worth €500,000:
- The organization document would state that ACME has budgeted a total of €3,000,000 for aid in 2011, and would further specify that €1,500,000 was allocated for activities in Rwanda and €1,500,000 was allocated for activities in Burundi.
- The three activity documents would each state that the total budget of the activity was €1,000,000, of which €500,000 was allocated for Rwanda, and €500,000 allocated for Burundi.
The formal definitions of these document types appear as two XML schemas, iati-organizations-schema.xsd and iati-activities-schema.xsd. It is important to understand, however, that these schemas do not provide a complete definition of the IATI document types: it is possible for a document to validate against one of the schemas and still not be a conformant IATI aid document.
Since the activities document type is the most widely used (and the best defined at this early stage of IATI development), this tutorial will concentrate solely on it; however, many of the points made in this tutorial also apply to the organization document type.
Throughout this tutorial, examples may contain an ellipsis (“…”) to show that part of the expected markup has been left out for brevity or clarity. Literal XML examples appear in monospace type, while XML element or attribute names mentioned inline appear in italic type.
Activities document walk-through
This is the main body of the tutorial, containing a walk-through of the most important parts of the IATI activities document type.
Basic structure and date/time generated
An activity document may include descriptions for one or more activities, like this:
<?xml version=”1.0” encoding=”UTF-8”?>
<iati-activities version=”1.01”
generated-datetime=”2010-07-12T13:26:00-0400”>
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
<!– first activity –>
…
</iati-activity>
<iati-activity last-updated-datetime=”2010-07-01T09:00:01-04:00”>
<!– second activity –>
…
</iati-activity>
…
</iati-activities>
The top-level iati-activities element is a container for as many activity reports as needed, each represented by its own iati-activity element.
The version attribute specifies the version of the IATI specification in use (currently “1.01”). IATI’s goal is not to introduce backward-incompatibilities into different versions of the schema, but the version number may still be useful for processing and validation. If omitted, the version defaults to “1.0”.
The generated-datetime attribute is not required by the schema, but it is strongly recommended. It specifies when this report was generated using the extended ISO 8601 date/time format, so “2010-07-12T13:26:00-04:00” represents July 12, 2010 at 1:26:00 PM 4:00 hours before UTC/Greenwich Mean Time (in other words, North American Eastern Daylight Time). This date/time stamp is important for processing IATI information, because the most recent data counts: if a data consumer receives a report with a generated-datetime value later than the one in this report, it should discard the data from this report and replace it with the data in the newer report. Note that the generated-datetime should be updated every time a new report is generated, even if none of the information in it has changed.
The remainder of the tutorial will focus on the individual iati-activity element that appears one or more times inside the iati-activities container element.
Top level of an activity report
Inside the iati-activities container appears a series of one or more iati-activity elements, each describing an individual aid activity (such as a development project or humanitarian appeal):
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
<iati-identifier>ACME:12345</iati-identifier>
<reporting-organization ref=”ACME”/>
<title xml:lang=”en”>Sample Activity Report</title>
…
</iati-activity>
The last-updated-datetime attribute is not required by the schema, but it is strongly recommended. It specifies the last time a change was made to this activity data, using the extended ISO 8601 date/time format (so that “2010-04-01T00:00:01” represents one second after midnight UTC/GMT on April 1, 2010). This date/timestamp should change only when a field inside iati-activity is added, removed, or modified; if the data content is unchanged since the last report, the last-updated-datetime value should remain the same (though the generated-datetime attribute on the iati-activities container would still be updated).
The iati-identifier element contains a unique identifier for the activity: this identifier must remain the same in every report, no matter what other changes take place (it is what database specialists refer to as a “primary key”). For the current IATI release, the activity identifier uses an organization identifier assigned by IATI (and specified in the IATI organisation_identifiers code list) followed by a colon (“:”) and an identifier string assigned by the organization, such as an internal project tracking number. It is the organization’s responsibility to ensure that the part after the colon is unique among all other identifiers it assigns. In this example, we have the fictional aid organization with the IATI identifier “ACME”, which identifiers this activity using the number “12345”, so the IATI identifier is “ACME:12345”. (Future releases may use a different scheme, such as a URL, so that non-IATI-member organizations can also participate).
IATI also assigns unique identifiers to financial transactions (such as contributions), organizations (such as donors), and aid initiatives (such as humanitarian appeals), so that these can be connected across multiple reports.
The order of subelements inside iati-activity is not significant: the reporting organization is free to rearrange them however desired. The following example is functionally identical to the previous one, despite the fact that the order of elements has changed:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
<reporting-organization ref=”ACME”/>
<title xml:lang=”en”>Sample Activity Report</title>
<iati-identifier>ACME:12345</iati-identifier>
…
</iati-activity>
Multiple languages
The title element in the previous examples contains a human-readable title for the aid activity: in this case, “Sample Activity Report.” The xml:lang attribute uses the ISO 639 language code “en” to specify that the title appears in English. For organizations generating multilingual reports, the title element may be repeated with different values of xml:lang; in the following example, the title appears English, French, and Spanish:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
…
<title xml:lang=”en”>Sample Activity Report</title>
<title xml:lang=”fr”>Rapport d’activité échantillon</title>
<title xml:lang=”es”>Muestra de informe de actividades</title>
…
</iati-activity>
There are many other IATI elements that may contain human-readable text, and each of these may also take the xml:lang attribute. Two common examples are the description element and the reporting-org element (which may include the organization’s name as well as its identifier):
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
…
<reporting-org xml:lang=”en” ref=”ACME:12345”>ACME
Foundation</reporting-org>
<title xml:lang=”en”>Sample Activity Report</title>
<description xml:lang=”en”>
This is a longer description of the sample activity.
It may have multiple paragraphs and other kinds of
information.
</description>
…
</iati-activity>
It can be tedious repeating the xml:lang attribute for every element that contains human-readable text, especially when a report uses only a single language. As an alternative, the xml:lang attribute may be specified just once for the iati-activity element to provide a default language for the entire activity report:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01” xml:lang=”en”>
…
<reporting-org ref=”ACME:12345”>ACME Foundation</reporting-org>
<title>Sample Activity Report</title>
<description>
This is a longer description of the sample activity.
It may have multiple paragraphs and other kinds of
information.
</description>
…
</iati-activity>
The remaining examples in this tutorial will assume that a default language has been set, and will omit the xml:lang attribute.
The activity-status element specifies the current status of the activity (at the time of reporting):
<activity-status code=”02”/>
The IATI Activity Status code list specifies the allowed numeric values for the code attribute:
- 01: pipeline/identification
- 02: implementation
- 03: completion
- 04: post-completion
- 05: cancelled
Like the activity-date element, the activity-status element allows plain text content as well, to provide additional information about the status for human readers:
<activity-status code=”01”>Awaiting final budget</activity-status>
The activity-website element simply contains a URL that represents this specific activity:
<activity-website>http://example.org/acme/12345.html</activity-website>
Ideally, the URL should be a link directly to a page describing this activity (if one exists), not a general link to an aid organization’s home page.
There will be situations where reporting organizations want to publish additional data that are not covered by the default IATI elements, or want to specify the data using the original formats or values to avoid information loss. IATI provides two mechanisms for doing so:
- Use an XML namespace to extend the schema.
- Use the legacy-data element to provide original data values.
The first approach allows reporting organizations to invent any required markup and add it to an IATI activity report. IATI users who don’t recognize the extended markup are required simply to ignore it, without reporting an error. Here is an example:
<iati-activity xmlns:acme=”http://example.org/acme/ns#”>
…
<acme:risk-level>3</acme:risk-level>
…
</iati-activity>
In this example, ACME has defined its own namespace using the URL “http://example.org/acme/ns#” and mapped that to the prefix “acme”. It then adds the new element, acme:risk-level, to provide information about its risk assessment for the activity. IATI users who don’t recognize the “http://example.org/acme/ns#” namespace are required to ignore the acme:risk element rather than reporting an error, so the extended markup does not harm compatibility. Users who are familiar with the namespace, however, can take advantage of the additional information.
This tutorial has provided a detailed introduction to the IATI XML document format for aid activities, but it is not a complete reference guide. To produce or use IATI data files, you should now turn to the official reference documentation available online at http://iatistandard.org/.
There is also an IATI organisation document type, which will be the subject of a future tutorial.
DAC: the Development Assistance Committee of the Organisation for Economic Co-operation and Development (OECD). DAC defines some aid-related code lists used by IATI. http://www.oecd.org/dac/
IATI: the International Aid Transparency Initiative.http://iatistandard.org/
Schemas: http://iatistandard.org/schema/
Code lists: http://iatistandard.org/codelists/
ISO 691: Codes for the Representation of Names of Languages (IATI uses the 2-letter abbreviations). http://www.loc.gov/standards/iso639-2/php/English_list.php
ISO 3166:Codes for the representation of names of countries and their subdivisions (IATI uses the alpha-2 country codes). http://www.iso.org/iso/country_codes.htm
ISO 4217:Currency and Funds Name and Code Elements (IATI uses the alphabetic codes): http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list-1.htm
ISO 8601:Representation of Dates and Times (IATI uses the W3C profile described in http://www.w3.org/TR/NOTE-datetime)
NGO: a non-governmental organization, such as Médecins san frontières.
XML: the Extensible Markup Language.http://www.w3.org/XML/
XML Namespace: a mechanism for extending XML vocabularies safely. http://www.w3.org/TR/REC-xml-names/
XML Schema: a formal description of the structure rules governing an XML document type. http://www.w3.org/XML/Schema.html