Keeping / maintaining Organisation names in IATI data

(Steven Flower) #1

It is understood that 2.01 places emphasis on the code over the code name within the data. Hence

<activity-status code="2 />

is “preferable” to

<activity-status code="2">Implementation</activity-status>

I understand that this is because the data should - as far as possible - be language neutral, so that data users can then implement multi-lingual instances of IATI, by utilising translations of the code lists, etc

However, I just wanted to state that this logic might not best be applied to the describing organisations in IATI. By this, I mean that whilst the @ref code is very important for IATI when describing an organisation, the name (in any version of the standard) still also has a use. Namely - it’s because there isn’t a lookup list for all the possible organisations in the world (or IATI) it becomes difficult for data users to dereference organisations when just a @ref exists.

Whilst such a service would no doubt be useful, it might be worth stating that

<participating-org ref="GB-1" role="Funding" type="10">DfID</participating-org>

could be more help to a data user than:

<participating-org ref="GB-1" role="Funding" type="10"/> 

Example: take a look at this data on d-portal*:

The XML for the participating-org does not include the name, just the @ref. d-portal does not therefore display an organisation name - because it hasn’t (I guess) a list to lookup against (and GB-1 is not the best example)

Perhaps we need to establish clearer consensus / guidance on this? Do others think this might be a potential issue (or not)?

*NB: this isn’t a critique of d-portal - just an illustration of the challenges that we could face

(Dale Potter) #2

Hi Steven - good to bring this up. My immediate reaction was that this shows a need for an organisational look-up tool in order to dereference a given IATI organisation identifier. However, you’re right that such a tool would not be able to identify every possible organisational identifier even for the same organisation (bearing in mind that an organisation may be listed with multiple registration agencies), let alone all organisations in the world!

Therefore it would probably make sense to include some textual reference alongside any field referencing an organisation identifier, as you suggest. We’ve added this to the issue backlog to discuss further amongst the team.

In any case, it’s on my (albeit long) task list to find out about previous work on an organisational look-up tool. @TimDavies may have done some work on this previously?

(Tim Davies) #3

Hey Dale,

A few years ago I built a simple lookup against the then spreadsheet based Organisation ID codelist - just to help people (a) identify prefixes; (b) lookup organisations if a search for IDs for the registration agency existed;

It is at, but no longer working due to the move away from maintaining Organisation ID prefixes in a Google spreadsheet.

I think the solution in this space is definitely something to pursue through the Joined Up Data Alliance: a shared project to create a platform which would:

(a) Enable easier lookup of prefixes;
(b) If a third-party reconciliation service exists for IDs, map an endpoint to that;

E.g. rather than trying to maintain a full organization lookup, which is a prohibitively complex task (just ask Open Corporates about their hosting bill…), proxy requests to GB-COH to open corporates, for example, or to some other source that maintains an authoritative list of companies.

This noted: having people still include the name they know an organisation by in their IATI files is really useful, and it only only helps with cases where there isn’t an existing identifier, or lookup service - but also helps with discovery of the ‘Also Known As’ (AKAs) of organisations.

(Dale Potter) #4

Thanks for this extra information @TimDavies - very useful to see the context of where things have been in the past. You’re right that this would definitely be one to explore with the Joined Up Data Alliance. I’ve made a note to draft up some ideas shortly. @bill_anderson is also thinking about the vision for this too.

(Steven Flower) #5

In the meantime, should there be some guidance on this page, regarding the use of org names: ?

(Dale Potter) #6

Thanks Steven, this was touched on at the last Tech Team Issue call and will be discussed in more detail in the next one in a couple weeks.

(Michael Medley) #7

Is there a comprehensive list of valid values one can use for reporting-org in the Datastore API? It would help me if there were, especially if it were machine-readable and cross-referenced with the text names that have been used against the codes. Such a list would (perhaps obviously) include all the organizations that HAVE reported rather than all the organizations in the world.

(Yohanna Loucheur) #8

I’m a bit confused about what the issue is. Isn’t this addressed by using the “narrative” element along with the identifier? It would be possible for the D-Portal (or other sites) to show the content of the narrative element along with the ID.

(Steven Flower) #9

Thanks all

@dalepotter would be good to know any plans/timescales

@MichaelMedley afaik such a list isnt a hand. Perhaps that should be a datastore API query in itself? Additionally, there is a field for “IATI identifier” held in the Registry, so that could be useful (although not accessible via However, note that these values don’t always match the data: Maybe this is a new thread?

@YohannaLoucheur yes, in 2.01 the narrative element can be used to provide the organisation name. My original observation was that a name should ALWAYS be provided for an organisation, alongside the structured reference/identifier - as these alone cannot always be dereferenced. In 2.01, we dont seem to be clear on this:

On participating-org:

May contain the organisation name as narrative.

If @ref is not present then the narrative MUST contain the name of the organisation.

Hence - this could also be read that it is fine to just include the organisation ref alone, with no name.

(Yohanna Loucheur) #10

So it would be a simple case of clearer guidance then, to make sure the name is included in the narrative element. A best practice, so to speak.

I now recall we had this discussion in DFATD - indeed some people assumed we would only use the ID, but I insisted that we should also include the name, for ease of reference.

I still think it would make sense for the D-Portal to use the narrative element along with the ID, if it isn’t already the case.

(Rory Scott) #11

Hi Steven,

We recently had a discussion which touched on your observation of 2.01 and earlier documentation’s lack of clarity on participating-org's narrative. Could I invite you to expand on it a bit, and add it to our 2.02 proposals page?


(Steven Flower) #12


I dont see this being related to 2.02. It’s more about guidance across all versions of IATI, but particularly for 2.01 - where emphasis was placed on not using a name with a code. This is about making it clear that the data would be useful when an org name was included.

(Bill Anderson) #13

There are a couple of issues worthy of discussion here:

  • If we had a proper utility by which the name associated with an organisation identifier could be discovered our guidance could be the same as our guidance for code descriptions. Is the building of such an utility a priority?
  • In the absence of such a utility we need to change the guidance that this is a recommended rather than optional element. Logically they may mean the same thing, but I think this is an important enough issue for the guidance to be included in the schema definition. Hence the suggestion that we consider it for 2.02

(Steven Flower) #14

OK - have added something around the second point at

(Tim Davies) #15

There are a couple of issues here when it comes to a utility:

(1) An approach to look-up official names from those registration agencies which provide open data could be part of Joined Up Data work on Org IDs.

This could be a relatively low-lift tool that provides wrappers around existing lookup platforms (e.g. Open Corporates) rather than trying to provide and maintain the quality of its own lookup list.

(2) An approach to look-up names where no open data list exists is more complex - and relies on at least some IATI publishers including names in their files

I.e. the other way a tool can work is to read in all the IATI files published, look for mapping between IDs and Names, and then allow others to lookup names from the ID.

I believe Dan M and others have experimented with tools for this: but found issues with the incoming data quality that made this tricky.

To allow a utility that does (2) here, then definitely a strong recommendation to include the name is useful.

The alternative to this is to encourage publication of a separate codelist of organisations named in files, keeping IATI files terse, but providing the input that would be needed for a utility of type (2).