Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Why are some words capitalised in field documentation when IATI (maybe?) doesn't use RFC2119? #478

Open
robredpath opened this issue Sep 8, 2023 · 1 comment

Comments

@robredpath
Copy link

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.

@andylolz
Copy link
Contributor

andylolz commented Sep 8, 2023

Related: IATI/IATI-Extra-Documentation#565

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants