This file contains notes pertaining to the specification which may make it into documentation in the future.
The specification relies on defining paths of a target JSON dataset via JSON Pointer Syntax (RFC 6901). This is well supported in various programming languages, as well as in JSON Schema validation but it, ironically, presents a problem for the main use-case of this specification: machine-checking of use-cases in target datasets.
Since some use-cases may require properties which are nested under one or more levels of arrays, it becomes a challenge to mechanically evaluate to what extent the dataset supports the use-case.
For example in a comprehensive OCDS dataset, we may want to track the number of unique awarded suppliers (U004). We need:
- The identifier for each Award
- The identifier for each Supplier
- The name for each supplier
- The status of each Award
The problem is that in an OCDS release, awards is an array, as is awards.suppliers. There is no way in JSON pointer syntax to refer to the awards.status or awards.suppliers.id across an array, we have to declare the exact index e.g. /awards/0/status.
While this is supported in JSON Path Syntax, JSON Path does not (yet) have a formal specification while JSON Pointer does. Further, JSON Schema provides functionality to support validation of strings as JSON Path.
Therefore, all arrays should be denoted using the 0 index, and tools should spot this and expand the array to contain the full list of JSON Pointers for the data set. This should be repeated for multiple arrays.
Using the above example, we would specify the paths required for U004 as:
/awards/0/id/awards/0/suppliers/0/id,/awards/0/suppliers/0/name,/awards/0/status