From e0429fd5a0f53ea144804153cf74f19ab9298d50 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 28 Feb 2024 16:33:44 +1300 Subject: [PATCH 1/3] docs/guidance/map/amendments.md: Simplify tender example --- docs/examples/amendments/tender.json | 436 +++++---------------------- docs/guidance/map/amendments.md | 28 +- 2 files changed, 78 insertions(+), 386 deletions(-) diff --git a/docs/examples/amendments/tender.json b/docs/examples/amendments/tender.json index 59975919a..8ffc05e07 100644 --- a/docs/examples/amendments/tender.json +++ b/docs/examples/amendments/tender.json @@ -6,376 +6,136 @@ "releases": [ { "ocid": "ocds-213czf-000-00002", - "id": "ocds-213czf-000-00002-01-tender", - "date": "2016-01-01T09:30:00Z", + "id": "1", + "date": "2024-01-01T00:00:00Z", "tag": [ "tender" ], - "parties": [ - { - "name": "Open Data Services", - "identifier": { - "scheme": "GB-COH", - "id": "09506232", - "legalName": "Open Data Services Co-operative", - "uri": "https://opencorporates.com/companies/gb/09506232" - }, - "roles": [ - "buyer" - ], - "id": "GB-COH-09506232" - } - ], - "buyer": { - "id": "GB-COH-09506232", - "name": "Open Data Services" - }, "tender": { - "id": "ocds-213czf-000-00002-01-tender", - "title": "Data merging tool", - "description": "Data merge tool.", - "status": "active", + "id": "1", + "title": "Office supplies", "value": { - "amount": 1000, + "amount": 10000, "currency": "USD" - }, - "procurementMethod": "open", - "awardCriteria": "bestProposal", - "tenderPeriod": { - "startDate": "2016-01-31T09:00:00Z", - "endDate": "2016-02-15T18:00:00Z" - }, - "awardPeriod": { - "startDate": "2016-04-01T00:00:00Z", - "endDate": "2016-06-01T23:59:59Z" } } }, { "ocid": "ocds-213czf-000-00002", - "id": "ocds-213czf-000-00002-01-tender-update", - "date": "2016-01-31T09:30:00Z", + "id": "2", + "date": "2024-01-07T00:00:00Z", "tag": [ "tenderUpdate" ], - "parties": [ - { - "name": "Open Data Services", - "identifier": { - "scheme": "GB-COH", - "id": "09506232", - "legalName": "Open Data Services Co-operative", - "uri": "https://opencorporates.com/companies/gb/09506232" - }, - "roles": [ - "buyer" - ], - "id": "GB-COH-09506232" - } - ], - "buyer": { - "id": "GB-COH-09506232", - "name": "Open Data Services" - }, "tender": { - "id": "ocds-213czf-000-00002-01-tender", - "title": "Data merging tool", - "description": "Creation of a data merging tool. The tool should by written in Python. Proposals should be submitted by e-mail.", - "status": "active", + "id": "1", + "title": "Office supplies", "value": { - "amount": 1000, + "amount": 10000, "currency": "USD" }, - "procurementMethod": "open", - "awardCriteria": "bestProposal", - "tenderPeriod": { - "startDate": "2016-01-31T09:00:00Z", - "endDate": "2016-02-15T18:00:00Z" - }, - "awardPeriod": { - "startDate": "2016-04-01T00:00:00Z", - "endDate": "2016-06-01T23:59:59Z" - } + "mainProcurementCategory": "goods" } }, { "ocid": "ocds-213czf-000-00002", - "id": "ocds-213czf-000-00002-01-tender-amendment", - "date": "2016-02-05T10:30:00Z", + "id": "3", + "date": "2024-01-14T00:00:00Z", "tag": [ "tenderAmendment" ], - "parties": [ - { - "name": "Open Data Services", - "identifier": { - "scheme": "GB-COH", - "id": "09506232", - "legalName": "Open Data Services Co-operative", - "uri": "https://opencorporates.com/companies/gb/09506232" - }, - "roles": [ - "buyer" - ], - "id": "GB-COH-09506232" - } - ], - "buyer": { - "id": "GB-COH-09506232", - "name": "Open Data Services" - }, "tender": { - "id": "ocds-213czf-000-00002-01-tender", - "title": "Data merging tool", - "description": "Creation of a data merging tool. The tool should by written in Python. Proposals should be submitted by e-mail.", - "status": "active", + "id": "1", + "title": "Office supplies", "value": { - "amount": 2000, + "amount": 15000, "currency": "USD" }, - "procurementMethod": "open", - "awardCriteria": "bestProposal", - "tenderPeriod": { - "startDate": "2016-01-31T09:00:00Z", - "endDate": "2016-02-20T18:00:00Z" - }, - "awardPeriod": { - "startDate": "2016-04-01T00:00:00Z", - "endDate": "2016-06-01T23:59:59Z" - }, + "mainProcurementCategory": "goods", "amendments": [ { - "id": "amendment-1", - "date": "2016-02-04T09:30:00Z", - "rationale": "Based on feedback from potential bidders, the total budget was increased by $1000, and the deadline extended", - "amendsReleaseID": "ocds-213czf-000-00002-01-tender", - "releaseID": "ocds-213czf-000-00002-01-tender-amendment" + "id": "1", + "date": "2024-01-14T00:00:00Z", + "rationale": "Additional needs identified.", + "amendsReleaseID": "2", + "releaseID": "3" } ] } } ], "compiledRelease": { + "ocid": "ocds-213czf-000-00002", + "id": "ocds-213czf-000-00002-2024-01-14T00:00:00Z", + "date": "2024-01-14T00:00:00Z", "tag": [ "compiled" ], - "id": "ocds-213czf-000-00002-2016-02-05T10:30:00Z", - "date": "2016-02-05T10:30:00Z", - "ocid": "ocds-213czf-000-00002", - "parties": [ - { - "id": "GB-COH-09506232", - "name": "Open Data Services", - "identifier": { - "scheme": "GB-COH", - "id": "09506232", - "legalName": "Open Data Services Co-operative", - "uri": "https://opencorporates.com/companies/gb/09506232" - }, - "roles": [ - "buyer" - ] - } - ], - "buyer": { - "id": "GB-COH-09506232", - "name": "Open Data Services" - }, "tender": { - "id": "ocds-213czf-000-00002-01-tender", - "title": "Data merging tool", - "description": "Creation of a data merging tool. The tool should by written in Python. Proposals should be submitted by e-mail.", - "status": "active", + "id": "1", + "title": "Office supplies", "value": { - "amount": 2000, + "amount": 15000, "currency": "USD" }, - "procurementMethod": "open", - "awardCriteria": "bestProposal", - "tenderPeriod": { - "startDate": "2016-01-31T09:00:00Z", - "endDate": "2016-02-20T18:00:00Z" - }, - "awardPeriod": { - "startDate": "2016-04-01T00:00:00Z", - "endDate": "2016-06-01T23:59:59Z" - }, + "mainProcurementCategory": "goods", "amendments": [ { - "id": "amendment-1", - "date": "2016-02-04T09:30:00Z", - "rationale": "Based on feedback from potential bidders, the total budget was increased by $1000, and the deadline extended", - "amendsReleaseID": "ocds-213czf-000-00002-01-tender", - "releaseID": "ocds-213czf-000-00002-01-tender-amendment" + "id": "1", + "date": "2024-01-14T00:00:00Z", + "rationale": "Additional needs identified.", + "amendsReleaseID": "2", + "releaseID": "3" } ] - } + } }, "versionedRelease": { "ocid": "ocds-213czf-000-00002", - "parties": [ - { - "id": "GB-COH-09506232", - "name": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "Open Data Services" - } - ], - "identifier": { - "scheme": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "GB-COH" - } - ], - "id": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "09506232" - } - ], - "legalName": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "Open Data Services Co-operative" - } - ], - "uri": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "https://opencorporates.com/companies/gb/09506232" - } - ] - }, - "roles": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": [ - "buyer" - ] - } - ] - } - ], - "buyer": { - "id": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "GB-COH-09506232" - } - ], - "name": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "Open Data Services" - } - ] - }, "tender": { "id": [ { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", + "releaseID": "1", + "releaseDate": "2024-01-01T00:00:00Z", "releaseTag": [ "tender" ], - "value": "ocds-213czf-000-00002-01-tender" + "value": "1" } ], "title": [ { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "Data merging tool" - } - ], - "description": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", + "releaseID": "1", + "releaseDate": "2024-01-01T00:00:00Z", "releaseTag": [ "tender" ], - "value": "Data merge tool." - }, - { - "releaseID": "ocds-213czf-000-00002-01-tender-update", - "releaseDate": "2016-01-31T09:30:00Z", - "releaseTag": [ - "tenderUpdate" - ], - "value": "Creation of a data merging tool. The tool should by written in Python. Proposals should be submitted by e-mail." - } - ], - "status": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "active" + "value": "Office supplies" } ], "value": { "amount": [ { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", + "releaseID": "1", + "releaseDate": "2024-01-01T00:00:00Z", "releaseTag": [ "tender" ], - "value": 1000 + "value": 10000 }, { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", + "releaseID": "3", + "releaseDate": "2024-01-14T00:00:00Z", "releaseTag": [ "tenderAmendment" ], - "value": 2000 + "value": 15000 } ], "currency": [ { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", + "releaseID": "1", + "releaseDate": "2024-01-01T00:00:00Z", "releaseTag": [ "tender" ], @@ -383,119 +143,59 @@ } ] }, - "procurementMethod": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "open" - } - ], - "awardCriteria": [ + "mainProcurementCategory": [ { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", + "releaseID": "2", + "releaseDate": "2024-01-07T00:00:00Z", "releaseTag": [ "tender" ], - "value": "bestProposal" + "value": [ + "goods" + ] } ], - "tenderPeriod": { - "startDate": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "2016-01-31T09:00:00Z" - } - ], - "endDate": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "2016-02-15T18:00:00Z" - }, - { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", - "releaseTag": [ - "tenderAmendment" - ], - "value": "2016-02-20T18:00:00Z" - } - ] - }, - "awardPeriod": { - "startDate": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "2016-04-01T00:00:00Z" - } - ], - "endDate": [ - { - "releaseID": "ocds-213czf-000-00002-01-tender", - "releaseDate": "2016-01-01T09:30:00Z", - "releaseTag": [ - "tender" - ], - "value": "2016-06-01T23:59:59Z" - } - ] - }, "amendments": [ { - "id": "amendment-1", + "id": "1", "date": [ { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", + "releaseID": "3", + "releaseDate": "2024-01-14T00:00:00Z", "releaseTag": [ "tenderAmendment" ], - "value": "2016-02-04T09:30:00Z" + "value": "2024-01-14T00:00:00Z" } ], "rationale": [ { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", + "releaseID": "3", + "releaseDate": "2024-01-14T00:00:00Z", "releaseTag": [ "tenderAmendment" ], - "value": "Based on feedback from potential bidders, the total budget was increased by $1000, and the deadline extended" + "value": "Additional needs identified" } ], "amendsReleaseID": [ { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", + "releaseID": "3", + "releaseDate": "2024-01-14T00:00:00Z", "releaseTag": [ "tenderAmendment" ], - "value": "ocds-213czf-000-00002-01-tender" + "value": "2" } ], "releaseID": [ { - "releaseID": "ocds-213czf-000-00002-01-tender-amendment", - "releaseDate": "2016-02-05T10:30:00Z", + "releaseID": "3", + "releaseDate": "2024-01-14T00:00:00Z", "releaseTag": [ "tenderAmendment" ], - "value": "ocds-213czf-000-00002-01-tender-amendment" + "value": "2" } ] } diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 32c126d9e..0fbc2de32 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -24,11 +24,11 @@ The nature of a change can be made explicit using: ### Example 1: Tender updates and amendments -This example goes through updates during the **tender** stage in a contracting process. +This example illustrates how updates and amendments are modelled in OCDS. -#### Tender +#### Tender release -A publisher issues a tender for a "Data merge tool". A new release with the `tag` 'tender' is built, see the JSON example below. +A buyer publishes a tender for the purchase of office supplies. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/0 @@ -36,9 +36,9 @@ A publisher issues a tender for a "Data merge tool". A new release with the `tag :title: Tender ``` -#### Tender Update +#### Tender update release -Weeks later, the publisher expands the `description` of the tender to provide more details about the tool being procured. A new release with the `tag` 'tenderUpdate' is built. The publisher does not consider this to be a formal 'amendment' to the tender, so does not publish any amendment information. See the JSON release below. +The buyer adds a main procurement category to the tender. The new information is not a formal amendment to the tender so the publisher uses the 'tenderUpdate' tag and omits the `tender.amendments` field. The publisher chooses to repeat fields whose values are unchanged from the previous release. Such fields can be omitted when a publication provides access to historic releases. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/1 @@ -46,9 +46,9 @@ Weeks later, the publisher expands the `description` of the tender to provide mo :title: TenderUpdate ``` -#### Tender Amendment +#### Tender amendment release -A few days later, the publisher increases the value of the tender and extends the deadline for bid submissions. These changes are considered as an 'amendment' by the publisher (depending on jurisdiction, certain changes can need to be disclosed as amendments), and so the new release has the `tag` 'tenderAmendment' and an `amendments` block under `tender`. The release reflects the updated value (USD 2000 instead of USD 1000) and the updated closing date for bid submissions (`2012-02-20` instead of `2012-02-15`). See the JSON example below. +The buyer increases the estimated value of the tender. This change is a formal amendment to the tender so the publisher uses the 'tenderAmendment' tag and populates the `tender.amendments` field. Note that `tender.amendments` does not include the changed values. Rather, the `tender.value.amount` field itself is updated. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/2 @@ -58,11 +58,11 @@ A few days later, the publisher increases the value of the tender and extends th #### Record -A full record is provided below, with all the releases for the process and a `compiledRelease` and `versionedRelease`. The `versionedRelease` block reflects all the changes made in the tender. +`releases` contains the above releases, `compiledRelease` contains the latest value of each field and, `versionedRelease` contains a history of changes to each field. The `releaseID` and `amendsReleaseID` fields in the `amendments` array of the compiled release can be looked up in `releases` and `versionedRelease` to identify what changed. ```{jsoninclude} ../../examples/amendments/tender.json -:jsonpointer: -:expand: records, releases +:jsonpointer: /records/0 +:expand: compiledRelease, versionedRelease, value, amount :title: FullRecord ``` @@ -70,14 +70,6 @@ A full record is provided below, with all the releases for the process and a `co It is encouraged to [download](../../examples/amendments/tender.json) the record example and use the [Data Review Tool](https://review.standard.open-contracting.org/) to explore the changes in the contracting process. ``` -Note in this example that: - -* **The amendments block does not contain data on what was changed**. Changes are recorded by updating the fields of the `tender` block a new release. - -* **The publisher chooses in the 'tenderAmendment' release to repeat a fragment of the original 'tender' release**. This is not necessary when a full archive of releases is made accessible, but a publisher might want to provide the latest data available in each release. - -* **In the record**, the `releaseID` and `amendsReleaseID` fields from the `amendments` array can be used to look up information in the `versionedRelease` object or `releases` array, to see where changes are explained by an amendment `rationale`. - ### Example 2: Contract amendment This example shows an update to the value and scope of a contract. From b310838b59119169347394e964de56f22776e126 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 28 Feb 2024 16:37:43 +1300 Subject: [PATCH 2/3] docs/guidance/map/amendments.md: Add paragraph breaks --- docs/guidance/map/amendments.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 0fbc2de32..4cded05cd 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -38,7 +38,9 @@ A buyer publishes a tender for the purchase of office supplies. #### Tender update release -The buyer adds a main procurement category to the tender. The new information is not a formal amendment to the tender so the publisher uses the 'tenderUpdate' tag and omits the `tender.amendments` field. The publisher chooses to repeat fields whose values are unchanged from the previous release. Such fields can be omitted when a publication provides access to historic releases. +The buyer adds a main procurement category to the tender. The new information is not a formal amendment to the tender so the publisher uses the 'tenderUpdate' tag and omits the `tender.amendments` field. + +The publisher chooses to repeat fields whose values are unchanged from the previous release. Such fields can be omitted when a publication provides access to historic releases. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/1 @@ -48,7 +50,9 @@ The buyer adds a main procurement category to the tender. The new information is #### Tender amendment release -The buyer increases the estimated value of the tender. This change is a formal amendment to the tender so the publisher uses the 'tenderAmendment' tag and populates the `tender.amendments` field. Note that `tender.amendments` does not include the changed values. Rather, the `tender.value.amount` field itself is updated. +The buyer increases the estimated value of the tender. This change is a formal amendment to the tender so the publisher uses the 'tenderAmendment' tag and populates the `tender.amendments` field. + +Note that `tender.amendments` does not include the changed values. Rather, the `tender.value.amount` field itself is updated. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/2 @@ -58,7 +62,9 @@ The buyer increases the estimated value of the tender. This change is a formal a #### Record -`releases` contains the above releases, `compiledRelease` contains the latest value of each field and, `versionedRelease` contains a history of changes to each field. The `releaseID` and `amendsReleaseID` fields in the `amendments` array of the compiled release can be looked up in `releases` and `versionedRelease` to identify what changed. +`releases` contains the above releases, `compiledRelease` contains the latest value of each field and, `versionedRelease` contains a history of changes to each field. + +The `releaseID` and `amendsReleaseID` fields in the `amendments` array of the compiled release can be looked up in `releases` and `versionedRelease` to identify what changed. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0 From ff14232dee94008109ed1d2794deae8d5dd822b8 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 28 Feb 2024 16:43:34 +1300 Subject: [PATCH 3/3] docs/examples/amendments/tender.json: Reindent --- docs/examples/amendments/tender.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/amendments/tender.json b/docs/examples/amendments/tender.json index 8ffc05e07..c30cae455 100644 --- a/docs/examples/amendments/tender.json +++ b/docs/examples/amendments/tender.json @@ -88,7 +88,7 @@ "releaseID": "3" } ] - } + } }, "versionedRelease": { "ocid": "ocds-213czf-000-00002",