From 3f1a71391196300da1db4e407b7576fb2aa4351a Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 5 Nov 2024 10:32:07 +0000 Subject: [PATCH 1/3] release-schema: update tag and publisher description for compiled releases --- docs/schema/merging.md | 15 ++++++++++----- schema/dereferenced-release-schema.json | 4 ++-- schema/release-schema.json | 4 ++-- 3 files changed, 14 insertions(+), 9 deletions(-) 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" From 222a9c66ac8e029bf3f4f73f9efc905f9f0678f2 Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:56:33 +0000 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Duncan Dewhurst --- docs/schema/merging.md | 8 ++++---- schema/release-schema.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/schema/merging.md b/docs/schema/merging.md index 0a87c6935..b2085a1a0 100644 --- a/docs/schema/merging.md +++ b/docs/schema/merging.md @@ -18,10 +18,10 @@ 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` `publisher` 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. + * 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, as described below. * For a versioned release: * The fields are discarded, but their values are moved, as described below, in order to indicate from which releases each other field value is taken. @@ -90,8 +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. Set `tag` to all the unique tags from all the releases, plus the 'compiled' tag. + 1. Optionally, 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/release-schema.json b/schema/release-schema.json index cd6a59cc9..7aa13eedf 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -33,7 +33,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. For a compiled release all the tags used in the individual releases for the contracting process should be included together with the 'compiled' tag.", + "description": "For a release, a tag labeling the release, using the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. For a compiled release, all unique tags from all releases for this contracting or planning process, plus the 'compiled' tag. 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.", "type": "array", "items": { "type": "string" From 9bbeaef0419bf834a179b40bcd7479e5fe383ace Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 7 Nov 2024 10:00:36 +0000 Subject: [PATCH 3/3] apply suggestions from code review --- docs/schema/merging.md | 9 --------- schema/dereferenced-release-schema.json | 4 ++-- schema/release-schema.json | 2 +- 3 files changed, 3 insertions(+), 12 deletions(-) diff --git a/docs/schema/merging.md b/docs/schema/merging.md index b2085a1a0..b2fac8a02 100644 --- a/docs/schema/merging.md +++ b/docs/schema/merging.md @@ -27,15 +27,6 @@ In the release schema, `"omitWhenMerged": true` is declared on fields that must If `omitWhenMerged` is set to `false`, ignore it. -```{note} -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. - -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 To convert a field's value in a release to a **versioned value**, you must: diff --git a/schema/dereferenced-release-schema.json b/schema/dereferenced-release-schema.json index dd48912e4..cc9de6d67 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 the release. For a compiled release this may differ from the publisher(s) of the individual releases about the contracting process.", + "description": "The original publisher of the release. The publisher of a compiled release for a contracting or planning process may differ from the publishers of its releases.", "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. For a compiled release all the tags used in the individual releases for the contracting process should be included together with the 'compiled' tag.", + "description": "For a release, a tag labeling the release, using the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. For a compiled release, all unique tags from all releases for this contracting or planning process, plus the 'compiled' tag. 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.", "type": "array", "items": { "type": "string" diff --git a/schema/release-schema.json b/schema/release-schema.json index 7aa13eedf..01e319d7c 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -27,7 +27,7 @@ }, "publisher": { "title": "Publisher", - "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.", + "description": "The original publisher of the release. The publisher of a compiled release for a contracting or planning process may differ from the publishers of its releases.", "omitWhenMerged": true, "$ref": "#/definitions/Identifier" },