Add rules on how to identify and date compiled/versioned releases

[jpmckinney]

Split from #455. Copying relevant contributions:

From @mpostelnicu

[compiled releases] is where we need a better handling of IDs. Even then, maybe the ID of a compiled release could be constructed adding ocid to say the compiled release creation datetime, or a random hash. i am not entirely sure that for the same contract, two compiled releases done at a different time and having different content, would have to have the same id or not...

From @jpmckinney

we should add more guidance about the identification of compiled releases.

For context, release-schema.json has "omitWhenMerged": true for id and date, which means that the compiled release will not retain these fields from the releases on which it is based.

The compiled release is essentially the "present state of the contracting process". However, as you note, this "present state" can be published at multiple times, such that you can have many compiled releases for the same contracting process. Without id or date fields, it's more difficult to distinguish compiled releases, or to establish their sequence (since a record must always include at least one release, a user could look up the latest date among those releases, but this is a greater effort). We might therefore consider introducing a date field on the compiled release, whose semantics would be the time at which it was updated.

Since the compiled release reuses the release schema, id is required – though with #330 this requirement might be removed for the compiled release. In the meantime, I think it makes sense to set the id to the <ocid>-<date>, where the date is the last release's date, and to set the date similarly.

[jpmckinney]

The versioned release has no id or date field, so if we identify use cases for those fields, they will need to be added by the make_versioned_release_schema.py script.

[duncandewhurst]

We might therefore consider introducing a date field on the compiled release, whose semantics would be the time at which it was updated.

Does this conform to the description of the date field in the release schema?

The date on which the information contained in the release was first recorded in, or published by, any system.

Arguably, taking the information in the compiled release as a whole, the date the information was first published is the date the compiled release was updated.

In which case, should we clarify the schema description as follows?

The date on which the information contained in the release was first recorded in, or published by, any system. For a compiled release, the date of the last release used to create the compiled release.

[jpmckinney]

Yes. Another option:

... For a compiled release, the maximum date among the individual releases used to create the compiled release.

To avoid ambiguity with respect to "last" (e.g. if some historical release were backfilled at a later date).

[duncandewhurst]

For id:

... For a compiled release, the ocid and the maximum date among the individual releases used to create the compiled release, separated by a dash: {ocid}-{date}.

I used {} notation for consistency with the description for Organization/id.

Potentially, this creates a conformance issue: if the publisher already uses ocid-date for release IDs, then the compiled release and the last release would share the same id, so it would not be unique within the scope of the contracting process. @jpmckinney what do you think?

In addition to the schema changes, should we add a note to https://standard.open-contracting.org/staging/1.2-dev/en/schema/records_reference/#compiled-release explaining the rules?

[jpmckinney]

dash -> hyphen

I consider compiled releases to be grouped separately from individual releases, in terms of uniqueness. Their uniqueness rules are more like records.

Rather than the records reference page, this section of the merging page needs to be updated: https://standard.open-contracting.org/staging/1.2-dev/en/schema/merging/#merging-specification