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
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.
andylolz
commented
1 year ago
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
https://github.com/IATI/IATI-Schemas/blob/771f2c2aa17c653bf2a78c286ed84cd2770eeeaf/iati-activities-schema.xsd#L175-L184
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.