Compliance

[RexJaeschke]

Formalizing the FDC3 Standard documentation

This issue has been raised as part of work, sponsored by FINOS, to improve and formalize the documentation of the FDC3 standard.

Issue description

“FDC3 Compliance” states, “… So, unless a particular item in a spec is marked with keywords such as OPTIONAL, MAY, SHOULD, or SHOULD NOT, it should be treated as REQUIRED. Since FDC3 itself is primarily concerned with establishing the baseline requirements for interoperation, this is consistent with the IETF Guidance:”

A search of all docs/md files shows that “MUST” appears only three times, and “SHALL” only once, which reinforces that the advice written above has been followed.

My first, second, and third reactions to this approach were negative. These keywords exist to mark specific text according to the keyword’s property, yet there are almost never used for that purpose. I would have expected to see all required criteria to be explicitly marked “SHALL” rather than that being the default. Without that, if a paragraph or section does not contain any of these keywords, the reader still has to scan it very carefully to see what requirements might be contained therein.

Proposals:

1. Rewrite this section, saying that we use the RFC-2119 required keywords SHALL/MUST instead of defaulting to them. That is, we make all requirements explicit. (This allows them to be found mechanically to help the implementer figure out exactly what they have to do to comply.)
2. Apply the above-mentioned change throughout the Parts.
3. Define the term compliant implementation in terms of which Parts are required and which, if any, are optional.
4. Introduce the notion of deprecation (which is used at least in “API Specification, Raising Intents”).