Thanks. 

This issue may get a little tricky to follow. I suggest that with the well formed pull request in place, GitHub is the easiest place to discuss the work in progress, so follow the detail there. Once we have a resolution we will paste the outcome here.

Adding New Organisation Registration Agencies

Changing existing Organisation Registration Agency codes has serious implications, as these form part of an organisation identifier which in turn become part of an iati-identifier for activities. A core requirement underpinning the standard is that activity identifiers do not change. The overhead for publishers and data users of a change of an Organisation Registration Agency code is quite significant.

This means that when we add a code to our list, it is important to get it right first time where possible.

At the same time it is important to remember that Organisation Registration Agency codes are simply codes - it is not necessary to derive meaning from them.

Even so, we have started to form some conventions about how they are crafted:

Organisation Registration Agency codes:

• begin with a two letter country code followed by,
• a dash followed by an acronym based on the name of the agency (in the native language - but using Latin script)
• if the code is extended beyond this, each subsequent section is delimited by an underscore

Beyond the code, we also record a name, description, URL, and a flag to indicate whether or not the Registration Agency has a publicly searchable database

Given this information as a whole, it is expected that data users should be able to go and find further information about an Organisation reported in IATI data.

IATI treats it's Organisation Registration Agency codelist as a Non-Embedded codelist, which means changes may be made to it quickly, outside of decimal and integer upgrade processes that take much longer. In particular, this allows us to add Organisation Registration Agencies quickly so that people can get on with their work. It also allows us to make minor adjustments and bug fixes in a timely manner.

However, other types of change should not be considered lightly.

This includes:

• Changing a Registration Agency code (because of significant knock on effects)
• Removing/Deleting a Registration Agency (data users can no longer look up information)
• Cases where a Registration Agency changes behaviour (such that an existing look up would start to fail)

We currently do not have a system to deal with deletions or a way to maintain lists of historic codes/codes that may have changed. (Although we have started work on what this would look like)

The problem IATI staff face
When new Organisation Registration Agencies are suggested we want to try to get the entry right first time.
This means scrutinising each suggestion, trying to make sense of the suggested Organisation Registration Agency in the context of the country and language in which it operates, trying to check that identifiers for that agency are unique, assessing whether or not that agency is likely to persist. It is not necessarily a quick, easy process.

Until now, requests to add single Organisation Registration Agencies have been received on a few occasions and have been easy to handle.

With a recent request to add 90 agencies at once, this has caused the team significant problems. First there is the sheer number of Registration Agencies to assess before we can add them to add to our list. Secondly, staff have already been committed to big projects, that have left little time for new work such as this. Third, our current system of considering and responding to requests is not sufficient to deal with such resource intensive requests.

Following a meeting today to deal specifically with with the current pull request:
https://github.com/IATI/IATI-Codelists-NonEmbedded/pull/43
we propose to:

First, tidy up the data by:
1) Remove all descriptions of the type:
Opencorporates jurisdiction code: ae_az
as these do not provide any useful data

2) Rewrite suggested codes to match the format
XX-XXX_XXX_XX
e.g.
FI_FBIS (Finnish Business Information System) should be
FI-FBIS
AE-DU_DIFC (Dubai International Financial Centre) is ok as it is.

3) Acronyms should not include small words (the, of, de, et). So:
BS_RGSDOTB Registrar General's Department of the Bahamas would become
BS-RGDB

4) The entry here:
https://github.com/IATI/IATI-Codelists-NonEmbedded/pull/43/files#diff-89d167448aa0a89b5baf22b18879111fR1133
should be removed as it contains incomplete data

5) We will also agree to remove the US-DOS entry. We believe we can do this as a check of the data shows that it is not in use. We need to ensure that we are still happy that it is not in use anywhere.

Once the data is in better shape we will only add each entry as and when it is requested to be used by data publishers. This is a practical step in order to allow the technical team time to assess each addition.

Therefore, publishers looking for a Registration Agency code should:

First check the current list at:
http://iatistandard.org/201/codelists/OrganisationRegistrationAgency/

If they do not find what they need there, then they should check our list of proposed additions
https://docs.google.com/spreadsheets/d/1T_c0GmDEBZXO0-Uh7MQhEJmEh6JqMXXHZvbZTbt1JIM/edit#gid=1273853054

If the Registration Agency they require is on that list, they should agree with the IATI Team any amendments needed, and the team will add the entry to our list for them to use.

If they have still not found a suitable Registration Agency to use, then they may propose a new addition to the list.

Investigations into finding a standardised method for identifying corporate bodies have now been picked up by the Joined Up Data Alliance. It is therefore not intended to progress with any of these proposed changes for now.

You can follow the progress of this by the Joined Up Data Alliance at https://groups.google.com/forum/#!forum/joined-up-data-alliance