1. Introduction

This document is part of the Humanitarian Exchange Language (HXL), a standard for increasing the efficiency and effectiveness of data exchange during humanitarian crises.

The HXL standard consists of two normative parts:

1. HXL tagging conventions (this document) — instructions for adding HXL tags to spreadsheets.
2. HXL hashtag dictionary — a list of hashtags for identifying humanitarian data fields.

There are also two non-normative annexes:

1. HXL postcards — two-sided 10×15 cm (4×6 in) cards in multiple languages, for quick reference.
2. Classification codes — recommended taxonomies and code lists for use in HXL-encoded datasets.

2. Adding HXL tags to data

Consider the following simple spreadsheet:

Datasets like this — longer, of course, and with more columns — are the backbone of humanitarian information management, and they provide the input for most reports, maps, and visualisations coming out of a crisis. Unfortunately, creating those data products is time-consuming, and responders have to duplicate the work from crisis to crisis and even dataset to dataset, because it is hard to build reusable software tools that can understand the many different ways responders may choose to label their data. For example, the text header of the last column could have appeared in dozens of variants, and in several different languages:

• Number affected
• Affected
• People affected
• # de personnes concernées
• Afectadas/os
• عدد الأشخاص المتضررين

Software tools need to be able to recognise that the figures in the third column refer to the number of people affected — regardless of how the data provider has decided to label it in the spreadsheet — so HXL adds a second header row containing short hashtags:

Now, whether the text at the top of the column reads “Number affected” or “عدد الأشخاص المتضررين”, software for cleaning, validating, analysing, mapping, or visualising the data can automatically recognise the hashtag #affected and use the figures below accordingly.

More than one row of headers may appear above the HXL hashtag row — the hashtags themselves act as a marker to show automated systems where the headers end and the data begins:

HXL software should expect to find the hashtag row anywhere within the first 25 rows of a dataset.

3. Structure of a HXL tag

The root of a HXL hashtag follows the same syntactic rules as a Twitter hashtag: it begins with the octothorpe/pound sign (“#”) and contains only unaccented Roman alphabetic characters (so-called “ASCII letters,” “a” to “z”), Arabic numerals (“0” to “9”), and the underscore symbol (“_”). The first character must be alphabetic, and character case does not matter (#ADM1 and #adm1 are the same hashtag, though lower case is preferred for stylistic reasons). Here are some examples of syntactically-valid HXL hashtags:

• #sector
• #org
• #households
• #impact

4. Special cases

This section describes how to use HXL to deal with special cases that do not normally fit well into a tabular data model.

Appendix A: Changes from previous versions

Changes from 1.0 beta to 1.0 final:

• Explicitly state that the text of the standard is released into the public domain.
• Many minor copy-editing and text-formatting changes.

Changes from 1.0 alpha to 1.0 beta:

• Removed compact disaggregated syntax and language extensions.
• Added tag attributes.
• Added recommendations for language attributes.

Appendix B: Formal grammar of a HXL tag

The following Backus-Naur Form grammar, with regular expressions, defines the allowed content of a HXL tag (terminals are in uppercase):

<hxl-tag>               ::= <tag>
    | <tag> <attributes>
    | <tag> WHITESPACE <attributes>

    <attributes>            ::= <attribute>
    | <attributes> <attribute>
    | <attributes> WHITESPACE <attribute>

    <tag>                   ::=    "#" TOKEN

    <attribute>             ::= "+" TOKEN

    TOKEN                   ::=      /[a-zA-Z][a-zA-Z0-9_]*/

    WHITESPACE              ::=    /[ \t\n\r]+/

Appendix C: Credits

HXL is a group effort of many people and organisations, including a wider community of over 100 members of the hxlproject@googlegroups.com public mailing list. Chad Hendrix (OCHA) was the founder of the HXL standards effort, and Carsten Keßler (Hunter College) was the original technical lead. Since 2013, Sarah Telford (OCHA) has been overall programme manager and David Megginson (OCHA) has served as standards lead and chair, while John Crowley helped with outreach and governance in late 2014 and early 2015, and Aidan McGuire (ScraperWiki) has provided project management since 2015. Generous funding for HXL research and development in 2014 came from the Humanitarian Innovation Fund, and OCHA has supported continuing work. The Paul Allen Foundation has generously agreed to fund HXL work through 2016.

During 2014, the HXL Working Group included Albert Gembara (USAID), Andrej Verity (OCHA), Andrew Alspach (UNHCR), David Megginson (OCHA), Gavin Wood (UNICEF), John Crowley (World Bank), Lauren Burns (Save the Children), Maurizio Blasilli (WFP), Muhammad Rizki (IOM, later replaced by Ivan Vukovic), and Paul Currion (Humanitarian Innovation Fund).

Beginning in 2015, the HXL Working Group has included Andrej Verity (OCHA), David Megginson (OCHA), John Adams (DFID), John Crowley (originally, World Bank), Justine Mackinnon (Standby Task Force), Laurent Pitoiset (UNHCR), Sara-Jayne Terp (ThoughtWorks), and Simon Johnson (British Red Cross).