Final Technical Proposal for the 2.03 Upgrade

Standard Management 2.03 Decimal Upgrade Proposals
#1

The IATI technical team has worked up the final proposed content for the 2.03 Upgrade into a technical proposal. The document below contains the proposed 2.03 summary tables for the Organisation and Activity Standards:

The tabs are as follows:

  • Keylog: details the type of change made
  • 2.03 Activity Standard (Changes): a condensed summary of the changes
  • 2.03 Organisation Standard (Changes): a condensed summary of the changes
  • 2.03 Activity Standard (Full): the full summary table
  • 2.03 Organisation Standard (Full): the full summary table
  • Non-embedded codelists: list of codelists moving from Embedded to Non-Embedded
  • Codelists: details of the additions and modifications made

If you would like to comment on the final technical proposal, please do so via this thread. The deadline for making comments is Friday 3rd November 2017.

How to participate in the 2.03 Upgrade consultation?
Add budget-exempt attribute and codelist (included 2.03)
Results – improve consistency of results standard (included 2.03)
Add vocabularies to aid-type (included 2.03)
Results – represent more than quantitative data (included 2.03)
Guidance on U.r.i. Usage for publisher’s own vocabularies (included 2.03)
Traceability - definitions of disbursement and expenditure (included 2.03)
CRS Channels of Delivery (included 2.03)
Hierarchies - related-activity definition (included 2.03)
Document-link description (included 2.03)
IATI and SDGs - untangling threads
Language - recommend use of ISO 639-1 (included 2.03)
Boundary values for percentages (included 2.03)
Modify definition of secondary publisher (included 2.03)
Redefine selected codelists as “Non-embedded” (included 2.03)
TransactionType codes (included 2.03)
Results - vocabulary attribute option (included 2.03)
Results – allow disaggregations of results data (included 2.03)
Organisation type codes - additions (included 2.03)
Version 2.03 Available for Inspection and Testing
Version 2.03 Available for Inspection and Testing
Final Proposal of 2.03 Content
Add document-link to Results indicator (included 2.03)
#2
#3

The updated definition of the xml:lang attribute is the same for all instances of the attribute. As such, it removes any reference to the ability to define a default language at the <iati-activity> or <iati-organisation> level. This information should be maintained.

There are 3 narrative elements. It is reasonable that each may be different:

  • iati-activity (defined in activity)
  • iati-organisation (defined in org)
  • narrative (defined in common)

Comment added to relevant issue on Github.

#4

With the addition of iati-activities/iati-activity/participating-org/@crs-channel-code, there is no need for a Rule specifying:

Must contain a valid value from the CRS ChannelCode codelist.

This is because it is stated that the attribute will have a value from the CRS Channel Code Codelist, and this Codelist is specified to be complete.

#5

The updated definition for iati-activities/iati-activity/recipient-region/@vocaulary-uri states that:

The URI where this vocabulary is defined. If the vocabulary is 99 or 98 (reporting organisation), the URI where this internal vocabulary is defined. While this is an optional field it is STRONGLY RECOMMENDED that all publishers use it to ensure that the meaning of their codes are fully understood by data users.

This attribute refers to another attribute that uses the Region Vocabulary Codelist. This Codelist does not contain a 98 value.

There is also no proposed change in the Codelists sheet to add a 98 code.

This also impacts other @vocabulary-uri attributes.

  • iati-activities/iati-activity/recipient-region/@vocabulary-uri
  • iati-activities/iati-activity/sector/@vocabulary-uri
  • iati-activities/iati-activity/tag/@vocabulary-uri
  • iati-activities/iati-activity/humanitarian-scope/@vocabulary-uri
  • iati-activities/iati-activity/policy-marker/@vocabulary-uri
  • iati-activities/iati-activity/transaction/sector/@vocabulary-uri
  • iati-activities/iati-activity/transaction/recipient-region/@vocabulary-uri
  • iati-activities/iati-activity/result/reference/@vocabulary-uri

Changes made in Github:

#6

The spreadsheet of changes includes an entry for iati-activities/iati-activity/tag/narrative/text().

This is not an element or attribute. The definition should be under iati-activities/iati-activity/tag/narrative. This is an element, so does not have a type.

EDIT: This appears to be something magic about <narrative> elements being unlike anything else in the Standard, and so this can be passed over with no action.

#7

There are inconsistent references to the Aid Type Codelist with respect to the new vocabulary.

The definition for iati-activities/iati-activity/default-aid-type/@code refers to it as:

the OECD DAC vocabulary

The definition for iati-activities/iati-activity/default-aid-type/@vocabulary refers to it as:

the AidType codelist

These should be made consistent so that it is clear that they are referring to the same thing.

Definition’s changed to:
Code: A code from the specified vocabulary.
Vocabulary: A code for the vocabulary aid-type classifications. If omitted the AidType (OECD DAC) codelist is assumed. The code must be a valid value in the AidTypeVocabulary codelist.

See Github: https://github.com/IATI/IATI-Schemas/issues/346 and https://github.com/IATI/IATI-Schemas/issues/345

#8

The definition of iati-activities/iati-activity/transaction/receiver-org/@ref currently states that:

if omitted on incoming funds then the receiver organisation is assumed to be the reporting organisation

The proposed definition removes this information.

Additionally, the Previous Definition in the spreadsheet is incorrect for this attribute.

EDIT: It has been noted that this issue impacts a range of receiver-org/@ref and provider-org/@ref attributes, not just the one specified here.

Comment added to relevant Github issue.

#9

The @value attribute for various things within results is proposed to become optional so that it is clearer how to report qualitative data.

  • iati-activities/iati-activity/result/indicator/baseline/@value
  • iati-activities/iati-activity/result/indicator/period/target/@value
  • iati-activities/iati-activity/result/indicator/period/actual/@value

It is proposed that 3 Rules are added:

  1. The @value must be omitted for qualitative measures
  2. The @value must be included for non-qualitative measures
  3. The @value must be a valid number for all non-qualitative measures

With these Rules…

A note that: Numbers 1) and 2) are Non-Machine Readable, and so will not displayed on the relevant attribute pages (at least with the current architecture).

Additionally, because the attributes are currently so lax in what is allowed (permitting both quantitative and qualitative values, numeric and non-numeric), implementing these as Rules (must) is not backwards-compatible.

#2) can be a Rule at 2.03 because it maintains the status quo. 1) and 3), however, cannot because they would add additional restrictions. They must instead be Guidelines (should).

EDIT: It has been explained how my interpretation of the IndicatorMeasure Codelist is incorrect. I would therefore suggest it may be worth adding something along the lines of This can be used to detail [qualitative|quantitative] indicators. to the Description of Codes in this Codelist.

This corrected understanding changes the above points to:

  • #1) and #2) can be Rules
  • #3) can only be a Guideline because it adds additional restrictions (not present in 2.02) to quantitative indicator values

Changed rule 3 from a must to a should: “the @value should be a valid number for all non-qualitative measures”. See Github issue: https://github.com/IATI/IATI-Schemas/issues/353

#10

A couple of things with {x}Vocabulary Codelists…

ResultVocabulary

It is currently detailed that this Codelist will have 99 and 98 values in a similar way to SectorVocabulary.

The addition of a 98 value seems problematic since it allows partial use of multiple vocabularies, but only to a limited extent. A more versatile option would be to either:

  1. Make use of the @vocabulary-uri attribute to deem uniqueness (this was introduced as a concept at 2.02, after 98 became a thing with SectorVocabulary).
  2. Add a <narrative> sub-element to provide information (partially implemented with sectors, though how to deem uniqueness is slightly unclear).

Due to how other @[vocabulary|indicator]-uri attributes are implemented (ie. they lack child narrative elements), 1) appears the preferable option.

Whichever way, 98 codes should be on a path towards deprecation in favour of a more robust solution - more 98 codes shouldn’t be added.

TagVocabulary

This is to be used by an element (iati-activities/iati-activity/tag) with a @vocabulary-uri attribute. It is not proposed that a 99 code is added.

  • The TagVocabulary Codelist should include a 99 code.
1 Like
#11

With regards to the proposal to introduce iati-activities/iati-activity/result/baseline/@iso-date with occurrence rule 1..1.

Is it not the case that decimal upgrades can only add optional fields, so perhaps the occurrence rule should be 0..1?

Occurrence rule changed to 0…1. See Github: https://github.com/IATI/IATI-Schemas/issues/364

#12

It is proposed to change a number of Codelists from Embedded to Non-Embedded.

The following Codelists had their format changed from 1.05 to 2.01. As such, they cannot become Non-Embedded since there is no categorisation to allow particular Codes to exist at only particular integer versions of the Standard:

@petyakangalova (with assistance from others) has been working on a full solution to allow this change to occur, through the introduction of a new category of Codelist.

#13

It is proposed that 4 new Codelists are added:

  • BudgetNotProvided
  • AidTypeVocabulary
  • ResultVocabulary
  • TagVocabulary

These have names, though do not appear to have been provided additional details, in particular:

  • description
  • complete?

(other details may also be relevant, though the above are essential (some like the prose name and language are obvious, so don’t really require stating, though others may))

#14

I’m wondering what happened to: Adding links to related OCDS contracts (excluded 2.03). The title of that post suggests it was excluded (which I believe just means the proposal as it was originally stated was rejected), but the thread suggests it was included. However, I can’t see any mention of it in the final proposal.

#15

I wonder if budget-omitted might be a pithier name than budget-not-provided (and avoids the negation.)

#16

Like the OCDS contracts, the Results – recognising partner contributions (excluded 2.03) proposal was also included until the 25th October when the title changed to “(excluded 2.03)”, and the post was immediate closed to further discussion meaning no response could be made. Please could someone clarify why it was excluded and why there has not been opportunity for discussion after it was dropped from the upgrade process on the 25th October? The IATI @IATI-techteam also emailed me to check the results proposals on the 25th October and respond but because the posts are closed I cannot do so. Should I include my response here?

#17

OCDS link was omitted because @TimDavies, on second thoughts, felt some more work was required to get this right.

#18

Thinking things through, I think that result/indicator/@aggregation-status can only be 1 if result/indicator/@measure is 1 (Unit)

Percentages, scales and qualitative results can’t be aggregated.

@mikesmith: the “Results – recognising partner contributions (excluded 2.03)” proposal was probably omitted because I expressed my doubts.

#19

(this post is in reference to Results – recognising partner contributions (excluded 2.03) )

Hi @pelleaardema thanks for the response, please could you provide some reasoning behind your doubts - for example many of the 2.03 proposals “add complexity” why in particular should this one not be accepted? Also e.g. @Herman queried in your referenced post Our shared understanding of what IATI is, and is not, if the "propose to defer the adoption of the IATI 2.03 upgrade” - but the community has collectively decided that there will be a 2.03 upgrade. It would be good to understand what your reasoning is.

To help provide the UK NGO and Nethope consultation perspective, this proposal is about improving the consistency of the IATI standard and simplifying IATI reporting. For the former, it’s remiss that transactions are for specific organisations but results cannot be. For the latter, I think we can agree that IATI should not cause a fundamental redesign of our work, just for IATI reporting ( see Results – represent more than quantitative data (included 2.03) and other comments). For example one currently has to artificially split an activity because you cannot assign different parts of the results framework to different organisations. This requires duplicating data (eg, title, description) and designing projects to a level of detail beyond that is required for internal management and donor reporting (eg you have to split budgets, organisation spending etc. by individual results, partners etc.). Some overarching results (ag indirect advocacy ) can’t be split so must also be treated separately. This all adds up to very complicated reporting which is even highlighted in the document that is referenced (https://www.drostan.org/wp-content/uploads/2017/05/Partos-IATI-Results-2017-report-of-meetings.pdf ) in the post that @pelleaardema you refer to (Our shared understanding of what IATI is, and is not, ) "there are no ways to indicate the boundary of a partnership, or to better mark activities as joint activities. This can lead to overlaps and duplications.”. They also talk about this problem of having to change the fundamental way projects are managed under the section "How do you coordinate working with the same indicators in a partnership?” which I know has caused a number of organisations a headache. The additional coordination effort to produce reports (with various additional discussions, sign-offs between organisations etc.) just to report in this way is substantial. A simplified example (in practice there are often many more indicators) , 5 partners, 5 indicators (2 of which overarching):
ImplementingPartners
requires artificially splitting 1 activity into 5 (red ellipses marking the activity boundary) just so that they can be reported in IATI. As well as causing duplication and confusion, there is substantial effort involved in splitting finances per each activity (doesn’t sound like much but this is in effect adding an additional dimension to all financial reporting in an organisation) which is beyond what most NGO systems can do at the moment, and adds a huge overhead to our programmes staff, just for IATI. This proposal alleviates these problems by not forcing artificial splits.

#20

Hi @mikesmith,

I understand what you’re trying to do, but I’m in doubt about the proposed solution.

In general adding elements to reduce complexity would not be my preferred solution. IATI is already perceived as a complex standard, and from my experiences with many different publishers I am doubtful if this specific proposal makes their lives easier - let alone for users of the data, for whom it will introduce yet another dimension to take into account when dealing with results.

In line with our joint statement I’m in favour of making changes to the standard supported by very clear ‘use cases’ and inline with a common understanding of what IATI is and is not. I feel we are not there yet, so let’s please take some more time to share and learn from each other’s experiences.