How it Works

Adding tags to #HXL — Figure 1: Adding a row of #HXL hashtags to an existing dataset.

HXL (pronounced “HEX-ell”) works with your existing spreadsheets and other humanitarian data. Simply add a new row between the last row of headers and the first row of data values, as show in Figure 1.

Hashtags

In your new row, add a HXL hashtag for each column that you would like to label. For example, if the column contains the number of people in need of humanitarian assistance, you could label the column with the hashtag #inneed.

(Read the full list of core HXL hashtags.)

Attributes

You can use HXL attributes to refine the meaning of the hashtags. For example, if the column contained the number of girls in need of humanitarian assistance, you could add the attributes +f for “female” and +children (the order of the attributes does not matter):

#inneed +f +children

(Read the full list of core HXL attributes.)

Help choosing hashtags and attributes

There are a few sources and tools to help you choose the most-interoperable HXL hashtags and attributes for your columns:

The HXL Postcard, a small cheatsheet that you an print on a postcard and bring with you into the field.
HXL Tag Assist, real-world examples of HXL hashtags in context.
The HXL hashtag chooser, and early release of a third-party tool that prompts you with questions about the information you want to tag.

It is not necessary to add a HXL hashtag to every column. The HXL Working Group recommends tagging the columns that are most-likely to be useful for interoperability with other humanitarian datasets, and also those that you would like to be able to use with HXL tools.

Using HXL with JSON data

It is also possible to add HXL hashtags to JSON data (a format often used by web applications).

FAQ

General

Does HXL require special technical skills?

If you know how to edit a spreadsheet, then you are ready to share HXL data. You simply insert one extra row in any existing spreadsheet and fill it with humanitarian hashtags identifying the type of information in each column.
This is an important design criterion for HXL: that it fit in with existing skills in the humanitarian community, rather than requiring retraining. With thousands of humanitarian organisations responding to crises around the world, it would not be practical to expect you all to train staff and volunteers to learn to use a more-complex data structure like XML, JSON, or RDF, or to all learn and adopt additional software to support one of those formats.
Some larger humanitarian organisations don’t rely exclusively on spreadsheets, but have built special applications for data management. For example, UNHCR operates a series of operational data portals that generate CSV data for download from their information systems. HXL can work with systems like these just as easily as it can work with hand-created spreadsheets. Again, no additional skills are required from the systems’ development teams: simply add an additional row of HXL hashtags to the CSV data that you’re already exporting, and then others will be able to analyse and integrate it more easily.

What software tools are available for HXL data?

To create HXL data, all you need is a spreadsheet application, such as Excel or Google Sheets. To help with processing and analysing HXL data, we have created a collection of free software tools.
HXL 1.0 beta core schema. A HXL-formatted schema for validating HXL datasets (e.g. using the scripts in libhxl-python, below). You can create your own schema for specific applications.
HXL tools and Python library (github). Public-domain command-line tools and Python software library for working with HXL data.
HXL proxy (github). Public-domain source code for a Python-based online service for analysing and visualising HXL-encoded data. You can see this code running live in the HXL Proxy. User documentation is available.
HXL Javascript library (github). A public-domain software library for working with HXL data in inside a web browser using Javascript.
Not yet updated for 1.0 beta HXL PHP library(github). A public-domain software library for working with HXL data in the PHP programming language.
HXL Java library(github). A public-domain software library for working with HXL data in the Java programming language.

What’s different about HXL?

Inspired by social-media hashtags, HXL fits in with the way you work and helps you add value to the data you’re already creating, rather than trying to force you to do things differently. Unlike most data standards, HXL is cooperative rather than competitive. A competitive standard typically considers the way you currently work to be a problem, and starts with a set of demands:

Switch to a different data format (and acquire and learn new software tools).
Change the information you share (and the way your organisation collects and uses that information).
Abandon what is valuable and unique about your organisation’s data (and conform to the common denominator).

For HXL, we reversed the process and started by asking how you’re working right now, then thought about how we can build a cooperative standard to enhance it:

You told us that most humanitarian organisations use spreadsheets for data sharing, so HXL works with your existing spreadsheets.
You told us that every crisis and activity has different data requirements, so HXL offers a selection of hashtags that you can mix and match to suit your reporting needs.
You told us that sometimes your organisation collects types of information that no one else has, so HXL allows you to leave columns untagged, or to invent your own hashtags when you still want to share.

With HXL, there’s no new reporting channel and no new skills requirements. We know that you have more-important things to do than reporting, so we’ve designed HXL to minimise the work and maximize the value of sharing information.

Who created the HXL standard?

Representatives from the Humanitarian Innovation Fund, IOM, OCHA, Save the Children, UNHCR, UNICEF, USAID, the World Bank, and the World Food Program made up the HXL Working Group. The HXL standard is the product of a multi-organisation working group, with support from the members of a community mailing list.
Since the HXL 1.1 release on 2018-04-30, the HXL working group has included the following members and organisations: Andrej Verity (UNOCHA),David Megginson (UNOCHA; WG chair),Helen Campbell (British Red Cross),Jann Rapp (INSO),John Adams (UK DFID),John Crowley (IFRC),Kashif Nadeem (IOM),Mariann Urban (UNHCR),Michael Rans (UNOCHA),Simon Johnson (British Red Cross),Sylvain Ponserre (IDMC), and Wesley DeWitt (World Bank).
The Netherlands Ministry of Foreign Affairs and the Education Above All Foundation kindly provide ongoing funding to support HXL standards development.

How can we learn more about HXL?

How can we get involved with defining the standard?

HXL tags

How do I distinguish individuals from households?

HXL uses the attribute +ind to specify that a column of numbers applies to individuals, or +hh if the column applies to households (individuals is assumed by default). So the number of refugee households targeted for assistance would be #targeted +refugees +hh

How do I tag columns in different languages?

A HXL attribute beginning with “i_” followed by a 2-letter ISO 639 language code specifies the language of the text in a column. For example, if your dataset contains governorate names in both Arabic and French, you can tag the two columns with #adm1 +name +i_ar and #adm1 +name +i_fr to distinguish them.

How do I tag sex- and age-disaggregated data?

HXL has a selection of attributes for distinguishing sex and age. For sex, it has +f for female, +m for male, and +i for non-gender-binary; for broad age groups, it has +infants, +children, +adolescents, +adults, and +elderly. You can also use +total to distinguish a column that sums up the others. Here are some examples, using #affected +idps (number of internally-displaced people) as a base:
#affected +idps +f +children
number of internally-displaced girls #affected +idps +m +adults number of internally-displaced men
#affected +idps +total total number of internally-displaced people
Sometimes, you will want to include more-specific age groups in addition to the broad ones in the HXL core. To do that, create your own attribute with the starting with “age_” followed by the first number, an underscore, and a second number. For example, to tag girls age 5-12, you could use #affected +f +children +age_5_12. Note that it’s still important to include the general +children attribute.

Do I have to add hashtags to all the columns in my spreadsheet?

No. It is fine to leave some columns untagged, especially if they’re highly-specialised data that wouldn’t be of general interest. However, if the answer to any of these questions is “yes,” we strongly recommend tagging:

Is the column important for connecting your data with related datasets (e.g. locations, dates, sectors, org names, population figures)?
Do you want to be able to work on the data in the column using HXL-aware tools (transform, validate, visualise, search, etc)?
Do you want to be able to operate on the data yourself, even if the column orders or headers change (e.g. importing into a database)?

What do I do if no HXL hashtag matches my data?

If no HXL hashtag is a perfect match, you still have a few options:

You can use a more general hashtag combined with attributes, e.g. #affected +refugees +injured +elderly +f for the number of elderly refugee women injured.
You can use the general #indicator hashtag combined with your own custom attribute to identify an indicator specific to your own organisation, project, or cluster, e.g. #indicator +facilities_damaged +num for the number of facilities damaged (where +facilities_damaged is the attribute that you created).
If no general hashtag applies, you can create your own custom hashtag beginning with “x_”, e.g. #x_virulence for the virulence of a disease.

More information is available in the HXL standard, 3.2. Creating extension hashtags

OCHA Services