Confusing guidance on path notation

[duncandewhurst]

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?

[jpmckinney]

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.

[duncandewhurst]

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?

[jpmckinney]

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.

[duncandewhurst]

I'll prepare a PR to update the guidance.