This proposal has been discussed amongst the IATI Technical Team following the end of the initial suggestion phase of the v2.02 upgrade.

The IATI Technical Team is happy progress this proposal however we encourage further discussion on any alternative methods to deal with withdrawn codes in codelists.

Here's a suggestion for an alternative approach: add the status of a codelist item as an attribute of the <codelist-item> element.  This is how it could look in practice:

<codelist-items>
    <codelist-item status="active">
        <code>ZMK</code>
            <name>
                <narrative>Zambian Kwacha</narrative>
            </name>
    </codelist-item>
    <codelist-item status="withdrawn">
        <code>AUR</code>
        <name>
            <narrative>(Ancient Roman) Aureus</narrative>
        </name>
    </codelist-item>
</codelist-items>

To me, this feels more in-keeping with the standard, rather than adding substrings to codelist names.  

Would be interested to hear what others think...

I would support the idea of an attribute on codelist-item. It's similar to what I was working on in https://github.com/IATI/IATI-Codelists-NonEmbedded/pull/51, specifically https://github.com/IATI/IATI-Codelists/pull/78/files

Thanks for the extra context Ben.

As an addition to my suggestion, I would like to also propose adding an optional xs:date attribute to log the date that a codelist item was withdrawn.  For example:

<codelist-items>
    <codelist-item status="active">
        <code>ZMK</code>
            <name>
                <narrative>Zambian Kwacha</narrative>
            </name>
    </codelist-item>
    <codelist-item status="withdrawn" withdrawn-date="1900-01-01">
        <code>AUR</code>
        <name>
            <narrative>(Ancient Roman) Aureus</narrative>
        </name>
    </codelist-item>
</codelist-items>

What is the use case?

• If it is to inform end users that the code no longer is valid, a text addition might suffice.
• If it is to let software only present currently active codes, an attribute may be better.

If I want to add a historical activity with a sector code as it was valid then, that should be possible (although maybe not supported by the software).

If we want more complete information about when a code was withdrawn, or what an earlier version was, we'd have to really have versioned code lists. Which isn't such a problem: be able to request the code list "as was" in addition to "as is" is easy with git, and maybe useful for a codelist API.

As with currency values: add an attribute to the sector element to indicate the date to be used. Or maybe add a version number to each version, and let that be specified in an attribute.

Please see below for the technical implementation that is suggested in the Version 2.02 - Formal Proposal:

Codelist management policy

• Modification to the codelist.xsd to add three attributes status, activation-date and withdrawal-date.

• Example

• Current usage

   <codelist-item>

      <code>ZMK</code>

      <name>

          <narrative xml:lang="en">Zambian Kwacha</narrative>

      </name>

   </codelist-item>

• Proposed usage

   <codelist-item status="active" activation-date="2000-01-01" withdrawal-date="2017-01-01">

       <code>ZMK</code>

           <name>

              <narrative xml:lang="en">Zambian Kwacha</narrative>

          </name>

   </codelist-item>

This proposal has been added as a GitHub issue, for inclusion in the version 2.02 development branch of the appropriate code repository: https://github.com/IATI/IATI-Codelists/issues/89

This proposal has now been incorporated into a version 2.02 code repositories (see the above GitHub issue link for technical details). The updated codelist schema is available to view.  Additionally, an updated codelist management page on a development version of the 2.02 reference and documentation site is also available to view.

We welcome scrutiny on the implementation of this proposal and encourage the community to feedback and suggest solutions for any errors, omissions and problems. This should be done before Monday 7 December, when the process will commence to release version 2.02 as a live version of the IATI Standard. More information on the inspection phase is available here.