Required annotation fields not clear to users

[kd-ods]

The schema sets out that motivation and statementPointerTarget are required within annotation objects. And if the motivation is 'linking' then url is also required.

However, the two fields that are always required are not picked up by the tables in the docs. I'm not sure how possible it is to fix up the tool that creates the tables from the schema to handle more complex requirements logic.

It's probably better to fix this by using the field descriptions to represent requirements.

[kd-ods]

This is linked to the validation issues in openownership/lib-cove-bods#64.

It doesn't look like an alternative but equivalent logic can be used in the schema. Therefore, let's address this issue with edits to the property descriptions in the schema: describing which properties are required. (And moving to adopt the kind of description style used in OCDS is a good idea.)

[rhiaro]

Unfortunately "describing which properties are required" and "moving to adopt the kind of description style used in OCDS" are incompatible, as the OCDS style guide says:

Descriptions should not:
Explicitly state whether a field is required or optional.

[kd-ods]

Ah! Well, I understand why that would be part of the style guide: it is preferable that requirement is set at a schema level. I think we may need to ignore that element of the style guide in this case, since we can't communicate the requiredness(!) via the schema.

Or have you got a more elegant solution, @rhiaro? I don't think there's any reworking of the schema logic that will help, but you might know better than I do.

[rhiaro]

Similar issue with Identifier, where one or both scheme or schemeName are required, and the schema uses anyOf to express that. (That info is already in the description in that case though.)

I've opened an issue on the tool that generates the tables to dig into this further at that end.

[rhiaro]

I've reshuffled the schema logic so the two always required fields are at the top level of Annotation rather than in an anyOf. That means they show up correctly in the docs (preview). I've adjusted the description for url since this is a conditional requirement and the tool that generates the tables can't handle that yet.

[odscjames]

This has now been merged to master and will go out in the next release of the standard, 0.2.1 or 0.3