Confusing guidance on path notation
Opened this issue · 3 comments
According to the guidance on text formatting:
- When referring to a field in JSON Schema, use dot notation, like ``tender.id``. (Slash notation is reserved for `JSON Pointer <https://tools.ietf.org/html/rfc6901>`__. For example, the JSON Pointer for ``tender.id`` is ``/definitions/Tender/properties/id``.)
- When referring to a field in OCDS data, use a JSON Pointer, like ``/tender/id``.
According to the guidance on word choice:
When referring to a field, prefer the notation for the path in the data, like ``contracts.period``, rather than the notation for the path in the schema, like ``Contract.period``.
Shouldn't it be /contracts/period
if it's the notation for the path in the data?
There is indeed differing guidance here.
For data, I think slash notation is appropriate. However, we use dot notation quite a lot. To avoid hundreds of changes, I think we can change the guidance to prefer /
but allow .
– but to always prefer consistency with the proximate docs.
That sounds good to me.
The other challenge helpdesk analysts have with applying the current guidance is determining whether a reference relates to the publisher's data or to the schema; for example, if we tell a publisher to populate field X, is that a reference to the field publisher's data or a reference to the field in the schema?
It's a reference to the field in the data (you can only populate data, you can't populate schema – the schema is unchanging for a given version). I think we almost never need to talk about the field in the schema.