Why does 2.02 include a code list that was not supported since 1.04?

Standard Management Non-Core Codelist Amendments
#1

@IATI-techteam take a look at this codelist in 2.02 http://iatistandard.org/202/codelists/OrganisationIdentifier/

As of 1.04 this list is no longer maintained.

As well as not maintained, this list is “wrong” (the country codes should be numeric) and out-of-synch with the source (OECD DAC aka XM-DAC).

Is there a compelling reason to publish this list within the documentation and resources for versions beyond 1.04? I still see people download this list and consume it, without reading the notice. Better for all to just remove it from the relevant repositories?

2 Likes
#2

I agree and will set the wheels in motion. It should have been removed at v2 so I think we can treat this as a bug-fix.

#3

Thanks @bill_anderson - have put something into https://github.com/IATI/IATI-Codelists-NonEmbedded/issues/176 - it’s a Non Embedded Codelist, so should make this easier…

#4

At present Non-Embedded Codelists refer to Codelists that are present at all versions of the Standard. There is no way for a Non-Embedded Codelist to exist at some versions (decimal or integer) but not others.

In terms of hiding it from display on iatistandard.org against versions of the Standard from 1.05+, we have deemed it to be a wontfix due to the way in which the site is generated, and upcoming work on the core website architecture.

In parallel to this, @petyakangalova (with assistance from others) has been working on a full solution to rectify the oversight that leads to the situation that has been brought up here (plus a range of other issues, some impacting the proposal to re-categorise some Embedded Codelists as Non-Embedded). I cannot recall the exact status of this, though last I saw it was a reasonably comprehensive and sensible proposal.

If the proposal in this thread is to completely wipe this Codelist from the face of history, that can be done (from a technical perspective). If the proposal is to remove it from versions 1.05+ (or 2.01+) only, that is not possible with the current methods of Codelist categorisation.

#5

All other IATI codelists define allowable values for an attribute or element. Not so for this list, which provides information about possible reference values.

Removing it from all versions does not break anything.

2 Likes
#6

That’s the difference between a complete and incomplete codelist, isn’t it? If so, I’ve no idea why the Organisation Identifier codelist is complete. I suspect that’s probably an error (this is far from a complete list of all organisation identifiers!) My mistake! I muddled up two codelists.

But anyway – Great! It sounds like removing the codelist is both technically possible, and won’t break anything. This is brilliant – Let’s do it!

#7

So - is the way forward to remove this list?

1 Like
#8

I’ve sent a PR for that:

#9

I think it is a bad idea to remove this list for all versions of the Standard.

Many organisations are still publishing using organisation identifiers on this list, and this was acceptable until 1.04, so removing this would not be consistent with the lack of consensus on deprecating older versions of the Standard. I would suggest that before removing this list (which is a useful reference list for data users) all existing publishers should be asked to use a new / other organisation identifier, at least for the reporting organisation.

Otherwise how can a user dereference FR-6 to know that this is the French MFA, GB-4 is UK DECC or CH-4 is Swiss SDC? The currently published codelist is the only place that you can get lookup values for these organisation identifiers.

Instead I would suggest just making the text at the top of the codelist much clearer – that it was previously used by publishers until 1.04 but shouldn’t be used any more, and that all existing publishers are urged to switch to the new methodology. In addition, if switching organisation identifiers is a priority, perhaps the IATI Technical Support team could raise this up the list of issues they proactively take up with publishers, as there are some major organisations still using the old methodology.

1 Like
#10

I can see your point @markbrough

I slightly disagree - but only via the existence this thread, which has been implemented by @andylolz --> checking publishers organisation files (against the reporting-org ref) to give us some indication of what reference to use (GB-GOV-1 or GB-1 or XM-DAC-12-1?)

This doesn’t answer all your queries, but a danger to the idea of a definitive / clean list is a list that is a) quite out-of-date with the references actually used by publishers, and b) also with the original source - OECD DAC.

A number of us in the community are suggesting that this methodology, list and (possibly) lookup should become a core piece of infrastructure adopted by IATI. In turn, I think harks back to some of the original requests from members (ie: a master list of organisation references) via community members such as @Reichner @OJ_ @YohannaLoucheur & @Herman, for example.

#11

Thanks for your reply @stevieflow and apologies for my delayed response.

I agree that a nice lookup tool (I guess building on @andylolz’ awesome work) would alleviate some of these concerns. But until then (or until at least major organisations are moved away from using these identifiers), I don’t like the idea of removing something that is at least somewhat useful. I guess generally I am also against removing data just because people might misinterpret it :wink:

#12

Following IATI’s standard management procedures we currently can’t remove a non-embedded codelist.

However, as this is an incomplete codelist we can remove individual codes whilst maintaining backwards compatibility (@hayfield) .

Therefore, I propose that we remove all of the codes from the codelist and update the description to explain what has happened. The description will also signpost people to info about how to form valid IATI Organisation Identifiers and to support@iatistandard.org. Where the teach team will be able to provide answers for people looking to find the values of the previous identifiers (which will remain available via github).

If there are no objections in the next 7 days we can start this process.

#13

Removing all of the codes from a codelist clearly has the same effect as removing the codelist itself. I don’t think it is an acceptable reading of the rules that govern the Standard.

I object to this for the reasons I previously outlined above. In the absence of a well supported organisation identifier lookup tool, given that these codes are already being used by a number of organisations, and given that 2.x encourages providing codes without narrative text, this removes the only available source for dereferencing a large number of organisation identifiers.

Please can you point to this in the Standard upgrade procedures? I cannot see where a codelist being tagged as incomplete means that it is not subject to the normal rules around decimal and integer upgrades. I also do not accept that removing codes (unless it is actually a bugfix) is backward-compatible.

#14

I’m a bit puzzled why we’re discussing this list and not (at the same time) this one: http://iatistandard.org/203/codelists/IATIOrganisationIdentifier/

This IATI list is even more incomplete. Furthermore, the rationale for its existence (“a bona fide organisation is not registered with any recognised or appropriate registration agency”) is clearly not respected, as almost all the organizations on this list are in fact registered with a recognised agency (e.g. OECD DAC, and presumably national registration agencies in the US, Netherlands, Mozambique etc). It also contains Org Identifiers that inconsistent with those in the Org Identifier codelists (e.g. ECHO, IADB)

This issue may be different enough to require a separate thread, but I wanted to flag it as what is decided here may apply to it as well.

#15

From a user’s point of view, that is correct, yep.

From a Standard Management point of view, however, they are slightly different - in the former, the statement that “there is a Codelist called ‘[thisThing]’ at version xyz of the Standard” remains true. In the latter, it becomes false (and so does not maintain backwards compatibility).

given that 2.x encourages providing codes without narrative text

v2.0x provides the means of including the names of reporting and participating orgs.

If there is any Guidance that discourages the use of these elements, could you point towards it?

this removes the only available source for dereferencing a large number of organisation identifiers

The historical source will remain, and updates to the documentation will signpost this for those who require it.

Please can you point to this in the Standard upgrade procedures?

Non-Embedded Codelist Management Process

I also do not accept that removing codes (unless it is actually a bugfix) is backward-compatible.

If a Codelist is complete, removing Codes is not backwards compatible (since it is not permitted to use a Code that is not on the Codelist - a Dataset that was previously valid would suddenly become invalid).

If a Codelist is incomplete, removing Codes maintains backwards-compatibility (it is permitted to use Codes that are not on the Codelist, so a Dataset that was valid before their removal remains valid after they are removed).

#16

From here:

codes withdrawn from the release of version 2.02 (December 2015) will feature status=“withdrawn” and withdrawal-date attributes.

Not sure you can just remove codes from codelists – I think you’d need to mark them as withdrawn, wouldn’t you?

I gather that one motivation for third party codelists is that other organisations sometimes remove codelist items that were previously in use (e.g. DAC). So IATI duplicates these codelists for posterity, and marks items that have been removed from source as “withdrawn”. This is helpful, because it provides a reference for historical codelist items that may have been used in the past, but should not be used going forward.

I think the same logic applies here.

#17

Thanks for your reply @hayfield

I don’t accept that removing all codes from this codelist is backwards-compatible, even given the presence of the incomplete flag, though I accept that that is your view. Perhaps you have a narrower definition of backwards-compatibility than I do (yes, I am primarily concerned about the user’s point of view). I don’t see anything in the Non-Embedded Codelist Management Processes document you linked to that states anything on the matter.

Your view of upgrade processes here does not appear to be compatible with the Revision of IATI Standard Upgrade Procedures that I understand to be the most current one.