It's common for open data standards to use RFC 2119 key words to reduce ambiguity around expected behaviour; RFC 8174 further clarifies that the specific meanings of those key words only applies when they are written in ALL CAPS; otherwise they have their plain English meaning.
IATI doesn't seem to use RFC 2119 but nonetheless there are instances where terms are capitalised in the documentation: for example
|
<xsd:attribute name="default-currency" type="xsd:string" use="optional"> |
|
<xsd:annotation> |
|
<xsd:documentation xml:lang="en"> |
|
Default ISO 4217 alphabetic currency code for all |
|
financial values in this activity report. If this is not |
|
declared then the currency attribute MUST be specified for |
|
all monetary values. |
|
</xsd:documentation> |
|
</xsd:annotation> |
|
</xsd:attribute> |
This is inconsistent, however: not all instances of "must" are capitalised, and terms that are not RFC2119 key words are capitalised.
As someone who is very familiar with reading schemas this feels odd to read, and makes me question what is being communicated by the capitalisation (or not) of particular words. Is it simply emphasis, given a lack of formatting options?
I guess I'm not really looking for answers here, but I would be keen to see consistency and clarity in this; I (and I suspect many others) expect to see RFC2119 usage when we see a capital MUST in schema, and so it's surprising and counterintuitive when it's not in use.
It's common for open data standards to use RFC 2119 key words to reduce ambiguity around expected behaviour; RFC 8174 further clarifies that the specific meanings of those key words only applies when they are written in ALL CAPS; otherwise they have their plain English meaning.
IATI doesn't seem to use RFC 2119 but nonetheless there are instances where terms are capitalised in the documentation: for example
IATI-Schemas/iati-activities-schema.xsd
Lines 175 to 184 in 771f2c2
This is inconsistent, however: not all instances of "must" are capitalised, and terms that are not RFC2119 key words are capitalised.
As someone who is very familiar with reading schemas this feels odd to read, and makes me question what is being communicated by the capitalisation (or not) of particular words. Is it simply emphasis, given a lack of formatting options?
I guess I'm not really looking for answers here, but I would be keen to see consistency and clarity in this; I (and I suspect many others) expect to see RFC2119 usage when we see a capital MUST in schema, and so it's surprising and counterintuitive when it's not in use.