diff --git a/docs/schema/merging.md b/docs/schema/merging.md index dbab1e407..0a87c6935 100644 --- a/docs/schema/merging.md +++ b/docs/schema/merging.md @@ -2,8 +2,8 @@ An OCDS [record](../schema/records_reference) aggregates all the releases available for a contracting (or planning) process at a given time, and can include: -* a compiled release, which expresses the current state of the contracting (or planning) process, by showing only the most recent field values -* a versioned release, which expresses all historical states of the contracting (or planning) process, by showing all the field values over time +* a compiled release, which expresses the current state of the contracting (or planning) process, by showing only the most recent field values. +* a versioned release, which expresses all historical states of the contracting (or planning) process, by showing all the field values over time. **Merging** is the process of combining individual releases with the same OCDS version into a compiled or versioned release, described in more detail below. At a high level: @@ -18,7 +18,7 @@ Guidance: [Updates and deletions](../guidance/build/merging) ### Discarded fields -In the release schema, `"omitWhenMerged": true` is declared on fields that must be discarded during merging. These are presently: `id`, `date` and `tag`. +In the release schema, `"omitWhenMerged": true` is declared on fields that must be discarded during merging. These are presently: `id`, `date` `publisher` and `tag`. * For a compiled release: * Both the fields and their values are discarded, because they are metadata about the individual releases; the compiled release replaces these with its own metadata. @@ -28,9 +28,12 @@ In the release schema, `"omitWhenMerged": true` is declared on fields that must If `omitWhenMerged` is set to `false`, ignore it. ```{note} -The compiled release presently uses the same schema as the release schema, which means that the `id`, `date` and `tag` fields are required in a compiled release. We invite discussion on whether to change these requirements in a separate compiled release schema in issue [#330](https://github.com/open-contracting/standard/issues/330). +The compiled release uses the same schema as the release schema, which means that the `id`, `date` and `tag` fields are required in a compiled release. -In the meantime, an intermediate solution is to set `tag` to `["compiled"]`, `date` to the maximum `date` among the individual releases used to create the compiled release, and `id` to `{ocid}-{date}`, like in the [reference implementation](#reference-implementation) of the merge routine. +These fields must be set with values that reflect the compiled release, like in the [reference implementation](#reference-implementation) of the merge routine: + * `id` should be set to `{ocid}-{date}` + * `date` should be set to the maximum `date` among the individual releases used to create the compiled release. + * `tag` should accumulate all `tag` values from the individual releases together with the tag "compiled". ``` ### Versioned values @@ -87,6 +90,8 @@ To create a compiled or versioned release, you must: 1. For a compiled release: 1. Set `date` to the maximum `date` among the releases. 1. Set `id` to `{ocid}-{date}`. + 1. Set `tag` to include all tag values from the individual releases together with "compiled". + 1. If using set `publisher` to the publisher of the compiled release. 1. Merge each release (**input**), in order, into the JSON object (**output**), as follows: #### Object values diff --git a/schema/dereferenced-release-schema.json b/schema/dereferenced-release-schema.json index f71c5592f..dd48912e4 100644 --- a/schema/dereferenced-release-schema.json +++ b/schema/dereferenced-release-schema.json @@ -27,7 +27,7 @@ }, "publisher": { "title": "Publisher", - "description": "The original publisher of this release.", + "description": "The original publisher of the release. For a compiled release this may differ from the publisher(s) of the individual releases about the contracting process.", "type": "object", "properties": { "scheme": { @@ -69,7 +69,7 @@ }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields.", + "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields. For a compiled release all the tags used in the individual releases for the contracting process should be included together with the 'compiled' tag.", "type": "array", "items": { "type": "string" diff --git a/schema/release-schema.json b/schema/release-schema.json index 46f3ea6d8..cd6a59cc9 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -27,13 +27,13 @@ }, "publisher": { "title": "Publisher", - "description": "The original publisher of this release.", + "description": "The original publisher of the release. For a compiled release this may differ from the publisher(s) of the individual releases about the contracting process.", "omitWhenMerged": true, "$ref": "#/definitions/Identifier" }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields.", + "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields. For a compiled release all the tags used in the individual releases for the contracting process should be included together with the 'compiled' tag.", "type": "array", "items": { "type": "string"