Add describedby field for the extended release schema

[irwink]

Edit: This issue effectively starts at #426 (comment)

$schema is meant for the "metaschema", not for the "schema". The linked comment proposes using a describedby field to link to the schema.

---

I suggest that a "$schema" field be added to all contracting data files. The "$schema" field's value would be either a single URI of the schema that the data claims to conform to, or a list of schema (e.g. if the data conforms the OCDS and and extension schema). This would be very useful from both a quality assurance perspective as well as parsing and consuming the contracting data. Programs would know which schema the data conforms to and how to properly parse them. This is especially useful if the data repository contains a mix of data files that conform to the OCDS, extension schema or some other schema.

An example would be (using the Paraguay sample data)

{
"uri": "https://www.contrataciones.gov.py/datos/record-package/273637.json",
"$schema": "http://standard.open-contracting.org/schema/1__0__1/release-schema.json",
"publisher": {
"uri": "https://contrataciones.gov.py/datos",
"legalName": "Dirección Nacional de Contrataciones Públicas, Paraguay",
"name": "DNCP - Paraguay"
},

[timgdavies]

In OCDS 1.1 (see #301) we were planning to handle this with two properties:

• Version
  and
• Extensions

Although I note that JSON Schema notes that the $schema keyword can be used for both version and schema declaration.

The reason I believe for diverging from JSON Schema here was:

• Many validators dereference the remote $schema by default, which can be frustrating for local development and validation against local schema;

• $schema only allows a single value, not an array of values

But, other views on this welcome.

Assigning to @kindly and @Bjwebb to have a quick glance at whether we should alter the OCDS 1.1 approach before we're committed to it too strongly.

[irwink]

The suggestions in issue #301 would handle the extensions problem, however, an application would have to "know" that a JSON file claims to conform to the Open Contracting standard and would also have to know where the schema is located (to validate against it). Furthermore, if the JSON file repository contains a mixture of Open Contracting files and other non Open Contracting files, there is no predictable way to distinguish them. The use of a "$schema" field (or some other widely adopted equivalent) would provide an explicit schema reference (similar to a DOCTYPE declaration in a web page).

[mireille-raad]

in the same spirit, it would be useful to have a similar field to $schema but for extensions.
As implementations get more complex, and as multiple extensions are used, it would be useful to have a reference to all that somewhere.
Maybe the $extension would be a closed codelist of the official OCDS extensions.

[jpmckinney]

Regarding extensions, couldn't $schema be a URL of a release schema that has been patched with the relevant extensions? The value of $schema in this case would not be useful for identifying the version of OCDS, but the purpose of $schema in JSON Schema is for validation - not for version identification.