This document provides a tutorial introduction to the International Aid Transparency Initiative (IATI) XML schemas, release 20100707 (version 1.01). The intended audience is information-technology specialists and managers who are implementing or evaluating the IATI XML document types. Readers should have a basic working knowledge of XML and some familiarity with common concepts in the world of international development or humanitarian aid.
This tutorial is a supplement to the detailed schema reference documentation available online at http://www.iatistandard.org/. In case of disagreement, the schema reference documentation — not this tutorial — is the authoritative source.
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.
IATI strongly recommends the use of the Unicode UTF-8 or UTF-16 character encodings to provide support for the widest range of languages. These encodings may be declared at the beginning of XML documents as follows:
<?xml version=”1.0” encoding=”UTF-8”?>
or
<?xml version=”1.0” encoding=”UTF-16”?>
The XML standard requires all conformant software to support both of these encodings, so the choice is up to the publisher. In most cases, UTF-8 should result in smaller documents even for non-alphabetic languages like Han Chinese, since much of an IATI document consists of XML markup, (alphabetic) codes, and numeric values.
IATI discourages the use of non-Unicode character encodings such as “BIG5” or “ISO-8859-1”, since these might not be supported by all XML processing software, and our initiative’s goal is maximum transparency and portability.
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.
Reporting and participating organizations
Every activity description has a single reporting organization, represented by the element reporting-org in the previous examples:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
<reporting-org ref=”ACME”>ACME Foundation</reporting-org>
…
</iati-activity>
This is the document’s author, the organization that’s responsible for the accuracy, completeness, and timeliness of the information in the activity report — in other words, this element fills the same function as a byline in a newspaper story.
The reporting organization is not necessarily involved in the aid activity itself, though in practice it often will be a donor or appealing agency. It is possible that more than one organization will publish reports on the same activity — for example, a donor, an implementing agency, a beneficiary, and an independent aid database might all publish reports about the same activity. Unique identifiers for activities and financial transactions will make it possible to identify duplicate information in different reports, but it is still up to the data user to decide how to handle that duplicate information, and which sources should have the priority.
There is a second element, participating-org, that can list each organization participating in the activity, together with its role, as in the following example:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
…
<participating-org ref=”ACME” role=”Implementing”/>
<participating-org ref=”ABC” role=”Funding”/>
<participating-org ref=”XYZ” role=”Funding”/>
</iati-activity>
In this example, the organization with the identifier “ACME” is an implementing agency, while the organizations with the identifiers “ABC” and “XYZ” are donors contributing funds to the activity. As with reporting-org, participating-org can optionally include the name of the organization:
<participating-org ref=”ABC” role=”Funding”>ABC Fund</participating-org>
If the reporting organization is also participating (as will often be the case), then it must be listed twice:
<reporting-org ref=”ACME”/>
<participating-org ref=”ACME” role=”Implementing”/>
To date, IATI has defined four roles in its Organisation Role code list:
- Funding: an organization providing money or in-kind funding for an activity.
- Extending: the subunit of the funding country or organization, financing the activity from its own budget (e.g. a government agency or department).
- Implementing: an intermediary organization between the one controlling the activity and the ultimate beneficiary.
- Beneficiary: an organization receiving funding for this activity and ultimately carrying it out.
Note that these roles do not define which organization has actually initiated and planned the activity. For development aid, the activity lead will often be a funding or extending organization, such as a national government, national aid agency, or private foundation. For humanitarian aid, the activity lead may actually be an implementing or beneficiary organization, such as a UN agency or NGO, which plans the activity and then appeals for funding from multiple donors.
IATI activity reports provide two different mechanisms for determining where aid money is being spent:
- Jurisdictional (dealing with governments or groups of governments).
- Geographical (dealing with specific locations or areas).
When a national government (for example) wants to know how much aid money is being spent in its country, it can read the jurisdictional markup. The most common element for jurisdictional information is recipient-country, as in the following example:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
…
<recipient-country code=”HT”>Haiti</recipient-country>
…
</iati-activity>
This example specifies that Haiti is the sole partner country for this aid activity. The value of the code attribute is an ISO 3166-1 alpha2 country code (see the IATI Country code list); while the code attribute is not required by the schema, it is strongly recommended to aid in machine processing. The country name is optional, and appears as the element’s content (the xml:lang attribute is allowed to specify the language of the name).
Some activities have more than one partner country; in that case, the activity report will list all of the countries, with the percentage attribute available to specify the percentage of the total budget allocated to each country (if known):
<recipient-country code=”GH” percentage=”40”>Ghana</recipient-country>
<recipient-country code=”BF” percentage=”30”>Burkina Faso</recipient-country>
<recipient-country code=”CI” percentage=”30”>Côte d’Ivoire</recipient-country>
Some activities, in their early stages, may be intended for a general geographical region such as the Middle East or West Indieis, without having (yet) selected specific partner countries. In that case, the recipient-region element allows specifying a broader geographical region:
<recipient-region code=”380”>West Indies</recipient-region>
As with recipient-country, the element may repeated for multiple regions, with an optional percentage attribute:
<recipient-region code=”380” percentage=”50”>West Indies</recipient-region>
<recipient-region code=”489” percentage=”50”>South America</recipient-region>
For recipient-region, IATI uses regional codes defined by the OECD’s Development Assistance Committee (DAC). These codes appear in the IATI Region code list.
(Note: the markup described in this section is not yet in use for most phase one pilots.)
To specify the actual location of aid work, rather than the jurisdiction of the partner country, IATI uses the target-location element, as in the following example:
<iati-activity last-updated-datetime=”2010-04-01T00:00:01”>
…
<target-location code=”GH-AH”>Ashanti Region, Ghana</target-location>
…
</iati-activity>
The code attribute by default specifies an ISO 3166-2 region code, such as “GH-AH” for the Ashanti region of Ghana. To use a different coding system, specify the vocabulary attribute:
<target-location code=”GH02”
vocabulary=”FIPS”>Ashanti Region, Ghana</target-location>
A separate option for specifying a location is the gis attribute, which contains the comma-separated decimal latitude and longitude of a specific point on the earth’s surface:
<target-location gis=”9.4075,-0.853333”/>
This element specifies that the aid will be targeted at a location of 9.4075 degrees latitude (9° 24.45’ N) and -0.853333 degrees longitude (0° 59.20’ W). Future IATI releases may also include support for outlines of geographical areas (such as circles and polygons). The gis attribute is especially useful for plotting aid activities on maps.
Finally, the target-location element may contain free-form text describing a location, with or without the code and gis attributes:
<target-location>Tamale</target-location>
All three methods may be combined where appropriate:
<target-location code=”GH-NP” gis=”9.4075,-0.853333”>Tamale</target-location>
This section introduces the elements describing the milestone dates and status of an activity.
The activity-date element contains a milestone date (past, present, or future) for the activity, as in the following example:
<activity-date type=”start-planned” iso-date=”2010-11-11”/>
The iso-date attribute gives the date in ISO 8601 (YYYY-MM-DD) format: this attribute is optional, but should be included whenever possible.
The type attribute describes the type of milestone date, from the IATI Activity Date code list. Currently, the list includes the following values:
- start-planned: the forecast starting implementation date for the activity.
- start-actual: the actual starting implementation date for the activity, such as the date of first disbursement.
- end-planned: the forecast ending implementation date for the activity.
- end-actual: the actual ending implementation date for the activity, such as the date of final disbursement.
An IATI activity document may repeat the activity-date element once for each type of date (though the *-actual types make sense only after the dates have arrived). Here is an excerpt from the report for a completed activity, including all four date types:
<iati-activity>
…
<activity-date type=”start-planned” iso-date=”2009-04-01”/>
<activity-date type=”start-actual” iso-date=”2009-04-18”/>
<activity-date type=”end-planned” iso-date=”2010-03-31”/>
<activity-date type=”end-actual” iso-date=”2010-03-15”/>
…
</iati-activity>
During early planning, it might not be possible to specify a precise date. A project, for example, might be planned only vaguely for a future year: it is a goal of IATI to allow donors and other participants to provide information as early as possible, to assist with planning in partner countries. As a result, the iati-activity element allows specifying imprecise dates using plain text in the content (optionally combined with the xml:lang attribute):
<activity-date type=”start-planned”
xml:lang=”en”>Late 2012 or early 2013</activity-date>
Note that an IATI activity document should use text instead of an ISO date only when it is not possible to provide a specific date; however, it is always allowed to include the text in addition to an ISO date, as in the following example, which specifies that the activity begins in the organization’s first financial quarter, on 1 April 2010::
<activity-date type=”start-planned”
iso-date=”2010-04-01”>2010 Q1</activity-date>
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>
An IATI activity document can categorize an activity in two different ways:
- by sector, using the sector element
- by policy or theme, using the policy-marker element (not used in phase one pilots)
By default, the sector element uses sector codes defined in the IATI Sector code list, as in the following example:
<sector code=”33181”/>
It is, however, possible to use a different sector code list by specifying it in the vocabulary attribute:
<sector vocabulary=”WB” code=”YC”/>
The IATI Vocabulary code list specifies the recognized vocabularies:
- COFOG: United Nations Classification of the Functions of Government (code list)
- DAC: OECD Development Assistance Committee sector codes (the default, as defined in the IATI Sector code list)
- WB: World Bank (code list)
Activity reports should always include the default (DAC) codes, even if another vocabulary is used as well.
If an activity covers more than one sector, the sector element may be repeated for each one, using the percentage element to show the allocation:
<sector code=”31161” percentage=”50”>Food crop production</sector>
<sector code=”31165” percentage=”50”>Agricultural alternative
production</sector>
Note that this example also includes optional, human-readable text to describe each sector. The percentages for sectors in each vocabulary should add up to 100.
The policy-marker element is similar to sector, but it allows specifying a policy or theme rather than a sector of development. This element is not used in the IATI phase-one pilots, but code lists will be developed for future use. The following example does not use official codes:
<policy-marker code=”111” percentage=”50”>Women’s rights</policy-marker>
<policy-marker code=”112” percentage=”50”>Girls’ education</policy-marker>
There are four elements that specify different attributes of an aid activity:
- default-flow-type — the nature of the assistance provided (e.g. official direct assistance, private NGO funding).
- default-aid-type — the type of aid supplied (e.g. budget support, pooled funds).
- default-finance-type — the type of financing supplied (e.g. debt relief).
- default-tied-status — indication of whether the aid is tied to the purchase of specific goods or services.
- collaboration-type — indication of whether the project is bilateral or multilateral.
The first four elements provide a default value for all of the financial transactions in an activity report. When necessary, they can be overridden for individual transactions using the transaction/flow-type, transaction/aid-type, transaction/finance-type, and transaction/tied-status elements. Here is an example of the default aid type information elements in use:
<activity>
…
<default-flow-type code=”10”>Official Direct Assistance</default-code-type>
<default-aid-type code=”A01”>General Budget Support</default-aid-type>
<default-finance-type code=”810”>Bank Bonds</default-finance-type>
<default-tied-status code=”05”>Untied</default-tied-status>
…
</activity>
The human-readable content is optional (but helpful), and has no fixed format; it is also permissible to use only the raw codes:
<activity>
…
<default-flow-type code=”10”/>
<default-aid-type code=”A01”/>
<default-finance-type code=”810”/>
<default-tied-status code=”05”/>
…
</activity>
Unlike the other four, collaboration-type has no bearing on individual financial transactions, and can be specified only at the top level. It is most useful for major development activities funded by national donors, and specifies whether projects are bilateral (involving just one donor country and the recipient), multilateral (involving multiple donor countries), and so on (see the Collaboration Type code list for details):
<collaboration-type code=”1”>Bilateral</collaboration-type>
These elements use codes from the following lists:
- IATI Flow Type code list for default-flow-type (and transaction/flow-type).
- IATI Aid Type code list for default-aid-type (and transaction/aid-type).
- IATI Finance Type code list for default-finance-type (and transaction/finance-type).
- IATI Tied Status code list for default-tied-status (and transaction/tied-status).
- IATI Collaboration Type code list for collaboration-type.
Financial information is at the heart of IATI — in many ways, it is the most important information about an aid activity, since it allows agencies, national governments, and others with planning future activities.
At the activity level, IATI supports both aggregate financial information for the entire activity in the total-cost element, and records of individual inflows and outflows of money, both planned and actual, in the budget-planned and transaction elements.
To understand how IATI handles financial values, it is useful to start with the total-cost element. The total-cost element specifies the budgeted cost of the activity over its entire lifetime, and appears at the top level of an activity record:
<total-cost currency=”EUR” value-date=”2010-03-31”>2000000</total-cost>
There are three important pieces of information here:
- The currency attribute provides the ISO 4217 code for the currency of the financial value, such as “USD” for US dollars, or “EUR” for Euros. This attribute is required unless the file specifies a default-currency attribute on the parent activity element — in that case, the default currency applies to any financial element that does not have its own currency attribute.
- The required value-date attribute provides an historical reference date for converting the amount to different currencies. For example, if an aid agency announced a project costing USD 500,000 on March 31, 2010, the exchange rate on that date should be used to calculate the equivalent value in other currencies (such as Euros or Pounds Sterling).
- The content of the element gives the total amount as an integer. It must include all required zeros (no abbreviations such as “M” or “B”), and include no commas or decimal places: in other words, “2000000” is acceptable, while “2M”, “2,000,000”, and “2000000.00” are not. IATI does not track fractional amounts, such as pennies.
The transaction element lists money flowing into or out of an aid activity (possibly from or to another activity). Transactions are critical for tracking the flow of money across different activities and avoiding duplicate counting; for example, if Activity A gives €1,000,000 for Somalia to Activity B, Activity B gives Somalia €1,000,000 to Activity C, and Activity C spends €1,000,000 on a development project in Somalia, it must be possible to count that as only €1,000,000 in aid money for Somalia, not €3,000,000. To help accomplish this goal, IATI uses three kinds of unique identifiers:
- Transaction identifiers: when Activity A disburses €1,000,000 to Activity B, Activity A should use the same identifier for its outgoing transaction as Activity B uses for its incoming transaction, so that users know there are not two separate disbursements.
- Activity identifiers: When Activity A gives money to Activity B, the outgoing transaction in the Activity A report includes Activity B’s identifier, and the incoming transaction in Activity B’s report includes Activity A’s identifier.
- Organization identifiers: In addition to the activity, the transactions also identify the organization that is making the payment.
Here is an example of a £100,000 disbursement from the fictitious ACME Foundation to the fictitious ACE Agency, from ACME’s perspective:
<transaction flow=”outgoing” ref=”ACME:transactions:12345”>
<value currency=”GBP” value-date=”2010-03-15”>100000</value>
<transaction-date type=”announced” iso-date=”2010-03-01”/>
<transaction-date type=”committed” iso-date=”2010-03-15”/>
<transaction-type code=”D”>disbursement</transaction-type>
<provider-org ref=”ACME”>ACME Foundation</provider-org>
<receiver-org ref=”ACE”>ACE Agency</receiver-org>
<receiver-activity ref=”ACE:activities:12345”/>
</transaction>
This markup describes transaction “ACME:transactions:12345”, stating that ACME committed ₤100,000 to ACE’s aid activity “ACE:activities:12345” through the activity currently being described. The disbursement was announced on 1 March 2010, and a legally-binding commitment was signed on 15 March 2010, which should also be used as the reference date for converting to other currencies. The money is going into ACE’s activity “ACE:activities:12345”.
Here is the same transaction from the perspective of ACE’s activity “ACE:activities:12345”:
<transaction flow=”incoming” ref=”ACME:transactions:12345”>
<value currency=”GBP” value-date=”2010-03-15”>100000</value>
<transaction-date type=”announced” iso-date=”2010-03-01”/>
<transaction-date type=”committed” iso-date=”2010-03-15”/>
<transaction-type code=”C”>commitment</transaction-type>
<provider-org ref=”ACME”>ACME Foundation</provider-org>
<receiver-org ref=”ACE”>ACE Agency</receiver-org>
<provider-activity ref=”ACME:1011-12”/>
</transaction>
Most of the content is the same, except that for ACE’s activity, this is an incoming transaction (as specified by the flow attribute), and the provider-activity element specifies the activity that is providing the money (ACME’s), rather than its own activity that is receiving it.
The transaction-type element uses the IATI Transaction Type code list, which currently contains the following codes:
- C: commitment — a firm written obligation from the donor.
- D: disbursement — a transfer of funds from one organization to another.
- E: expenditure — a final outlay of funds on goods or services for an activity.
- LR: loan repayment — a final outlay of funds against the principal of a loan.
- IR: interest repayment — a final outlay of funds against the interest of a loan.
A transaction may additionally contain the elements flow-type, aid-type, finance-type, and tied-status. These have the same meaning and content as the default-flow-type, default-aid-type, default-finance-type, and default-tied-status elements for the activity as a whole (described above), but can be used to override any of the defaults for a specific transaction. For example, the following specifies that a specific transaction is tied:
<transaction flow=”outgoing” ref=”ACME:transactions:67890”>
<value value-date=”2010-10-01”>500000</value>
<tied-status code=”04”>tied</tied-status>
…
</transaction>
The budget-planned element lists the planned future expenditures for an activity. This element has many similarities to transaction:
<budget-planned period=”annual”>
<value value-date=”2010-10-01”>1500000</value>
<period-start iso-date=”2011-04-01”/>
<period-end iso-date=”2012-03-31”/>
<receiver-org ref=”ACE”/>
</budget-planned>
The period attribute specifies an accounting period; allowed values are “annual”, “quarterly”, and “monthly”. The period-start and period-end elements provide the actual start and end dates of the period — in this example, the organization’s fiscal year begins on 1 April and ends on 31 March. The value and receiver-org elements are the same as in transaction.
Note that there is no flow attribute, because IATI activity reports include only planned outgoing disbursements — the budget-planned element is meant to give an indication of how much an activity is planning to expend or disburse in the medium term, beyond the current commitment period. Any money which has been firmly commited should appear in a transaction element instead. There is also no receiver-activity element (though, as in transaction, receiver-org has an optional attribute receiver-activity-id to include the receiving organization’s internal identifier).
The budget-planned element should be repeated for each receiving organization and accounting period for which planning information is available:
<budget-planned period=”quarterly”>
<value currency=”GBP” value-date=”2010-10-01”>175000</value>
<period-start iso-date=”2011-04-01”/>
<period-end iso-date=”2011-06-30”/>
<receiver-org ref=”ACE”/>
</budget-planned>
<budget-planned period=”quarterly”>
<value currency=”GBP” value-date=”2010-10-01”>300000</value>
<period-start iso-date=”2011-07-01”/>
<period-end iso-date=”2011-09-30”/>
<receiver-org ref=”ACE”/>
</budget-planned>
<budget-planned period=”quarterly”>
<value currency=”GBP” value-date=”2010-10-01”>150000</value>
<period-start iso-date=”2011-10-01”/>
<period-end iso-date=”2011-12-31”/>
<receiver-org ref=”ACE”/>
</budget-planned>
<budget-planned period=”quarterly”>
<value currency=”GBP” value-date=”2010-10-01”>100000</value>
<period-start iso-date=”2012-01-01”/>
<period-end iso-date=”2012-03-31”/>
<receiver-org ref=”ACE”/>
</budget-planned>
In this example, the activity has budgeted a ₤175,000 disbursement to ACE in Q1, a ₤300,000 disbursement in Q2, a ₤150,000 disbursement in Q3, and a ₤100,000 disbursement in Q4, but has not yet made a legally-binding commitment to provide the money.
This section describe relationships to other activities and to broader initiatives.
The financial transactions described above provide one type of link among activities, by tracing the flow of funds, by there are other types of connections that do not necessarily involve exchanging funds. To represent these relationships, IATI uses the related-activity element:
<related-activity ref=”ACME:activities:67890” type=”Parent”/>
This example states that a different activity, “ACME:activities:67890”, is the parent activity of the one currently being described. The allowed values for the type attribute appear in the IATI Related Activity Type code list:
- Parent: the referenced activity is the parent (a superset) of the current activity.
- Child: the referenced activity is a sub-component of the current activity.
- Sibling: the referenced activity is a sub-component of a common parent activity.
As with other IATI markup, this element may be repeated as necessary:
<related-activity ref=”ACME:activities:67890” type=”Parent”/>
<related-activity ref=”ACME:activities:11111” type=”Sibling”/>
<related-activity ref=”ACME:activities:22222” type=”Sibling”/>
An activity may also have relationships to intiatives that are not aid activities in themselves, but are still useful for classifying and grouping activities. For example, the United Nations Office for the Coordination of Humanitarian Affairs (UN-OCHA) issues appeals for aid after humanitarian disasters such as the 2010 Haiti earthquake, and agencies initiate projects under the umbrella of those appeals.
To specify that an activity is related to an appeal or other initiative (such as a special G8 or UN initiative), use the related-initiative element:
<related-initiative ref=”OCHA:haiti2010”
type=”appeal”>Haiti 2010 appeal</related-initiative>
As with all elements using a ref or code attribute, the human-readable content (“Haiti 2010 appeal”) is optional.
There are two elements to provide contact information for an activity: contact-info and activity-website.
The contact-info element contains a series of optional sub-elements providing information about an official contact person for the activity, as in the following example:
<contact-info>
<organization>ACME Foundation</organization>
<person-name>Muhammad Said</person-name>
<telephone>+44 555 555-5555</telephone>
<email>muhammad@example.org</email>
<mailing-address>
ACME Foundation
Box 555 123 High Street,
Cowsbury UK 123456
</mailing-address>
</contact-info>
Since IATI files are meant to be shared publicly, it is important not to release personal information inappropriately; for example, work email, addresses, and phone numbers should be used to protect personal privacy. IATI does not require the release of any specific contact information, and in many cases, simply a name and professional email address will be sufficient:
<contact-info>
<organization>ACME Foundation</organization>
<person-name>Muhammad Said</person-name>
<email>muhammad@example.org</email>
</contact-info>
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.
The legacy-data element holds an original value for an existing IATI data element. For example, if the fictitious ACME Foundation used a different set of codes for collaboration-type, it could include the following:
<legacy-data iati-equivalent=”collaboration-type”
name=”project-type” value=”Funding”/>
The iati-equivalent attribute holds the name of the equivalent IATI element, the name attribute contains the reporting organization’s local name for the data field, and the value attribute contains the original (legacy) data value.
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
