Should element page titles be the xml element?

[Bjwebb]

Or should they have nice english titles like http://iatistandard.org/activities-standard/iati-activity/ ?

[caprenter]

Personally, I'd be happy to stick with the element name as it is in the schema. But as we are often reminded the standard is not the schema... so I'm going to sit on the fence on this one.

[Bjwebb]

A similar question applies for codelists - currently on dev.iatistandard.org they reflect exactly the name of the XML files, whereas on iatistandard.org they are 'nicer' with spaces etc.

[rolfkleef]

Having nice English titles might help in creating consistency in how fields are presented to end-users in applications, and provide a way to have "official translations" into other languages? (Does create the challenge of how/where to store that info...)

[Bjwebb]

Good point @rolfkleef . For codelists the appropriate place is in the codelist metadata - I've just added this for all codelists on iatistandard.org.

For the XML elements, I'm not sure where we should store it. As far as I can tell, the choice is between storing it in appinfo in the schema, or in a separate mapping file like the codelist mapping file. Although only one of these can be the single source, we can of course have a script that generates one from the other, as we do for the different codelist formats.

[rolfkleef]

One could argue that a human-readable title should be added to documentation - but it'll need some adaptation of the scripts to generate the documentation (pick out a title element?) Something like:

<xsd:element name="iati-activities">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        <title>IATI Activities</title>
        Top-level list of one or more IATI activity records.
      </xsd:documentation>
...

Benefit is that multi-lingual versions are easy to do.

Alternatively, appinfo easily allows for structured, machine-processed content? (You might even add the mapping to codelists in there? I'm not sure if there is a reasonable XML standard for such things already that might be a good namespace to add? I like the DC example at http://docstore.mik.ua/orelly/xml/schema/ch15_01.htm#ch15-77057)

But in appinfo you'd have to introduce an xml:lang attribute or something again?

[rolfkleef]

(the <metadata>...</metadata> block as used in codelists could easily live in appinfo, though, to make it more orthogonal?)

[Bjwebb]

I think having the human-readable title in documentation would be useful to some people, but I think it makes it harder to use programatically, so I would argue against it as the "Single Source". However, I have been looking into generating an annotated schema derived from other parts of the SSOT - https://github.com/IATI/IATI-Schemas/pull/57 - this could easily contain titles in descriptions.

[Bjwebb]

BTW, there's a similar discussion about where machine consumable information should be stored (in this case the mapping between codelists and elements) on the support forum - http://support.iatistandard.org/entries/27805388-Mapping-between-codelists-and-schemas

[Bjwebb]

For elements, the current plan is to use the element names, as it's simpler, and often less confusing. https://github.com/IATI/IATI-Websites/issues/78