Result with dimensions - example XML is unclear in terms of multiple values (and possibly the wider documentation)

[stevieflow]

Describe the bug
I understand that the documentation and example on using dimensions in results is wrong / not illustrative of how this should work

(NOTE - I think I actually wrote the original example XML - so this bug report needs some checking!)

To Reproduce

(note - the CoVE / d-preview links will expire after around seven days)

The example XML is here: https://raw.githubusercontent.com/IATI/IATI-Extra-Documentation/version-2.03/en/activity-standard/activity-standard-example-annotated.xml

This seems to validate against the schema, so all good: https://iati.cove.opendataservices.coop/data/b573d066-438c-4b76-8fbf-22c73ed282cd

A useful way to then see this is through d-preview: http://b319646f92668e5acb64c34c565da244.d-preview.codeforiati.org/ctrack.html#view=act&aid=AA-AAA-123456789-ABC123

Here's the result:

So - whilst this is valid XML, when you view this it makes sense - what we miss is to see how things would look when we want to provide the values across two aspects of the same dimensions (eg make & female)

To do this, it seems you have to repeat the baseline / target / actual blocks for each dimension value. I've mocked up an example in this gist: https://gist.github.com/stevieflow/c2af5c13d0729c228b4990e523e14002 (note - I get an ordering error on this - but please use it for now!)

Here's how the d-preview now looks:

http://85ba5033b372fe39f5e3caae3bf7539b.d-preview.codeforiati.org/ctrack.html#view=act&aid=AA-AAA-123456789-ABC123

It'd be great if someone can check this logic in the XML, as if true, we may then want to look at how that is supported by documentation

[stevieflow]

Note - this isn't a suggestion that the existing documentation is wrong or has a bug. It's more to do with the fact that it doesn't fully include the concept of having two values for a dimension. in the example --> and that seeing that example might be very useful

[akmiller01]

Is this the kind of change you had in mind @stevieflow ? #660

I realize the usage of two locations is a little ambiguous. I find myself asking "Is it the baseline for two locations combined? Or the baseline for either location separately?" But since location can occur any number of times, I kept the new examples consistent with the previous ones.

[stevieflow]

Thanks @akmiller01

Yes, it can all get very nested !

Is this the kind of change you had in mind @stevieflow ? #660

I think so. I wonder (out loud) if the example would need to illustrate more than one aspect of any dimension, so that it is clear(er) to people?

Agree on how the addition of location can start to confuse too! That's inherent in the aim of the example XML to show everything I think, whereas some useful guidance might walk a user through the increasing complexity of the result block, with examples (but that's not for this issue!)

[akmiller01]

I wonder (out loud) if the example would need to illustrate more than one aspect of any dimension, so that it is clear(er) to people?

This is what I was attempting to do with the PR. Let me know if I've misinterpreted, or maybe the changelog in the PR didn't demonstrate the full example. I kept the adult female example as it was, but added an adult male example baseline below it:

IATI-Extra-Documentation/en/activity-standard/activity-standard-example-annotated.xml

Lines 371 to 396 in bffc584

	<baseline year="2012" iso-date="2012-01-01" value="10">
	<location ref="AF-KAN" />
	<location ref="KH-PNH" />
	<dimension name="sex" value="female" />
	<dimension name="age" value="adult" />
	<document-link format="application/vnd.oasis.opendocument.text" url="http:www.example.org/docs/result_baseline_en.odt">
	<title>
	<narrative>Results Baseline Report 2013</narrative>
	</title>
	<description>
	<narrative>Report of results baseline</narrative>
	</description>
	<category code="A01" />
	<language code="en" />
	<document-date iso-date="2014-02-05" />
	</document-link>
	<comment>
	<narrative>Baseline comment text</narrative>
	</comment>
	</baseline>
	<baseline year="2012" iso-date="2012-01-01" value="5">
	<location ref="AF-KAN" />
	<location ref="KH-PNH" />
	<dimension name="sex" value="male" />
	<dimension name="age" value="adult" />
	</baseline>

[stevieflow]

OK - got it , thanks @akmiller01. Yep - that make sense.

That does shine a new light on the usefulness of multiple locations, as you say - but think ^ addresses the original post