Specifying versions and extensions in package meta-data

[Bjwebb]

Update: See full proposal below

---

This maybe shouldn't be a problem for 1.x, as changes should be backwards compatible, but at some point it's likely that data users will want to know what version of the standard a file has been published to.

This could be a version key, or using the $schema key with the URI of the schema as the value.

[timgdavies]

Agreed this would be useful. What are the pros and cons or using version or $schema.

I believe @kindly had noted some issues with how validators use the $schema property.

[timgdavies]

Extension and versions in release package

This issue is under consideration for the 1.1 milestone.

It builds on discussion in #301 and #326

The issue

OCDS files do not currently specify which version of OCDS schema they are using, or whether any extensions are in use.

The proposal

Release and record package meta-data should be updated to include:

• A version property which MUST contain a string reporting the version of OCDS in use;
• An extensions property which MAY contain an array of URIs to extension.json files of extensions used in the release.

When no version property is present, tools should validate against the latest schema in 1.0 series.

A validation tool may choose to look up the extension.json files referenced, to apply their json merge patches to the version of the basic schema used, and validate on this basis.

Discussion

We considered using the $schema keyword of JSON Schema to indicate the version of an OCDS file.

However, this can lead to some unexpected behaviours when validation tools prefer to dereference the value of $schema instead of using a locally supplied schema. This causes particular problems for users trying to perform validation when offline, or with connectivity problems.

Worked example

A release package will now contain:

{
"uri":"http://standard.open-contracting.org/examples/releases/ocds-213czf-000-00001-01-planning.json",
"version":"1.0.1",
"extensions":["https://raw.githubusercontent.com/Bjwebb/proposed_location_extension/master/extension.json"],
"publishedDate":"2009-03-15T14:45:00Z",
"publisher": {
        "scheme": "GB-COH",
        "uid": "09506232",
        "name": "Open Data Services Co-operative Limited",
        "uri": "http://standard.open-contracting.org/examples/"
    },
"license":"http://opendatacommons.org/licenses/pddl/1.0/",
"publicationPolicy":"https://github.com/open-contracting/sample-data/",
"releases":[{"...":"..."}]
}

Engagement

Please indicate support or opposition for this proposal using the +1 / -1 buttons or a comment. If opposing the proposal, please give clear justifications, and where possible, make an alternative proposals.

[kindly]

Do we make the version

major.minor.patch e.g 1.1.0 OR
major.minor eg 1.1

My feeling is we just go with major.minor as that should be sufficient to make the validator work.
There should be no changes in a patch release that break behaviour on certain data.

It will also be frustrating for the publisher to feel like they have to produce a new version of their data for every patch release.

A suggestion to have the version number as as string "pattern" (a regexp) so its harder to get the value wrong,

[timgdavies]

I would support regex approach, and allowing major.minor or major.minor.patch as

(a) even if we say not to do this, people might do it anyway;
(b) there may be some cases where declaring the patch is important;

[kindly]

First draft of schema can be found:

https://github.com/open-contracting/ocds_upgrade_1_1_patches/tree/master/301_version_extension