Schema style guide: Add guidance on restating normative rules enforced by the schema in field descriptions

[neelima-j]

Should descriptions that restate rules enforced by the schema use normative keywords?
Example:
Period

"Key events during a project or contracting process may have a known start date, end date, duration, or maximum extent (the latest date the period can extend to). In some cases, not all of these fields will have known or relevant values."

• This description restates the properties of the Period object defined in the schema
• Is it advisable to use the normative keyword MAY in this description or better to use a non-normative synonym?

The normative keyword is consistent with the schema and stating the fields in the description might be useful for less technical audiences, but then we have the properties of the period object stated in two places, once in the schema and once in the description field, so there is a risk of the description and the schema going out of sync and becoming contradictory.

I think it’s probably best to avoid restating information contained in the schema if possible, but where restatements do occur, should we use normative keywords or non-normative synonyms?

[jpmckinney]

It is inadvisable for the description of a definition (like that of Period) to list the fields (like start date).

This definition ought to be rewritten to describe the semantics of period, not to list and repeat the rules for individual fields.

Since OCDS is fairly old and there was not much of a quality review for the initial version, you'll find this and other issues.

Please open an issue on the standard, and feel free to add some guidance to the handbook as above.