From e0429fd5a0f53ea144804153cf74f19ab9298d50 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 28 Feb 2024 16:33:44 +1300 Subject: [PATCH 01/36] 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 02/36] 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 03/36] 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", From 667f2dd88550616f172d0fc49e14a4bb6241db6e Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 11:54:49 +1300 Subject: [PATCH 04/36] docs/guidance/map/amendments.md: Copy edits --- docs/guidance/map/amendments.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 4cded05cd..76ab82432 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -4,31 +4,31 @@ # Updates and amendments -Information about a contracting (or planning) process will often change over time. +Information about a contracting (or planning) process often changes over time. -Each time information changes, a new OCDS release ought to be published. The new release can contain information that was previously published, in addition to the new information. +Each time information changes, a new OCDS release ought to be published. The new release can repeat information that was previously published, in addition to new and changed information. -There are three kinds of changes: +There are three types of change: * **New information**. For example, when information about the award of a contract is first released. -* **Updates to existing information**. For example, to correct errors in earlier releases, or to make minor adjustments to titles, descriptions or date. -* **Amendments**. For example, when the value or duration of a contract is changed. The term amendment often has a specific legal meaning for a publisher. Certain changes to a tender, award or contract might only be allowed as part of an amendment. +* **Updates to existing information**. For example, to correct errors in earlier releases, or to make minor adjustments to titles, descriptions or dates. +* **Amendments**. For example, when the value or duration of a contract is changed. The term amendment often has a specific legal meaning for a publisher. Certain changes to a tender, award or contract might only be permitted as part of an amendment. The nature of a change can be made explicit using: -* **The release tag** (`tag`). For example, for a release with a new contract, use 'contract'. For an update to the contract, use 'contractUpdate', and for an amendment to the contract, use 'contractAmendment'. +* **The release tag** field (`tag`), which is used to identify the type of change. For example, 'contract' identifies information about a new contract, 'contractUpdate' identifies an update to existing information about a contract, and 'contractAmendment' identifies a formal amendment to a contract. -* **The amendments** building block. This can contain an array of amendment explanations, and clearly identify the releases that contain before and after values. +* **The amendments** fields (`tender.amendments` and `contract.amendments`), which are used to list amendments along with their rationales and references to the releases that contain before and after values. ## Worked examples ### Example 1: Tender updates and amendments -This example illustrates how updates and amendments are modelled in OCDS. +This example illustrates how new information, updates and amendments are modelled in OCDS. #### Tender release -A buyer publishes a tender for the purchase of office supplies. +A buyer publishes an opportunity for the purchase of office supplies. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/0 @@ -38,7 +38,7 @@ 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 buyer now indicates the opportunity's main procurement category. The new information is not a formal amendment 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. @@ -50,7 +50,7 @@ The publisher chooses to repeat fields whose values are unchanged from the previ #### 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. +The buyer increases the estimated value of the opportunity. This change is a formal amendment 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. @@ -62,7 +62,7 @@ Note that `tender.amendments` does not include the changed values. Rather, the ` #### Record -`releases` contains the above releases, `compiledRelease` contains the latest value of each field and, `versionedRelease` contains a history of changes to each field. +`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. @@ -73,7 +73,7 @@ The `releaseID` and `amendsReleaseID` fields in the `amendments` array of the co ``` ```{hint} -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. +[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. ``` ### Example 2: Contract amendment From 87aec718bb1014bebb42e2148a0c63103f1f9ac6 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 12:24:45 +1300 Subject: [PATCH 05/36] docs/schema/records_reference.md: Make examples minimal, copy edit --- .../record_reference/linked_releases.json | 24 +++++++++++++++++++ docs/schema/records_reference.md | 18 +++++++------- 2 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 docs/examples/record_reference/linked_releases.json diff --git a/docs/examples/record_reference/linked_releases.json b/docs/examples/record_reference/linked_releases.json new file mode 100644 index 000000000..cea64c2ab --- /dev/null +++ b/docs/examples/record_reference/linked_releases.json @@ -0,0 +1,24 @@ +{ + "version": "1.1", + "records": [ + { + "ocid": "ocds-213czf-000-00002", + "releases": [ + { + "url": "http://example.com/release_package.json#1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "tender" + ] + }, + { + "url": "http://example.com/release_package.json#2", + "date": "2024-01-07T00:00:00Z", + "tag": [ + "tenderUpdate" + ] + } + ] + } + ] +} diff --git a/docs/schema/records_reference.md b/docs/schema/records_reference.md index cc2ba78fc..f53fee284 100644 --- a/docs/schema/records_reference.md +++ b/docs/schema/records_reference.md @@ -30,7 +30,7 @@ A record **may** contain a [versionedRelease](#versioned-release) object, which ````{admonition} Example :class: hint -```{jsoninclude} ../examples/merging/updates/versioned.json +```{jsoninclude} ../examples/amendments/tender.json :jsonpointer: /records/0 :title: record ``` @@ -56,15 +56,17 @@ For each `url` value, it must be possible for a consuming application to retriev The following example demonstrates the use of linked releases. -```{jsoninclude} ../examples/merging/updates/versioned.json +```{jsoninclude} ../examples/record_reference/linked_releases.json :jsonpointer: /records/0 :expand: releases, tag -:title: releases ``` -Above, the first linked release has a `url` value of `https://standard.open-contracting.org/examples/releases/ocds-213czf-000-00002-01-award1.json#ocds-213czf-000-00002-01-award1`. The first part (`https://standard.open-contracting.org/examples/releases/ocds-213czf-000-00002-01-award1.json`) is the URL of the release package, and the fragment identifier (`ocds-213czf-000-00002-01-award1`) is the `id` of the release. +Each release's `url` consists of two parts: + +* The URL of the release package that contains the release: `http://example.com/release_package.json` +* A fragment identifier (introduced by a hash mark #) whose value is the `id` of the release: `1` or `2` -Release `id` values are only required to be unique within the scope of a (contracting or planning) process: that is, within the scope of an `ocid` value. As such, a consuming application needs to use that fragment identifier in combination with the `ocid` of the record in order to identify the matching release within the release package. +Release `id` values are only required to be unique within the scope of a (contracting or planning) process: that is, within the scope of an `ocid` value. As such, a consuming application needs to use the fragment identifier in combination with the `ocid` of the record in order to identify the matching release within the release package. #### Embedded releases @@ -72,7 +74,7 @@ An embedded release follows the [release schema](reference). In other words, ins The following example demonstrates the use of embedded releases. -```{jsoninclude} ../examples/merging/embedded_releases.json +```{jsoninclude} ../examples/amendments/tender.json :jsonpointer: /records/0 :expand: releases,tag :title: releases @@ -106,8 +108,8 @@ A separate, auto-generated [versioned release schema](../../build/current_lang/v The following example displays a single field's [versioned values](merging.md#versioned-values). This shows that the amount changed between the tender stage and a tender amendment, while the currency did not. -```{jsoninclude} ../examples/merging/updates/versioned.json +```{jsoninclude} ../examples/amendments/tender.json :jsonpointer: /records/0/versionedRelease/tender/value -:expand: amount, releaseTag +:expand: amount, currency, releaseTag :title: versioned ``` From adcd4700e14d44452c10d5591b19d2835c2f424a Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 12:59:42 +1300 Subject: [PATCH 06/36] docs/guidance/map/awards_contracts.md: Update examples --- docs/examples/award_decisions/identifiers.csv | 4 -- docs/examples/award_decisions/multi_award.csv | 4 -- .../examples/award_decisions/multi_award.json | 57 ++++++++++++++++++ .../examples/award_decisions/single_award.csv | 2 - .../award_decisions/single_award.json | 48 +++++++++++++++ .../award_contract_changes.json | 59 +++++++++++++++++++ docs/guidance/map/awards_contracts.md | 40 ++++++------- 7 files changed, 184 insertions(+), 30 deletions(-) delete mode 100644 docs/examples/award_decisions/identifiers.csv delete mode 100644 docs/examples/award_decisions/multi_award.csv create mode 100644 docs/examples/award_decisions/multi_award.json delete mode 100644 docs/examples/award_decisions/single_award.csv create mode 100644 docs/examples/award_decisions/single_award.json create mode 100644 docs/examples/awards_contracts/award_contract_changes.json diff --git a/docs/examples/award_decisions/identifiers.csv b/docs/examples/award_decisions/identifiers.csv deleted file mode 100644 index 31981103a..000000000 --- a/docs/examples/award_decisions/identifiers.csv +++ /dev/null @@ -1,4 +0,0 @@ -awards/0/id,awards/0/value/amount,awards/0/suppliers/0/name -340885-electropar-sa-6,0,ELECTROPAR SA -340885-limburg-equities-s-a-5,698160,Limburg Equities S.A. -340885-sas-paraguay-s-a-2,330000,SAS PARAGUAY S.A. diff --git a/docs/examples/award_decisions/multi_award.csv b/docs/examples/award_decisions/multi_award.csv deleted file mode 100644 index a0a172997..000000000 --- a/docs/examples/award_decisions/multi_award.csv +++ /dev/null @@ -1,4 +0,0 @@ -awards/0/value/amount,awards/0/suppliers/0/name -0,ELECTROPAR SA -698160,Limburg Equities S.A. -330000,SAS PARAGUAY S.A. diff --git a/docs/examples/award_decisions/multi_award.json b/docs/examples/award_decisions/multi_award.json new file mode 100644 index 000000000..59619b4fc --- /dev/null +++ b/docs/examples/award_decisions/multi_award.json @@ -0,0 +1,57 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-00002", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "award" + ], + "awards": [ + { + "id": "1", + "value": { + "amount": 75000, + "currency": "PYG" + }, + "suppliers": [ + { + "id": "1", + "name": "ELECTROPAR SA" + } + ] + }, + { + "id": "2", + "value": { + "amount": 25000, + "currency": "PYG" + }, + "suppliers": [ + { + "id": "2", + "name": "Limburg Equities S.A." + } + ] + } + ], + "parties": [ + { + "id": "1", + "name": "ELECTROPAR SA", + "roles": [ + "supplier" + ] + }, + { + "id": "2", + "name": "Limburg Equities S.A.", + "roles": [ + "supplier" + ] + } + ] + } + ] +} diff --git a/docs/examples/award_decisions/single_award.csv b/docs/examples/award_decisions/single_award.csv deleted file mode 100644 index 0f035db2f..000000000 --- a/docs/examples/award_decisions/single_award.csv +++ /dev/null @@ -1,2 +0,0 @@ -awards/0/id,awards/0/value/amount,awards/0/suppliers/0/name,awards/0/suppliers/1/name,awards/0/suppliers/2/name -340885-Lp1367-18,1028160,ELECTROPAR SA,Limburg Equities S.A.,SAS PARAGUAY S.A. diff --git a/docs/examples/award_decisions/single_award.json b/docs/examples/award_decisions/single_award.json new file mode 100644 index 000000000..593e66d63 --- /dev/null +++ b/docs/examples/award_decisions/single_award.json @@ -0,0 +1,48 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-00002", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "award" + ], + "awards": [ + { + "id": "1", + "value": { + "amount": 100000, + "currency": "PYG" + }, + "suppliers": [ + { + "id": "1", + "name": "ELECTROPAR SA" + }, + { + "id": "2", + "name": "Limburg Equities S.A." + } + ] + } + ], + "parties": [ + { + "id": "1", + "name": "ELECTROPAR SA", + "roles": [ + "supplier" + ] + }, + { + "id": "2", + "name": "Limburg Equities S.A.", + "roles": [ + "supplier" + ] + } + ] + } + ] +} diff --git a/docs/examples/awards_contracts/award_contract_changes.json b/docs/examples/awards_contracts/award_contract_changes.json new file mode 100644 index 000000000..11cd5a808 --- /dev/null +++ b/docs/examples/awards_contracts/award_contract_changes.json @@ -0,0 +1,59 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-00001", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "award" + ], + "buyer": { + "id": "1", + "name": "Ministry of Finance" + }, + "awards": [ + { + "id": "1", + "title": "Award of contract for website development", + "suppliers": [ + { + "id": "2", + "name": "360nx Designs" + } + ] + } + ], + "parties": [ + { + "id": "1", + "name": "Ministry of Finance", + "roles": [ + "buyer" + ] + }, + { + "id": "2", + "name": "360nx Designs", + "roles": [ + "supplier" + ] + } + ] + }, + { + "ocid": "ocds-213czf-00001", + "id": "2", + "date": "2024-01-11T00:00:00Z", + "tag": [ + "awardCancellation" + ], + "awards": [ + { + "id": "1", + "finalStatus": "cancelled" + } + ] + } + ] +} diff --git a/docs/guidance/map/awards_contracts.md b/docs/guidance/map/awards_contracts.md index e3041882d..eea392c66 100644 --- a/docs/guidance/map/awards_contracts.md +++ b/docs/guidance/map/awards_contracts.md @@ -101,11 +101,21 @@ Once an award is published by the e-procurement system, there is a 10-day stands If an appeal is made and upheld, then the award is cancelled. If no appeals are upheld by the end of the standstill period, then a contract is signed between the buyer and the supplier, outside of the e-procurement system. No OCDS data is published or updated from this stage of the contracting process onward. -In this example, the Ministry of Finance uses the e-procurement system to solicit bids for the development of a new website. A contract is awarded to 360nx Designs for 3,000,000 ZMK, through the e-procurement system. +The Ministry of Finance uses the e-procurement system to award a contract for website development to to 360nx Designs. + +```{jsoninclude} ../../examples/awards_contracts/award_contract_changes.json +:jsonpointer: /releases/0 +:expand: awards, suppliers +``` An unsuccessful bidder appeals the award decision and the appeal is upheld, resulting the award being cancelled. -If both the `award` and `contract` sections of OCDS had been populated when the award was made through the e-procurement system, this would have resulted in the presence of a contract in the OCDS data that had never existed in reality. +```{jsoninclude} ../../examples/awards_contracts/award_contract_changes.json +:jsonpointer: /releases/1 +:expand: awards +``` + +If the `contract` section had been populated when the award was made through the e-procurement system, it would have resulted in the presence of a contract in the OCDS data that had never existed in reality. ## Awards and award notices @@ -121,30 +131,20 @@ In Paraguay, a single award notice is used to disclose many award decisions. Det Using a single award object to model such a notice in OCDS would make it impossible to determine which items related to which suppliers or how much of the total award value related to each supplier: -```{csv-table-no-translate} -:header-rows: 1 -:file: ../../examples/award_decisions/single_award.csv +```{jsoninclude} ../../examples/award_decisions/single_award.json +:jsonpointer: /releases/0 +:expand: awards, value, suppliers ``` -For the award object in OCDS to communicate a direct relationship between items, suppliers, and values, Paraguay's award notice is split into multiple award objects, one for each supplier/value pairing on the notice. - -```{csv-table-no-translate} -:header-rows: 1 -:file: ../../examples/award_decisions/multi_award.csv -``` +For the award object in OCDS to communicate a direct relationship between items, suppliers, and values, the award notice is split into multiple award objects, one for each supplier/value pairing on the notice. -There are no identifiers for the individual supplier/value pairings on the original award notice, so it is necessary to create a new identifier for each award object in OCDS. The approach to creating an identifier will depend on the properties of the dataset; for example, in Paraguay a combination of the award notice identifier, supplier name, and a consecutive number is used. +There are no identifiers for the individual supplier/value pairings on the original award notice, so it is necessary to create a new identifier for each award object in OCDS. The approach to creating an identifier will depend on the properties of the dataset; for example, using the supplier's `.id`. -```{csv-table-no-translate} -:header-rows: 1 -:file: ../../examples/award_decisions/identifiers.csv +```{jsoninclude} ../../examples/award_decisions/multi_award.json +:jsonpointer: /releases/0 +:expand: awards, value, suppliers ``` -```{admonition} View the example in JSON -:class: tip - -[View the example in Paraguay's API](https://contrataciones.gov.py/datos/api/v3/doc/ocds/record/ocds-03ad3f-340885-1) -``` ## Purchase orders A purchase order is a specific type of contract, an official document issued by a buyer committing to pay a supplier for the supply of specific goods, services or works to be delivered in the future. From a6090662565b5acd197ab62ea2355ead5725bc09 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 16:50:08 +1300 Subject: [PATCH 07/36] docs/guidance/map/amendments.md: Remove contract example --- docs/examples/amendments/contract.json | 754 ------------------------- docs/guidance/map/amendments.md | 46 +- 2 files changed, 3 insertions(+), 797 deletions(-) delete mode 100644 docs/examples/amendments/contract.json diff --git a/docs/examples/amendments/contract.json b/docs/examples/amendments/contract.json deleted file mode 100644 index b4e476a73..000000000 --- a/docs/examples/amendments/contract.json +++ /dev/null @@ -1,754 +0,0 @@ -{ - "version": "1.1", - "records": [ - { - "ocid": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856", - "releases": [ - { - "id": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "ocid": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856", - "date": "2019-02-15T01:00:58Z", - "tag": [ - "contract" - ], - "contracts": [ - { - "status": "active", - "description": "Appliances for Tuvalu PPB Residence", - "title": "4501062723", - "items": [ - { - "id": "1", - "description": "Domestic coffee maker", - "quantity": 2, - "classification": { - "scheme": "UNSPSC", - "id": "52141526" - } - }, - { - "id": "2", - "description": "Domestic electrical kettle", - "quantity": 2, - "classification": { - "scheme": "UNSPSC", - "id": "52141523" - } - } - ], - "period": { - "startDate": "2018-11-30T01:00:00Z", - "endDate": "2019-12-30T01:00:00Z" - }, - "value": { - "currency": "AUD", - "amount": 750.0 - }, - "dateSigned": "2018-12-21T02:49:50Z", - "awardID": "CN3562241-12b0ab89ef79180a7289cb6c40c33c1f", - "id": "CN3562241" - } - ], - "parties": [ - { - "identifier": { - "scheme": "AU-ABN", - "id": "60010555549" - }, - "name": "NORSHIP MARINE", - "roles": [ - "supplier" - ], - "address": { - "postalCode": "4870", - "country": "AU", - "region": "QLD", - "locality": "PORTSMITH" - }, - "contactPoint": { - "email": "BMI.FINANCIALREPORTING@DEFENCE.GOV.AU", - "telephone": "00", - "name": "SP&I - International Policy" - }, - "id": "fb9c43bb01f873c72c730bdac5b0858f" - }, - { - "identifier": { - "scheme": "AU-ABN", - "id": "62950639680" - }, - "name": "Department of Defence", - "roles": [ - "buyer" - ], - "contactPoint": { - "email": "tenders@finance.gov.au" - }, - "id": "0ec9911c9e99d1b7bb1b77f4abffc583" - } - ] - }, - { - "id": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "ocid": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856", - "date": "2019-02-17T00:00:00Z", - "tag": [ - "contractAmendment" - ], - "contracts": [ - { - "status": "active", - "amendments": [ - { - "id": "1", - "amendsReleaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "rationale": "After negotiations with the supplier, the scope of the contract has been increased to purchase an additional item.", - "date": "2019-02-16T12:00:00Z" - } - ], - "description": "Appliances for Tuvalu PPB Residence", - "title": "4501062723", - "items": [ - { - "id": "3", - "description": "Domestic microwave oven", - "quantity": 1, - "classification": { - "scheme": "UNSPSC", - "id": "52141502" - } - } - ], - "period": { - "startDate": "2018-11-30T01:00:00Z", - "endDate": "2019-12-30T01:00:00Z" - }, - "value": { - "currency": "AUD", - "amount": 1250.0 - }, - "dateSigned": "2018-12-21T02:49:50Z", - "awardID": "CN3562241-12b0ab89ef79180a7289cb6c40c33c1f", - "id": "CN3562241" - } - ], - "parties": [ - { - "identifier": { - "scheme": "AU-ABN", - "id": "60010555549" - }, - "name": "NORSHIP MARINE", - "roles": [ - "supplier" - ], - "address": { - "postalCode": "4870", - "country": "AU", - "region": "QLD", - "locality": "PORTSMITH" - }, - "contactPoint": { - "email": "BMI.FINANCIALREPORTING@DEFENCE.GOV.AU", - "telephone": "00", - "name": "SP&I - International Policy" - }, - "id": "fb9c43bb01f873c72c730bdac5b0858f" - }, - { - "identifier": { - "scheme": "AU-ABN", - "id": "62950639680" - }, - "name": "Department of Defence", - "roles": [ - "buyer" - ], - "contactPoint": { - "email": "tenders@finance.gov.au" - }, - "id": "0ec9911c9e99d1b7bb1b77f4abffc583" - } - ] - } - ], - "compiledRelease": { - "tag": [ - "compiled" - ], - "id": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2019-02-17T00:00:00Z", - "date": "2019-02-17T00:00:00Z", - "ocid": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856", - "contracts": [ - { - "id": "CN3562241", - "status": "active", - "description": "Appliances for Tuvalu PPB Residence", - "title": "4501062723", - "items": [ - { - "id": "1", - "description": "Domestic coffee maker", - "quantity": 2, - "classification": { - "scheme": "UNSPSC", - "id": "52141526" - } - }, - { - "id": "2", - "description": "Domestic electrical kettle", - "quantity": 2, - "classification": { - "scheme": "UNSPSC", - "id": "52141523" - } - }, - { - "id": "3", - "description": "Domestic microwave oven", - "quantity": 1, - "classification": { - "scheme": "UNSPSC", - "id": "52141502" - } - } - ], - "period": { - "startDate": "2018-11-30T01:00:00Z", - "endDate": "2019-12-30T01:00:00Z" - }, - "value": { - "currency": "AUD", - "amount": 1250.0 - }, - "dateSigned": "2018-12-21T02:49:50Z", - "awardID": "CN3562241-12b0ab89ef79180a7289cb6c40c33c1f", - "amendments": [ - { - "id": "1", - "amendsReleaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "rationale": "Increased scope of goods required.", - "date": "2019-02-16T12:00:00Z" - } - ] - } - ], - "parties": [ - { - "id": "fb9c43bb01f873c72c730bdac5b0858f", - "identifier": { - "scheme": "AU-ABN", - "id": "60010555549" - }, - "name": "NORSHIP MARINE", - "roles": [ - "supplier" - ], - "address": { - "postalCode": "4870", - "country": "AU", - "region": "QLD", - "locality": "PORTSMITH" - }, - "contactPoint": { - "email": "BMI.FINANCIALREPORTING@DEFENCE.GOV.AU", - "telephone": "00", - "name": "SP&I - International Policy" - } - }, - { - "id": "0ec9911c9e99d1b7bb1b77f4abffc583", - "identifier": { - "scheme": "AU-ABN", - "id": "62950639680" - }, - "name": "Department of Defence", - "roles": [ - "buyer" - ], - "contactPoint": { - "email": "tenders@finance.gov.au" - } - } - ] - }, - "versionedRelease": { - "ocid": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856", - "contracts": [ - { - "id": "CN3562241", - "status": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "active" - } - ], - "description": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "Appliances for Tuvalu PPB Residence" - } - ], - "title": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "4501062723" - } - ], - "items": [ - { - "id": "1", - "description": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "Domestic coffee maker" - } - ], - "quantity": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": 2 - } - ], - "classification": { - "scheme": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "UNSPSC" - } - ], - "id": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "52141526" - } - ] - } - }, - { - "id": "2", - "description": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "Domestic electrical kettle" - } - ], - "quantity": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": 2 - } - ], - "classification": { - "scheme": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "UNSPSC" - } - ], - "id": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "52141523" - } - ] - } - }, - { - "id": "3", - "description": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "Domestic microwave oven" - } - ], - "quantity": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": 1 - } - ], - "classification": { - "scheme": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "UNSPSC" - } - ], - "id": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "52141502" - } - ] - } - } - ], - "period": { - "startDate": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "2018-11-30T01:00:00Z" - } - ], - "endDate": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "2019-12-30T01:00:00Z" - } - ] - }, - "value": { - "currency": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "AUD" - } - ], - "amount": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": 750.0 - }, - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": 1250.0 - } - ] - }, - "dateSigned": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "2018-12-21T02:49:50Z" - } - ], - "awardID": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "CN3562241-12b0ab89ef79180a7289cb6c40c33c1f" - } - ], - "amendments": [ - { - "id": "1", - "amendsReleaseID": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24" - } - ], - "releaseID": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5" - } - ], - "rationale": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "Increased scope of goods required." - } - ], - "date": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-2000b475e7c23fcda74fcae13275e6c5", - "releaseDate": "2019-02-17T00:00:00Z", - "releaseTag": [ - "contractAmendment" - ], - "value": "2019-02-16T12:00:00Z" - } - ] - } - ] - } - ], - "parties": [ - { - "id": "fb9c43bb01f873c72c730bdac5b0858f", - "identifier": { - "scheme": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "AU-ABN" - } - ], - "id": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "60010555549" - } - ] - }, - "name": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "NORSHIP MARINE" - } - ], - "roles": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": [ - "supplier" - ] - } - ], - "address": { - "postalCode": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "4870" - } - ], - "country": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "AU" - } - ], - "region": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "QLD" - } - ], - "locality": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "PORTSMITH" - } - ] - }, - "contactPoint": { - "email": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "BMI.FINANCIALREPORTING@DEFENCE.GOV.AU" - } - ], - "telephone": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "00" - } - ], - "name": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "SP&I - International Policy" - } - ] - } - }, - { - "id": "0ec9911c9e99d1b7bb1b77f4abffc583", - "identifier": { - "scheme": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "AU-ABN" - } - ], - "id": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "62950639680" - } - ] - }, - "name": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "Department of Defence" - } - ], - "roles": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": [ - "buyer" - ] - } - ], - "contactPoint": { - "email": [ - { - "releaseID": "ocds-d2phr6-12b0ab8ac4c28d322a82062e99918856-9887f9ebe7043172ab2abe4db2a5aa24", - "releaseDate": "2019-02-15T01:00:58Z", - "releaseTag": [ - "contract" - ], - "value": "tenders@finance.gov.au" - } - ] - } - } - ] - } - } - ] -} diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 76ab82432..9d6bd8e64 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -76,51 +76,11 @@ The `releaseID` and `amendsReleaseID` fields in the `amendments` array of the co [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. ``` -### Example 2: Contract amendment - -This example shows an update to the value and scope of a contract. - -#### Contract - -A contract signature notice is published for the purchase of domestic appliances. The publisher builds a release and uses the 'contract' `tag`. - -See the JSON release below. - -```{jsoninclude} ../../examples/amendments/contract.json -:jsonpointer: /records/0/releases/0 -:expand: tag, contracts, items -:title: Contract -``` - -#### Contract Amendment - -A few days after the contract release, its scope is increased to include the purchase of one additional appliance. A new 'contractAmendment' release is built, where a single item is added in the `contracts/items` block and the value of the contract is increased. A `amendments` block is included to explain the rationale of the changes. - -See the example release below. - -```{jsoninclude} ../../examples/amendments/contract.json -:jsonpointer: /records/0/releases/1 -:expand: tag, contracts, items, amendments -:title: ContractAmendment -``` - -Note that amendments can cover more than values or duration. Also, note that the publisher chose to not repeat the contract items, but add a new one with a new ID value. - -In certain scenarios there might not be a valid `amendsReleaseID` and so it can be omitted, e.g. when historical data is being published in a single release. - -#### Record - -An example record for the whole process is shown below. Consider downloading the [record example](../../examples/amendments/contract.json) and use the [Data Review Tool](https://review.standard.open-contracting.org/) to explore the changes in the contracting process. - -Note that the `compiledRelease` contains all the items, included the latest one added in the contract amendment. - -```{jsoninclude} ../../examples/amendments/contract.json -:jsonpointer: -:expand: records, releases -:title: Record +```{admonition} Contract updates and amendments +Contract updates and amendments are modelled in the same way: the 'contract', 'contractUpdate' and 'contractAmendment' release tags distinguish the type of change and amendments are listed in the `contract.amendments` field. ``` -### Example 3: Amendments in a Easy Releases scenario +### Example 2: Amendments in a Easy Releases scenario The [Easy releases guidance](../build/easy_releases) explains how to publish releases without storing or publishing a full change history. Depending on the source system, it might still be possible to publish a history of amendments when using this model. From 992c3c250212991660449d7c832b578ad7bf20c8 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 18:07:13 +1300 Subject: [PATCH 08/36] docs/guidance/map/milestones.md: Update examples, copy edit --- .../milestones/delivery_milestones.json | 59 ++++++++ ...entation_financial_milestones_not_met.json | 71 ---------- ...on_financial_milestones_partially_met.json | 75 ---------- ...tion_financial_milestones_transaction.json | 129 ------------------ .../implementation_milestones_met.json | 61 --------- ...plementation_milestones_partially_met.json | 63 --------- .../implementation_milestones_scheduled.json | 58 -------- .../milestones/payment_milestones.json | 79 +++++++++++ .../planning-tender-milestones-2.json | 27 ---- .../milestones/planning_milestone.json | 34 ----- .../milestones/planning_milestones.json | 24 ++++ docs/guidance/map/milestones.md | 111 ++++++--------- docs/schema/reference.md | 2 +- 13 files changed, 203 insertions(+), 590 deletions(-) create mode 100644 docs/examples/milestones/delivery_milestones.json delete mode 100644 docs/examples/milestones/implementation_financial_milestones_not_met.json delete mode 100644 docs/examples/milestones/implementation_financial_milestones_partially_met.json delete mode 100644 docs/examples/milestones/implementation_financial_milestones_transaction.json delete mode 100644 docs/examples/milestones/implementation_milestones_met.json delete mode 100644 docs/examples/milestones/implementation_milestones_partially_met.json delete mode 100644 docs/examples/milestones/implementation_milestones_scheduled.json create mode 100644 docs/examples/milestones/payment_milestones.json delete mode 100644 docs/examples/milestones/planning-tender-milestones-2.json delete mode 100644 docs/examples/milestones/planning_milestone.json create mode 100644 docs/examples/milestones/planning_milestones.json diff --git a/docs/examples/milestones/delivery_milestones.json b/docs/examples/milestones/delivery_milestones.json new file mode 100644 index 000000000..c94182b23 --- /dev/null +++ b/docs/examples/milestones/delivery_milestones.json @@ -0,0 +1,59 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "implementation" + ], + "contracts": [ + { + "id": "1", + "title": "Cycle lane construction", + "implementation": { + "milestones": [ + { + "id": "1", + "title": "Project completion", + "type": "delivery", + "code": "completion", + "dueDate": "2024-06-30T00:00:00Z", + "status": "scheduled" + } + ] + } + } + ] + }, + { + "ocid": "ocds-213czf-0000", + "id": "2", + "date": "2024-07-15T00:00:00Z", + "tag": [ + "implementationUpdate" + ], + "contracts": [ + { + "id": "1", + "title": "Cycle lane construction", + "implementation": { + "milestones": [ + { + "id": "1", + "title": "Project completion", + "type": "delivery", + "code": "completion", + "dueDate": "2024-06-30T00:00:00Z", + "status": "met", + "dateMet": "2024-07-15T00:00:00Z", + "dateModified": "2024-07-15T00:00:00Z" + } + ] + } + } + ] + } + ] +} diff --git a/docs/examples/milestones/implementation_financial_milestones_not_met.json b/docs/examples/milestones/implementation_financial_milestones_not_met.json deleted file mode 100644 index e97475d47..000000000 --- a/docs/examples/milestones/implementation_financial_milestones_not_met.json +++ /dev/null @@ -1,71 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "contracts": [ - { - "status": "active", - "title": "School repairs and mantainance projects, Rahman Baba & Khushal Khan Khattak", - "implementation": { - "milestones": [ - { - "status": "notMet", - "title": "Payment for finish the exterior and interior walls", - "dueDate": "2018-10-10T00:00:00+04:30", - "type": "payment", - "id": "20653payment", - "value": { - "amount": 76955, - "currency": "AFN" - } - }, - { - "status": "notMet", - "title": "Finish the exterior and interior walls", - "dueDate": "2018-10-05T00:00:00+04:30", - "type": "delivery", - "id": "20653Delivery" - }, - { - "status": "notMet", - "title": "Payment for repair of the electric system", - "dueDate": "2018-10-31T00:00:00+04:30", - "type": "payment", - "id": "20654payment", - "value": { - "amount": 40000, - "currency": "AFN" - } - }, - { - "status": "notMet", - "title": "Repair of the electric system", - "dueDate": "2018-10-28T00:00:00+04:30", - "type": "delivery", - "id": "20654Delivery" - } - ] - }, - "period": { - "startDate": "2018-09-21T00:00:00+04:30", - "endDate": "2018-12-21T00:00:00+04:30" - }, - "value": { - "currency": "AFN", - "amount": 230865 - }, - "dateSigned": "2018-09-16T00:00:00+04:30", - "awardID": "MOBTA/1397/NCB/OPT/W.003", - "id": "MOBTA/1397/NCB/OPT/W.003" - } - ], - "ocid": "ocds-afalqw-001", - "id": "5c10b8c57e0a947f6b212f58-001", - "date": "2018-09-21T08:00:00+04:30", - "tag": [ - "contract", - "implementation" - ] - } - ] -} diff --git a/docs/examples/milestones/implementation_financial_milestones_partially_met.json b/docs/examples/milestones/implementation_financial_milestones_partially_met.json deleted file mode 100644 index 9618258c4..000000000 --- a/docs/examples/milestones/implementation_financial_milestones_partially_met.json +++ /dev/null @@ -1,75 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "contracts": [ - { - "status": "active", - "title": "School repairs and mantainance projects, Rahman Baba & Khushal Khan Khattak", - "implementation": { - "milestones": [ - { - "status": "notMet", - "title": "Payment for finish the exterior and interior walls", - "dueDate": "2018-10-10T00:00:00+04:30", - "dateModified": "2018-10-06T11:59:09+04:30", - "type": "payment", - "id": "20653payment", - "value": { - "amount": 76955, - "currency": "AFN" - } - }, - { - "status": "met", - "title": "Finish the exterior and interior walls", - "dueDate": "2018-10-05T00:00:00+04:30", - "dateMet": "2018-10-05T00:00:00+04:30", - "dateModified": "2018-10-06T11:59:09+04:30", - "type": "delivery", - "id": "20653Delivery" - }, - { - "status": "notMet", - "title": "Payment for repair of the electric system", - "dueDate": "2018-10-31T00:00:00+04:30", - "dateModified": "2018-10-06T11:59:09+04:30", - "type": "payment", - "id": "20654payment", - "value": { - "amount": 40000, - "currency": "AFN" - } - }, - { - "status": "notMet", - "title": "Repair of the electric system", - "dueDate": "2018-10-28T00:00:00+04:30", - "dateModified": "2018-10-06T11:59:09+04:30", - "type": "delivery", - "id": "20654Delivery" - } - ] - }, - "period": { - "startDate": "2018-09-21T00:00:00+04:30", - "endDate": "2018-12-21T00:00:00+04:30" - }, - "value": { - "currency": "AFN", - "amount": 230865 - }, - "dateSigned": "2018-09-16T00:00:00+04:30", - "awardID": "MOBTA/1397/NCB/OPT/W.003", - "id": "MOBTA/1397/NCB/OPT/W.003" - } - ], - "ocid": "ocds-afalqw-001", - "id": "5c10b8c57e0a947f6b212f58-002", - "date": "2018-10-06T11:59:09+04:30", - "tag": [ - "implementationUpdate" - ] - } - ] -} diff --git a/docs/examples/milestones/implementation_financial_milestones_transaction.json b/docs/examples/milestones/implementation_financial_milestones_transaction.json deleted file mode 100644 index 51f131c70..000000000 --- a/docs/examples/milestones/implementation_financial_milestones_transaction.json +++ /dev/null @@ -1,129 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "contracts": [ - { - "status": "active", - "title": "School repairs and mantainance projects, Rahman Baba & Khushal Khan Khattak", - "implementation": { - "milestones": [ - { - "status": "met", - "title": "Payment for finish the exterior and interior walls", - "dueDate": "2018-10-10T00:00:00+04:30", - "dateMet": "2018-10-09T09:15:00+04:30", - "dateModified": "2018-10-10T16:48:09+04:30", - "type": "payment", - "id": "20653payment", - "value": { - "amount": 76955, - "currency": "AFN" - } - }, - { - "status": "met", - "title": "Finish the exterior and interior walls", - "dueDate": "2018-10-05T00:00:00+04:30", - "dateMet": "2018-10-05T17:30:00+04:30", - "dateModified": "2018-10-10T16:48:09+04:30", - "type": "delivery", - "id": "20653Delivery" - }, - { - "status": "notMet", - "title": "Payment for repair of the electric system", - "dueDate": "2018-10-31T00:00:00+04:30", - "dateModified": "2018-10-10T16:48:09+04:30", - "type": "payment", - "id": "20654payment", - "value": { - "amount": 40000, - "currency": "AFN" - } - }, - { - "status": "notMet", - "title": "Repair of the electric system", - "dueDate": "2018-10-28T00:00:00+04:30", - "dateModified": "2018-10-10T16:48:09+04:30", - "type": "delivery", - "id": "20654Delivery" - } - ], - "transactions": [ - { - "id": "20653", - "date": "2018-10-09T09:15:00+04:30", - "value": { - "amount": 76955, - "currency": "AFN" - }, - "payer": { - "id": "AF-COA-20", - "name": "Ministry of Finance" - }, - "payee": { - "id": "AF-TIN-9000321217", - "name": "Primus Construction Company" - }, - "relatedImplementationMilestone": { - "id": "20653payment", - "title": "Payment for finish the exterior and interior walls" - } - } - ] - }, - "period": { - "startDate": "2018-09-21T00:00:00+04:30", - "endDate": "2018-12-21T00:00:00+04:30" - }, - "value": { - "currency": "AFN", - "amount": 230865 - }, - "dateSigned": "2018-09-16T00:00:00+04:30", - "awardID": "MOBTA/1397/NCB/OPT/W.003", - "id": "MOBTA/1397/NCB/OPT/W.003" - } - ], - "ocid": "ocds-afalqw-001", - "id": "5c10b8c57e0a947f6b212f58-003", - "date": "2018-10-10T16:48:09+04:30", - "tag": [ - "implementationUpdate" - ], - "parties": [ - { - "identifier": { - "scheme": "AF-TIN", - "id": "9000321217", - "legalName": "شرکت ساختمانی پریموس" - }, - "id": "AF-TIN-9000321217", - "roles": [ - "payee", - "supplier" - ], - "name": "Primus Construction Company" - }, - { - "name": "Ministry of Finance", - "roles": [ - "payer" - ], - "address": { - "country": "AF", - "region": "مرکز" - }, - "identifier": { - "scheme": "AF-COA", - "id": "20", - "legalName": "وزارت مالیه" - }, - "id": "AF-COA-20" - } - ] - } - ] -} diff --git a/docs/examples/milestones/implementation_milestones_met.json b/docs/examples/milestones/implementation_milestones_met.json deleted file mode 100644 index e21079de7..000000000 --- a/docs/examples/milestones/implementation_milestones_met.json +++ /dev/null @@ -1,61 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-06-implementation-milestones-2", - "date": "2018-03-31T09:30:00Z", - "tag": [ - "implementationUpdate" - ], - "parties": [ - { - "identifier": { - "scheme": "GB-LAC", - "id": "E09000003", - "legalName": "London Borough of Barnet" - }, - "name": "London Borough of Barnet", - "roles": [ - "buyer" - ], - "id": "GB-LAC-E09000003" - } - ], - "buyer": { - "id": "GB-LAC-E09000003", - "name": "London Borough of Barnet" - }, - "contracts": [ - { - "id": "ocds-213czf-000-00001-contract-01", - "awardID": "ocds-213czf-000-00001-award-01", - "title": "Contract to build new cycle lanes in the centre of town.", - "implementation": { - "milestones": [ - { - "id": "1", - "title": "project started", - "type": "delivery", - "code": "commencement", - "dueDate": "2018-03-19T00:00:00Z", - "status": "met", - "dateMet": "2018-03-31T00:00:00Z", - "dateModified": "2018-03-31T00:00:00Z" - }, - { - "id": "2", - "title": "project completed", - "type": "delivery", - "code": "completion", - "dueDate": "2018-12-31T00:00:00Z", - "status": "notMet", - "dateModified": "2018-03-31T00:00:00Z" - } - ] - } - } - ] - } - ] -} diff --git a/docs/examples/milestones/implementation_milestones_partially_met.json b/docs/examples/milestones/implementation_milestones_partially_met.json deleted file mode 100644 index de02e4f41..000000000 --- a/docs/examples/milestones/implementation_milestones_partially_met.json +++ /dev/null @@ -1,63 +0,0 @@ -{ - "version": "1.1", - "extensions": [], - "releases": [ - { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-06-implementation-milestones-3", - "date": "2018-12-24T09:30:00Z", - "tag": [ - "implementationUpdate" - ], - "parties": [ - { - "identifier": { - "scheme": "GB-LAC", - "id": "E09000003", - "legalName": "London Borough of Barnet" - }, - "name": "London Borough of Barnet", - "roles": [ - "buyer" - ], - "id": "GB-LAC-E09000003" - } - ], - "buyer": { - "id": "GB-LAC-E09000003", - "name": "London Borough of Barnet" - }, - "contracts": [ - { - "id": "ocds-213czf-000-00001-contract-01", - "awardID": "ocds-213czf-000-00001-award-01", - "title": "Contract to build new cycle lanes in the centre of town.", - "implementation": { - "milestones": [ - { - "id": "1", - "title": "project started", - "type": "delivery", - "code": "commencement", - "dueDate": "2018-03-19T00:00:00Z", - "status": "met", - "dateMet": "2018-03-31T00:00:00Z", - "dateModified": "2018-03-31T00:00:00Z" - }, - { - "id": "2", - "title": "project completed", - "type": "delivery", - "code": "completion", - "dueDate": "2018-12-31T00:00:00Z", - "status": "met", - "dateMet": "2018-12-24T00:00:00Z", - "dateModified": "2018-12-24T00:00:00Z" - } - ] - } - } - ] - } - ] -} diff --git a/docs/examples/milestones/implementation_milestones_scheduled.json b/docs/examples/milestones/implementation_milestones_scheduled.json deleted file mode 100644 index db4fe3696..000000000 --- a/docs/examples/milestones/implementation_milestones_scheduled.json +++ /dev/null @@ -1,58 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-06-implementation-milestones-1", - "date": "2018-01-05T09:30:00Z", - "tag": [ - "implementation" - ], - "parties": [ - { - "identifier": { - "scheme": "GB-LAC", - "id": "E09000003", - "legalName": "London Borough of Barnet" - }, - "name": "London Borough of Barnet", - "roles": [ - "buyer" - ], - "id": "GB-LAC-E09000003" - } - ], - "buyer": { - "id": "GB-LAC-E09000003", - "name": "London Borough of Barnet" - }, - "contracts": [ - { - "id": "ocds-213czf-000-00001-contract-01", - "awardID": "ocds-213czf-000-00001-award-01", - "title": "Contract to build new cycle lanes in the centre of town.", - "implementation": { - "milestones": [ - { - "id": "1", - "title": "project started", - "type": "delivery", - "code": "commencement", - "dueDate": "2018-03-19T00:00:00Z", - "status": "scheduled" - }, - { - "id": "2", - "title": "project completed", - "type": "delivery", - "code": "completion", - "dueDate": "2018-12-31T00:00:00Z", - "status": "scheduled" - } - ] - } - } - ] - } - ] -} diff --git a/docs/examples/milestones/payment_milestones.json b/docs/examples/milestones/payment_milestones.json new file mode 100644 index 000000000..3b8d1f372 --- /dev/null +++ b/docs/examples/milestones/payment_milestones.json @@ -0,0 +1,79 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "implementation" + ], + "contracts": [ + { + "id": "1", + "title": "Cycle lane construction", + "implementation": { + "milestones": [ + { + "id": "1", + "title": "Payment for project completion", + "type": "payment", + "dueDate": "2024-06-30T00:00:00Z", + "status": "scheduled", + "value": { + "amount": 100000, + "currency": "USD" + } + } + ] + } + } + ] + }, + { + "ocid": "ocds-213czf-0000", + "id": "2", + "date": "2024-07-15T00:00:00Z", + "tag": [ + "implementationUpdate" + ], + "contracts": [ + { + "id": "1", + "title": "Cycle lane construction", + "implementation": { + "milestones": [ + { + "id": "1", + "title": "Payment for project completion", + "type": "payment", + "dueDate": "2024-06-30T00:00:00Z", + "status": "met", + "value": { + "amount": 100000, + "currency": "USD" + }, + "dateMet": "2024-07-15T00:00:00Z", + "dateModified": "2024-07-15T00:00:00Z" + } + ], + "transactions": [ + { + "id": "1", + "date": "2024-07-15T00:00:00Z", + "value": { + "amount": 95000, + "currency": "USD" + }, + "relatedImplementationMilestone": { + "id": "1", + "title": "Payment for project completion" + } + } + ] + } + } + ] + } + ] +} diff --git a/docs/examples/milestones/planning-tender-milestones-2.json b/docs/examples/milestones/planning-tender-milestones-2.json deleted file mode 100644 index 8713937fa..000000000 --- a/docs/examples/milestones/planning-tender-milestones-2.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-04-tender", - "date": "2016-10-23T09:30:00Z", - "tag": [ - "tender" - ], - "tender": { - "id": "001002003", - "status": "active", - "milestones": [ - { - "id": 1, - "title": "Tender notice publication estimation from procurement plan", - "status": "met", - "type": "preProcurement", - "dueDate": "2016-10-21T15:00:00Z", - "dateMet": "2016-10-23T15:00:00Z" - } - ] - } - } - ] -} diff --git a/docs/examples/milestones/planning_milestone.json b/docs/examples/milestones/planning_milestone.json deleted file mode 100644 index 003af1503..000000000 --- a/docs/examples/milestones/planning_milestone.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-04-planning", - "date": "2016-09-10T09:30:00Z", - "tag": [ - "planning" - ], - "planning": { - "budget": { - "id": "1.02.1.02.01.01.25.24.5.2.3.49.06", - "amount": { - "amount": 30000000, - "currency": "IDR" - }, - "project": "Konsultan Pengawas", - "description": "APBD" - }, - "milestones": [ - { - "id": "1", - "type": "preProcurement", - "title": "Budget Plan", - "status": "scheduled", - "dueDate": "2016-09-19T23:29:03Z", - "description": "Rencana Pengadaan Road Map" - } - ] - } - } - ] -} diff --git a/docs/examples/milestones/planning_milestones.json b/docs/examples/milestones/planning_milestones.json new file mode 100644 index 000000000..896e5c39a --- /dev/null +++ b/docs/examples/milestones/planning_milestones.json @@ -0,0 +1,24 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "planning" + ], + "planning": { + "milestones": [ + { + "id": "1", + "type": "preProcurement", + "title": "Budget approval", + "status": "scheduled", + "dueDate": "2024-03-01T00:00:00Z" + } + ] + } + } + ] +} diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index c2de80451..f63fa6752 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -12,7 +12,7 @@ The planning milestones block is used for two types of milestones: * Key events in the planning process, for example, the preparation of an environmental impact assessment, the approval to proceed with a project, or the date of a public consultation. * Anticipated milestones during the contract implementation stage, for example, the date by which goods delivery of the goods is required. -If during the planning process you have information about tender process milestones, then you +If during the planning process you have information about tender process milestones, then you ought to populate the tender milestones block instead. ## Tender @@ -31,7 +31,7 @@ The contract milestones block is used to describe: The contract implementation milestones block is used to describe: * Any events related to the delivery of the contract, for example, the agreed date by which goods will be delivered. -The nature of the milestone is indicated by the [milestone type codelist](../../schema/codelists.md#milestone-type), for example, to distinguish between milestones that relate to bid submission and others that relate to contract implementation. +The nature of a milestone is indicated by the [milestone type codelist](../../schema/codelists.md#milestone-type), for example, a milestone representing a draft bid submission deadline would use the 'procurement' code, whilst a milestone representing the date by which goods are to be provided would use the 'delivery' code. At the point of contract signature, a comparison between `tender/milestones` and `contract/implementation/milestones` with a `milestone/type` of 'delivery' or 'reporting' should reveal how the negotiated contract differs from what was set out at tender time. @@ -41,102 +41,71 @@ To represent a planned payment, add a `Milestone`, set its `.type` to 'payment' ## Worked examples -The following worked examples show how to use milestones in different scenarios. +The following worked examples show how milestones are modelled. ### Planning milestones -The example below includes a planning release with details of a planned procurement, including the date the budget plan is expected to be ready. +A buyer publishes information about a new planning process, including the date the budget is expected to be approved. -The date the budget plan is expected to be ready is represented using a milestone in `planning/milestones` with `.type` is set to 'preProcurement' because the milestone relates to the planning process. `.dueDate` is set to the date and `.status` is set to 'scheduled'. +Because the approval relates to a planning process, it is modelled as a milestone in `planning.milestones` with `.type` set to 'preProcurement'. `.dueDate` is set to the expected date of the approval and `.status` is set to 'scheduled' because the approval has not yet occurred. -```{jsoninclude} ../../examples/milestones/planning_milestone.json -:jsonpointer: -:expand: releases, planning, milestones -:title: planning +```{jsoninclude} ../../examples/milestones/planning_milestones.json +:jsonpointer: /releases/0 +:expand: planning, milestones ``` -### Contract implementation milestones +### Delivery milestones -The following worked examples show how to use milestones in contract implementation releases +This worked example shows how delivery milestones are modelled. -#### Project data +#### Implementation release -This worked example shows how to use milestones to model the planned and actual start and finish dates for a construction project. +A buyer publishes the expected completion date of a construction project. -The example below includes three OCDS releases: +Because the completion date relates to contract delivery, it is modelled as a milestone in `contracts.implementation.milestones` with `.type` set to 'delivery'. `.dueDate` is set to the expected completion date and `.status` is set to 'scheduled' because the project is not yet complete. -* An implementation release which includes the scheduled start and end dates for the project. -* An implementation update release with the actual start date of the project -* An implementation update release with the actual end date of the project +The publisher defines their own value for the milestone's `.code` so that they can filter and compare completion dates across different contracts. -In the award release: - -* The scheduled start and end dates for the project are represented using milestones in `contracts/implementation/milestones` with `.type` set to 'delivery' because they relate to the delivery of the contract. The dates are provided in `.dueDate` and `.status` is set to 'scheduled'. -* The publisher has defined their own values for the `.code` field so they can filter and compare start and end date milestones across different contracts. - -In the first implementation update release, which is published after the project starts but before it completes: -* In the project commencement milestone, `.dateMet` is set to the actual start date and `.status` is set to 'met'. `.dateModified` is set to the date the milestone was updated. -* In the project completion milestone, `.status` is set to 'notMet' since the project is not yet complete and `.dateModified` is set to the date the milestone was updated. - -Users can compare the project commencement milestone's `.dueDate` and `.dateMet` fields to determine if the project started on time. Users can also compare the project completion milestone's `.dueDate` and `.dateModified` fields to determine whether the `.status` has been updated since the scheduled completion date. - -In the second implementation update release, which is published after the project completes: -* In the project completion milestone, `.dateMet` is set to the actual completion date for the project and `.status` is set to 'met'. - -```{jsoninclude} ../../examples/milestones/implementation_milestones_scheduled.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones -:title: implementation +```{jsoninclude} ../../examples/milestones/delivery_milestones.json +:jsonpointer: /releases/0 +:expand: tag, contracts, implementation, milestones ``` -```{jsoninclude} ../../examples/milestones/implementation_milestones_partially_met.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones -:title: implementation-update-1 -``` +#### Implementation update release -```{jsoninclude} ../../examples/milestones/implementation_milestones_met.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones -:title: implementation-update-2 -``` +The buyer publishes the actual completion date of the construction project. -#### Delivery and payment data +The milestone's `.dateMet` is set to the actual completion date, `.status` is set to 'met' and `.dateModified` is set to the date the milestone was updated. -This example shows how milestones can be used to keep track of delivery and payment data in a contracting process. +Users can compare the milestone's `.dueDate` and `.dateMet` to determine whether the project was completed on time. -The example below includes three OCDS releases: +```{jsoninclude} ../../examples/milestones/delivery_milestones.json +:jsonpointer: /releases/1 +:expand: tag, contracts, implementation, milestones +``` -* An implementation release with contract information including scheduled implementation milestones and planned payments. -* An implementation update release with the actual date the milestone was reached. -* An implementation update release with payment information +### Payment milestones -In the implementation release: +This example shows how payment milestones are modelled. -* Milestones have been set for the delivery and payment of goods, services and works related to the project. Contract information is released along with the implementation milestones. +#### Implementation release -In the first implementation update release: +A buyer publishes the expected date and value of the payment for the completion of a construction project. -* The milestone ("Finish the exterior and interior walls") has been met, so the `status` field is set to 'met' and the relevant dates are added to the `dateMet` and `dateModified` fields. +```{jsoninclude} ../../examples/milestones/payment_milestones.json +:jsonpointer: /releases/0 +:expand: tag, contracts, implementation, milestones +``` -In the second implementation update release: +#### Implementation update release -* The construction company has received payment for the work done so far, so the milestone for the wall restoration with type 'payment' is updated. A new `transaction` is disclosed, with the amount paid to the company. The [transaction-related milestones extension](https://extensions.open-contracting.org/en/extensions/transaction_milestones/master/) is used to link the transaction to the milestone. +The buyer publishes the actual date and value of the payment for completion of the project. -```{jsoninclude} ../../examples/milestones/implementation_financial_milestones_not_met.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones -:title: implementation -``` +The milestone is updated to reflect that the payment has been made: it's `.status` is set to `.met` and the `.dateMet` and `.dateModified` fields are populated. A transaction is added to `contracts.implementation.transactions` with the actual date and value of the payment. The [transaction-related milestones extension](https://extensions.open-contracting.org/en/extensions/transaction_milestones/master/) is used to link the transaction to the milestone. -```{jsoninclude} ../../examples/milestones/implementation_financial_milestones_partially_met.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones -:title: implementation-update-1 -``` +Users can compare the milestone's `.dueDate` and `.value` to the transaction's `.date` and `.value` to determine whether the payment was made on time and for the expected amount. -```{jsoninclude} ../../examples/milestones/implementation_financial_milestones_transaction.json -:jsonpointer: -:expand: releases, contracts, implementation, milestones, transactions -:title: implementation-update-2 +```{jsoninclude} ../../examples/milestones/payment_milestones.json +:jsonpointer: /releases/1 +:expand: tag, contracts, implementation, milestones, transactions ``` diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 22cfafe62..f0710b458 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -580,7 +580,7 @@ Milestone information can be included in the [planning](#planning), [tender](#te The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` either updated, or re-confirmed. ```{seealso} -[How to represent planned payments](../guidance/map/milestones.md#delivery-and-payment-data) +[How to represent planned payments](../guidance/map/milestones.md#payment-milestones) ``` For delivery milestones, if there is a time frame for delivery, use `.dueAfterDate` for the start date and `.dueDate` for the end date. From 81d271f9aafaaf9014c3afd10b3da3afc97ef85f Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 18:27:01 +1300 Subject: [PATCH 09/36] docs/guidance/map/organization_reference.md: Remove worked example --- .../organization_reference.json | 46 +++++++++++++++++++ docs/guidance/map.md | 1 - docs/guidance/map/organization_reference.md | 26 ----------- docs/schema/reference.md | 11 ++--- 4 files changed, 50 insertions(+), 34 deletions(-) create mode 100644 docs/examples/release_schema_reference/organization_reference.json delete mode 100644 docs/guidance/map/organization_reference.md diff --git a/docs/examples/release_schema_reference/organization_reference.json b/docs/examples/release_schema_reference/organization_reference.json new file mode 100644 index 000000000..c65eb59c4 --- /dev/null +++ b/docs/examples/release_schema_reference/organization_reference.json @@ -0,0 +1,46 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2011-01-10T09:30:00Z", + "tag": [ + "contract" + ], + "buyer": { + "id": "GB-LAC-E09000003", + "name": "London Borough of Barnet" + }, + "parties": [ + { + "name": "London Borough of Barnet", + "id": "GB-LAC-E09000003", + "identifier": { + "id": "E09000003", + "legalName": "London Borough of Barnet", + "scheme": "GB-LAC", + "uri": "http://www.barnet.gov.uk/" + }, + "address": { + "country": "GB", + "locality": "London", + "postalCode": "N11 1NP", + "region": "London", + "streetAddress": "4, North London Business Park, Oakleigh Rd S" + }, + "contactPoint": { + "email": "procurement-team@example.com", + "faxNumber": "01234 345 345", + "name": "Procurement Team", + "telephone": "01234 345 346", + "url": "http://example.com/contact/" + }, + "roles": [ + "buyer" + ] + } + ] + } + ] +} diff --git a/docs/guidance/map.md b/docs/guidance/map.md index e7ed21e3b..39ed1d9d9 100644 --- a/docs/guidance/map.md +++ b/docs/guidance/map.md @@ -107,7 +107,6 @@ map/electronic_catalogues map/amendments map/milestones map/buyers_suppliers -map/organization_reference map/organization_identifiers map/organization_personal_identifiers map/organizational_units diff --git a/docs/guidance/map/organization_reference.md b/docs/guidance/map/organization_reference.md deleted file mode 100644 index 9578bd169..000000000 --- a/docs/guidance/map/organization_reference.md +++ /dev/null @@ -1,26 +0,0 @@ -```{workedexample} Organization references -:tags: parties,organization_reference -``` - -# Organization references - -Many organizations can be involved in the lifecycle of contracting and planning processes. Sometimes the same organization can have multiple roles. For example, an organization can first be a tenderer and then become a supplier. - -To avoid data repetition, OCDS 1.1 introduced a top-level parties array, where the detailed information about all the organizations and other participants involved in a particular contracting (or planning) process is declared. - -When a **reference** is needed to an entry in the parties array, e.g. to provide a link between a `tenderer` declared in the `tender` section and its organization details, use an `OrganizationReference` object. This object includes just the `name` and `id` of the organization, instead of repeating all its relevant data again. - -## Worked Example - -In the example below: - -* An Organization is declared in the `parties` array with the `id` *GB-COH-09506232* and `name` *Open Data Services*. Information related to its legal `identifier` and `contactPoint` is also disclosed here. -* An OrganizationReference object is used in the `tenderers` and `suppliers` array to reference *Open Data Services*, **without** duplicating the organization's detailed information. -* If a user looks at the `tenderers` block and wants to contact *Open Data Services*, then the user has to search for the `id` *GB-COH-09506232* in the `parties` array. -* The same needs to be applied to each `OrganizationReference` instance. - -```{jsoninclude} ../../examples/organizations/organization_reference.json -:jsonpointer: -:expand: releases, parties, tender, tenderers, awards, suppliers -:title: organizationReference -``` diff --git a/docs/schema/reference.md b/docs/schema/reference.md index f0710b458..49364cda2 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -373,16 +373,13 @@ An organization reference consists of two main components: ````{admonition} Example :class: hint -```{jsoninclude} ../examples/release_schema_reference/release_package.json -:jsonpointer: /releases/0/buyer -:title: organizationReference +```{jsoninclude} ../examples/release_schema_reference/organization_reference.json +:jsonpointer: /releases/0 +:include_only: buyer, parties +:expand: buyer, parties ``` ```` -```{workedexamplelist} The following worked examples are available for organization reference -:tag: organization_reference -``` - ### Organization See the [parties](#parties) section. From 356de458e3085cb7afb22ba79e6f7b9aabaa804b Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 29 Feb 2024 18:31:36 +1300 Subject: [PATCH 10/36] docs/examples/award_decisions: Indent examples --- docs/examples/award_decisions/multi_award.json | 2 +- docs/examples/award_decisions/single_award.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/examples/award_decisions/multi_award.json b/docs/examples/award_decisions/multi_award.json index 59619b4fc..6ae17c1ec 100644 --- a/docs/examples/award_decisions/multi_award.json +++ b/docs/examples/award_decisions/multi_award.json @@ -50,7 +50,7 @@ "roles": [ "supplier" ] - } + } ] } ] diff --git a/docs/examples/award_decisions/single_award.json b/docs/examples/award_decisions/single_award.json index 593e66d63..a81aec1f1 100644 --- a/docs/examples/award_decisions/single_award.json +++ b/docs/examples/award_decisions/single_award.json @@ -41,7 +41,7 @@ "roles": [ "supplier" ] - } + } ] } ] From 3c424b05d20b8ede4757d0233b6fa2da363b88ac Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 11 Mar 2024 13:08:31 +1300 Subject: [PATCH 11/36] docs/guidance/map/framework_agreements: Update example 1 --- .../frameworks/closed_single_award.json | 59 ++++--------------- .../frameworks/closed_single_first_stage.json | 36 ++++------- .../frameworks/closed_single_supplier.json | 15 +++-- docs/guidance/map/framework_agreements.md | 57 +++++++++--------- 4 files changed, 56 insertions(+), 111 deletions(-) diff --git a/docs/examples/frameworks/closed_single_award.json b/docs/examples/frameworks/closed_single_award.json index 39061c6ec..77d4e5b84 100644 --- a/docs/examples/frameworks/closed_single_award.json +++ b/docs/examples/frameworks/closed_single_award.json @@ -5,32 +5,27 @@ ], "releases": [ { - "ocid": "ocds-r6ebe6-95f19d21-d066-4931-a431-071211033960", + "ocid": "ocds-213czf-0001", "id": "1", "date": "2020-10-01T00:00:00Z", "tag": [ "award" ], "buyer": { - "name": "The Common Services Agency (more commonly known as NHS National Services Scotland) (‘NSS’)", - "id": "GB-NHS-YA7" + "name": "NHS National Services Scotland", + "id": "1" }, "parties": [ { - "name": "The Common Services Agency (more commonly known as NHS National Services Scotland) (‘NSS’)", - "id": "GB-NHS-YA7", - "identifier": { - "scheme": "GB-NHS", - "id": "YA7" - }, + "name": "NHS National Services Scotland", + "id": "1", "roles": [ - "buyer", - "procuringEntity" + "buyer" ] }, { "name": "Movianto UK", - "id": "1", + "id": "2", "roles": [ "supplier" ] @@ -38,49 +33,17 @@ ], "tender": { "id": "1", - "competitive": false, - "procuringEntity": { - "name": "The Common Services Agency (more commonly known as NHS National Services Scotland) (‘NSS’)", - "id": "GB-NHS-YA7" - } + "competitive": false }, "awards": [ { "id": "1", - "value": { - "amount": 10000, - "currency": "GBP" - }, - "contractPeriod": { - "startDate": "2020-10-01T00:00:00Z", - "endDate": "2020-10-31T00:00:00Z" - }, + "title": "Receipt and storage of 10 pallets of seasonal flu vaccine", "suppliers": [ { "name": "Movianto UK", "id": "1" } - ], - "items": [ - { - "id": "38204627", - "description": "Receipt and storage of 10 pallets of seasonal flu vaccine", - "quantity": 10, - "unit": { - "name": "pallet/unit load", - "id": "D97", - "scheme": "UNCEFACT", - "value": { - "amount": 1000, - "currency": "GBP" - } - }, - "classification": { - "id": "63120000", - "scheme": "CPV", - "description": "Storage and warehousing services" - } - } ] } ], @@ -92,8 +55,8 @@ ], "title": "Storage and Distribution of Seasonal Influenza Vaccine", "scheme": "ocid", - "identifier": "ocds-r6ebe6-9af22e2f-5307-4e98-bff6-1ebffbff343d", - "uri": "https://example.org/records/ocds-r6ebe6-9af22e2f-5307-4e98-bff6-1ebffbff343d" + "identifier": "ocds-213czf-0000", + "uri": "https://example.org/records/ocds-213czf-0000" } ] } diff --git a/docs/examples/frameworks/closed_single_first_stage.json b/docs/examples/frameworks/closed_single_first_stage.json index 435e5eec9..791244fd2 100644 --- a/docs/examples/frameworks/closed_single_first_stage.json +++ b/docs/examples/frameworks/closed_single_first_stage.json @@ -5,48 +5,32 @@ ], "releases": [ { - "ocid": "ocds-r6ebe6-9af22e2f-5307-4e98-bff6-1ebffbff343d", - "id": "2019/S 197-478648", + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2019-10-09T00:00:00Z", "tag": [ "tender" ], "parties": [ { - "name": "The Common Services Agency (more commonly known as NHS National Services Scotland) (‘NSS’)", - "id": "GB-NHS-YA7", - "identifier": { - "scheme": "GB-NHS", - "id": "YA7" - }, + "name": "NHS National Services Scotland", + "id": "1", "roles": [ "buyer" ] } ], "buyer": { - "name": "The Common Services Agency (more commonly known as NHS National Services Scotland) (‘NSS’)", - "id": "GB-NHS-YA7" + "name": "NHS National Services Scotland", + "id": "1" }, "tender": { - "techniques": { - "hasFrameworkAgreement": true - }, - "id": "NP45719", + "id": "1", "title": "Storage and Distribution of Seasonal Influenza Vaccine", - "description": "This framework agreement is for the receipt, storage and distribution of seasonal influenza vaccines to GP practices, social care premises, vaccine holding centres and community pharmacies across NHS Scotland.", - "status": "active", - "procurementMethod": "open", - "value": { - "amount": 1120000, - "currency": "GBP" - }, + "procurementMethod": "selective", "expressionOfInterestDeadline": "2019-11-13T12:00:00Z", - "awardPeriod": { - "startDate": "2019-11-13T12:00:00Z" - }, - "contractPeriod": { - "durationInDays": 720 + "techniques": { + "hasFrameworkAgreement": true } } } diff --git a/docs/examples/frameworks/closed_single_supplier.json b/docs/examples/frameworks/closed_single_supplier.json index c5640ee13..c85876853 100644 --- a/docs/examples/frameworks/closed_single_supplier.json +++ b/docs/examples/frameworks/closed_single_supplier.json @@ -2,8 +2,8 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-r6ebe6-9af22e2f-5307-4e98-bff6-1ebffbff343d", - "id": "2020/S 110-268595", + "ocid": "ocds-213czf-0000", + "id": "2", "date": "2020-06-05T00:00:00Z", "tag": [ "award" @@ -11,24 +11,23 @@ "parties": [ { "name": "Movianto UK", - "id": "1", + "id": "2", "roles": [ "supplier" ] } ], "tender": { - "id": "NP45719", + "id": "1", "status": "complete" }, "awards": [ { - "id": "NP45719", - "status": "active", + "id": "1", "suppliers": [ { - "name": "Movianto UK", - "id": "1" + "id": "2", + "name": "Movianto UK" } ] } diff --git a/docs/guidance/map/framework_agreements.md b/docs/guidance/map/framework_agreements.md index 421b50fc3..c76bf5c3d 100644 --- a/docs/guidance/map/framework_agreements.md +++ b/docs/guidance/map/framework_agreements.md @@ -158,66 +158,65 @@ The following examples show how to model two framework agreements, covering a ra ### Example 1: Closed framework agreement with single buyer, single supplier and without second-stage competition -NHS National Services Scotland (NSS) wants to establish a framework agreement for the receipt, storage and distribution of seasonal influenza vaccines to general practitioner practices, social care premises, vaccine holding centres and community pharmacies across NHS Scotland. +NHS National Services Scotland establishes a closed, single-buyer, single-supplier framework agreement for storage and distribution of a seasonal influenza vaccine. #### Invitation to participate in the first stage of a framework agreement procedure -NSS issues a [contract notice](https://ted.europa.eu/udl?uri=TED:NOTICE:478648-2019:TEXT:EN:HTML) (tender notice), inviting potential suppliers to participate in the framework agreement. The tender notice specifies that the framework agreement is with a single operator. The framework agreement is not open, since the tender notice does not specify that the procurement involves the setting up of a dynamic purchasing system. The framework agreement is for a single buyer, since the tender notice specifies only one contracting authority. +The buyer invites potential suppliers to participate in the framework agreement. -The notice is modelled as an OCDS release with a `tag` of 'tender' and the following properties: +An OCDS release describes the opportunity: -* The techniques extension is declared in the package metadata. -* Since this contracting process is for the set-up of a framework agreement, `tender.techniques.hasFrameworkAgreement` is set to `true`. -* Since any supplier is able to submit a response to the invitation to participate, `tender.procurementMethod` is set to 'selective'. -* Since the framework agreement is closed, `tender.expressionOfInterestDeadline` is set to the deadline for responses to the invitation to participate. -* Since there is only one buyer, `buyer` is set to reference the buyer's object in the `parties` array. +* `tag` is set to `["tender"]` because this is the first release about the opportunity +* The release describes the set up of a framework agreement so the techniques extension is declared in the package metadata and `tender.techniques.hasFrameworkAgreement` is set to `true` +* Only qualified suppliers can respond to the invitation so `tender.procurementMethod` is set to 'selective' +* The framework agreement is closed so `tender.expressionOfInterestDeadline` is set to the deadline for responses to the invitation +* There is only one buyer so `buyer` is set to reference the buyer's object in the `parties` array ```{jsoninclude} ../../examples/frameworks/closed_single_first_stage.json :jsonpointer: -:expand: extensions, releases, tender, buyer, parties, roles -:title: First Stage +:expand: extensions, releases, buyer, tender ``` #### First-stage selection and addition of a supplier to the framework agreement -NSS issues a [contract award notice](https://ted.europa.eu/udl?uri=TED:NOTICE:268595-2020:TEXT:EN:HTML&src=0) to announce that the framework agreement has been concluded with a single supplier, Movianto UK. +The buyer concludes the framework agreement with a single supplier. -The notice is modelled as an OCDS release with the same `ocid` as the previous release, a `tag` of 'award', and the following properties: +An OCDS release describes the selection and addition of the supplier to the framework agreement: -* Since no further suppliers will be added to the framework agreement, `tender.status` is set to 'complete'. -* An `Award` object is added to the `awards` array. +* `ocid` is set to the same value as the previous release because the release describes the first stage of the framework agreement +* `tag` is set `["award"]` because this the first release about the award +* `tender.status` is set to 'complete' because no further suppliers will be added to the framework agreement * An `Organization` object is added to the `parties` array with the supplier's details. -* An `OrganizationReference` object is added to award's `.suppliers` array to reference the supplier's object in the `parties` array. +* An `Award` object is added to the `awards` array with a reference to the supplier in `.suppliers` ```{jsoninclude} ../../examples/frameworks/closed_single_supplier.json :jsonpointer: -:expand: releases, tender, awards, suppliers, parties, roles -:title: Adding a supplier +:expand: releases, tag, tender, awards, suppliers ``` -The first stage of the framework agreement procedure is complete and NSS can now purchase services from the supplier. +The first stage of the framework agreement procedure is complete and the buyer can now purchase services from the supplier. #### Award of a procurement contract without second-stage competition -NSS uses the framework agreement to place an order for the supplier to receive and store ten pallets of seasonal flu vaccine. Under the terms of the agreement the cost for this service is £10,000. - -The order represents the award of a procurement contract at the second stage of the framework agreement procedure. +The buyer uses the framework agreement to place an order for the supplier to receive and store ten pallets of seasonal flu vaccine. The order represents the award of a procurement contract at the second stage of the framework agreement procedure. -Because there was no competition at the second stage, the new contracting process has only one release, with a `tag` of 'award'. The release has the following properties: +An OCDS release describes the order: -* A new `ocid` is used. -* The `relatedProcesses` section is populated with a reference to the contracting process for the first stage. -* A minimal `tender` section sets `tender.id` and sets `tender.competitive` to `false`. -* The `awards` section is populated with the award value, period and items. -* The `buyer`, `tender.procuringEntity`, `awards.suppliers` and `parties` fields are populated with the details of the buyer, procuring entity and supplier. +* `ocid` differs from releases describing the first stage of the procedure +* `tag` is set to `["award"]` because this is the first release describing the award. There is no 'tender' release because there is no competition at the second stage. +* `relatedProcesses` links to the contracting process for the first stage of the procedure +* `tender.competitive` is set to `false` because there is no competition at the second stage and the [Competitive](https://extensions.open-contracting.org/en/extensions/competitive/master/) extension is declared in the package metadata +* `tender.id` is set to the same value as `awards.id` +* The `awards` section is populated with the details of the order +* The `buyer`, `awards.suppliers` and `parties` fields are populated with the details of the buyer and and supplier ```{jsoninclude} ../../examples/frameworks/closed_single_award.json :jsonpointer: -:expand: releases, tender, buyer, procuringEntity, awards, suppliers, parties, roles, relatedProcesses, relationship +:expand: extension, releases, buyer, tender, awards, suppliers, relatedProcesses, relationship :title: Award of a procurement contract ``` -Each additional purchase made under the framework agreement is represented by a new contracting process with a new `ocid`. +Each subsequent purchase made under the framework agreement would be represented by a new contracting process with a new `ocid`. ### Example 2: Open framework agreement with multiple buyers, with multiple suppliers and with second-stage competition From 5064d39fdbf9c36c4ae999585ca1da2e78600392 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 11 Mar 2024 15:43:31 +1300 Subject: [PATCH 12/36] docs/guidance/map/framework_agreements: Update second example --- .../frameworks/open_multiple_award.json | 52 ++---------- .../frameworks/open_multiple_first_stage.json | 46 +++------- .../open_multiple_second_stage.json | 56 +++--------- .../frameworks/open_multiple_supplier.json | 37 ++------ docs/guidance/map/framework_agreements.md | 85 +++++++++---------- 5 files changed, 78 insertions(+), 198 deletions(-) diff --git a/docs/examples/frameworks/open_multiple_award.json b/docs/examples/frameworks/open_multiple_award.json index f8f5de3a2..f458038c7 100644 --- a/docs/examples/frameworks/open_multiple_award.json +++ b/docs/examples/frameworks/open_multiple_award.json @@ -2,8 +2,8 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-70d2nz-54705", - "id": "54705-contract-1-2020-08-20T16:30:52Z", + "ocid": "ocds-213czf-0003", + "id": "2", "date": "2020-08-30T16:30:52Z", "tag": [ "award" @@ -11,66 +11,24 @@ "parties": [ { "name": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "id": "CL-MP-1394484", - "identifier": { - "id": "76364678", - "legalName": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "scheme": "CL-RUT" - }, + "id": "2", "roles": [ "supplier" ] } ], "tender": { - "id": "547054", + "id": "1", "status": "complete" }, "awards": [ { "id": "1", - "value": { - "amount": 280000, - "currency": "CLP" - }, "suppliers": [ { "name": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "id": "CL-MP-1394484" + "id": "2" } - ], - "items": [ - { - "id": "38204627", - "description": "Lápiz pasta", - "classification": { - "id": "38204627", - "description": "Lápiz pasta", - "scheme": "UNSPSC" - }, - "quantity": 200, - "unit": { - "value": { - "amount": 1400, - "currency": "CLP" - } - } - } - ] - } - ], - "relatedProcesses": [ - { - "id": "1", - "relationship": [ - "framework" - ], - "title": "CM Articulos de Escritorio y Papeleria", - "scheme": "ocid", - "identifier": "ocds-70d2nz-2239-4-LP14", - "uri": "https://example.org/records/ocds-70d2nz-2239-4-LP14", - "relatedLots": [ - "1" ] } ] diff --git a/docs/examples/frameworks/open_multiple_first_stage.json b/docs/examples/frameworks/open_multiple_first_stage.json index f8ac78123..6f40dc0de 100644 --- a/docs/examples/frameworks/open_multiple_first_stage.json +++ b/docs/examples/frameworks/open_multiple_first_stage.json @@ -5,66 +5,46 @@ ], "releases": [ { - "ocid": "ocds-70d2nz-2239-4-LP14", - "id": "2239-4-LP14", + "ocid": "ocds-213czf-0002", + "id": "1", "date": "2014-08-27T16:30:52Z", "tag": [ "tender" ], "parties": [ { - "name": "Dirección de Compras y Contratación Pública | Dirección de Compras y Contratación Pública", - "id": "CL-MP-749218", - "identifier": { - "id": "608080007", - "legalName": "Dirección de Compras y Contratación Pública", - "scheme": "CL-RUT" - }, + "name": "Chile Compra", + "id": "1", "roles": [ "procuringEntity" ] }, { - "name": "Biblioteca del Congreso Nacional | Biblioteca del Congreso Nacional", - "id": "CL-MP-3015", - "identifier": { - "id": "602030008", - "legalName": "Biblioteca del Congreso Nacional", - "scheme": "CL-RUT" - }, + "name": "Biblioteca del Congreso Nacional", + "id": "2", "roles": [ "buyer" ] }, { - "name": "Servicio Local de Educación Pública Puerto Cordillera | Servicio Local de Educación Pública Puerto Cordillera", - "id": "CL-MP-1002588", - "identifier": { - "id": "619993209", - "legalName": "Servicio Local de Educación Pública Puerto Cordill", - "scheme": "CL-RUT" - }, + "name": "Servicio Local de Educación Pública Puerto Cordillera", + "id": "3", "roles": [ "buyer" ] } ], "tender": { - "techniques": { - "hasFrameworkAgreement": true - }, - "id": "2239-4-LP14", + "id": "1", "title": "CM de Artículos de Escritorio y Papelería", - "status": "active", "procuringEntity": { - "name": "Dirección de Compras y Contratación Pública | Dirección de Compras y Contratación Pública", - "id": "CL-MP-749218" + "name": "Chile Compra", + "id": "1" }, "procurementMethod": "selective", "expressionOfInterestDeadline": "2020-08-27T15:00:00Z", - "contractPeriod": { - "startDate": "2005-01-19T15:30:00Z", - "endDate": "2020-08-27T15:00:00Z" + "techniques": { + "hasFrameworkAgreement": true }, "lots": [ { diff --git a/docs/examples/frameworks/open_multiple_second_stage.json b/docs/examples/frameworks/open_multiple_second_stage.json index 87f0ec25f..5f59a27a4 100644 --- a/docs/examples/frameworks/open_multiple_second_stage.json +++ b/docs/examples/frameworks/open_multiple_second_stage.json @@ -5,62 +5,30 @@ ], "releases": [ { - "ocid": "ocds-70d2nz-54705", - "id": "54705-2020-08-20T16:30:52Z", + "ocid": "ocds-213czf-0003", + "id": "1", "date": "2020-08-20T16:30:52Z", "tag": [ "tender" ], "parties": [ { - "name": "Servicio Local de Educación Pública Puerto Cordillera | Servicio Local de Educación Pública Puerto Cordillera", - "id": "CL-MP-1002588", - "identifier": { - "id": "619993209", - "legalName": "Servicio Local de Educación Pública Puerto Cordill", - "scheme": "CL-RUT" - }, + "name": "Servicio Local de Educación Pública Puerto Cordillera", + "id": "1", "roles": [ - "buyer", - "procuringEntity" + "buyer" ] } ], "buyer": { - "name": "Servicio Local de Educación Pública Puerto Cordillera | Servicio Local de Educación Pública Puerto Cordillera", - "id": "CL-MP-1002588" + "name": "Servicio Local de Educación Pública Puerto Cordillera", + "id": "1" }, "tender": { - "id": "547054", - "title": "Artículos de Escritorio y Papelería", + "id": "1", + "title": "Lápiz pasta", "status": "active", - "competitive": true, - "procuringEntity": { - "name": "Servicio Local de Educación Pública Puerto Cordillera | Servicio Local de Educación Pública Puerto Cordillera", - "id": "CL-MP-1002588" - }, - "tenderPeriod": { - "startDate": "2020-08-31T16:32:25Z", - "endDate": "2020-09-14T15:00:00Z" - }, - "items": [ - { - "id": "38204627", - "description": "Lápiz pasta", - "classification": { - "id": "38204627", - "description": "Lápiz pasta", - "scheme": "UNSPSC" - }, - "quantity": 200, - "unit": { - "value": { - "amount": 1305, - "currency": "CLP" - } - } - } - ] + "competitive": true }, "relatedProcesses": [ { @@ -70,8 +38,8 @@ ], "title": "CM Articulos de Escritorio y Papeleria", "scheme": "ocid", - "identifier": "ocds-70d2nz-2239-4-LP14", - "uri": "https://example.org/records/ocds-70d2nz-2239-4-LP14", + "identifier": "ocds-213czf-0002", + "uri": "https://example.org/records/ocds-213czf-0002", "relatedLots": [ "1" ] diff --git a/docs/examples/frameworks/open_multiple_supplier.json b/docs/examples/frameworks/open_multiple_supplier.json index 711cebf6c..5cf91e7c2 100644 --- a/docs/examples/frameworks/open_multiple_supplier.json +++ b/docs/examples/frameworks/open_multiple_supplier.json @@ -2,8 +2,8 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-70d2nz-2239-4-LP14", - "id": "28224fe3-8603354", + "ocid": "ocds-213czf-0002", + "id": "2", "date": "2014-12-17T16:33:32Z", "tag": [ "award" @@ -11,24 +11,14 @@ "parties": [ { "name": "RODRIGO ALEJANDRO VIDAL CAMPOS", - "id": "CL-MP-1214480", - "identifier": { - "id": " 12124463", - "legalName": "RODRIGO ALEJANDRO VIDAL CAMPOS", - "scheme": "CL-RUT" - }, + "id": "4", "roles": [ "supplier" ] }, { "name": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "id": "CL-MP-1394484", - "identifier": { - "id": "76364678", - "legalName": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "scheme": "CL-RUT" - }, + "id": "5", "roles": [ "supplier" ] @@ -36,29 +26,16 @@ ], "awards": [ { - "id": "8603354", + "id": "1", "title": "Convenio Marco de Artículos de Escritorio y Papelería", - "status": "active", - "date": "2014-12-17T16:33:32Z", "suppliers": [ { "name": "RODRIGO ALEJANDRO VIDAL CAMPOS", - "id": "CL-MP-1214480" + "id": "4" }, { "name": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", - "id": "CL-MP-1394484" - } - ], - "items": [ - { - "id": "38204627", - "description": "Lápiz pasta", - "classification": { - "id": "38204627", - "description": "Lápiz pasta", - "scheme": "UNSPSC" - } + "id": "5" } ] } diff --git a/docs/guidance/map/framework_agreements.md b/docs/guidance/map/framework_agreements.md index c76bf5c3d..1dc98fc3e 100644 --- a/docs/guidance/map/framework_agreements.md +++ b/docs/guidance/map/framework_agreements.md @@ -156,9 +156,9 @@ The following examples show how to model two framework agreements, covering a ra 1. A closed framework agreement established for a single buyer, with a single supplier and **without** second-stage competition 2. A open framework agreement established for multiple buyers, with multiple suppliers and **with** second-stage competition -### Example 1: Closed framework agreement with single buyer, single supplier and without second-stage competition +### Example 1: A closed, single-buyer, single-supplier framework agreement without second-stage competition -NHS National Services Scotland establishes a closed, single-buyer, single-supplier framework agreement for storage and distribution of a seasonal influenza vaccine. +NHS National Services Scotland establishes a closed, single-buyer, single-supplier framework agreement without second-stage competition for storage and distribution of a seasonal influenza vaccine. #### Invitation to participate in the first stage of a framework agreement procedure @@ -183,7 +183,7 @@ The buyer concludes the framework agreement with a single supplier. An OCDS release describes the selection and addition of the supplier to the framework agreement: -* `ocid` is set to the same value as the previous release because the release describes the first stage of the framework agreement +* `ocid` is set to the same value as the previous release because both releases relate to the first stage of the framework agreement * `tag` is set `["award"]` because this the first release about the award * `tender.status` is set to 'complete' because no further suppliers will be added to the framework agreement * An `Organization` object is added to the `parties` array with the supplier's details. @@ -202,7 +202,7 @@ The buyer uses the framework agreement to place an order for the supplier to rec An OCDS release describes the order: -* `ocid` differs from releases describing the first stage of the procedure +* `ocid` differs from releases describing the first stage of the procedure because the second stage of the procedure is modelled as a separate contracting process * `tag` is set to `["award"]` because this is the first release describing the award. There is no 'tender' release because there is no competition at the second stage. * `relatedProcesses` links to the contracting process for the first stage of the procedure * `tender.competitive` is set to `false` because there is no competition at the second stage and the [Competitive](https://extensions.open-contracting.org/en/extensions/competitive/master/) extension is declared in the package metadata @@ -218,81 +218,78 @@ An OCDS release describes the order: Each subsequent purchase made under the framework agreement would be represented by a new contracting process with a new `ocid`. -### Example 2: Open framework agreement with multiple buyers, with multiple suppliers and with second-stage competition +### Example 2: A multi-buyer, multi-supplier framework agreement with second-stage competition -The National Procurement Agency in Chile (Chile Compra) wants to establish a framework agreement for the purchase of office supplies, including paper and stationery items for the different public entities across Chile. +Dirección de Compras y Contratación Pública (Chile Compra) establishes a multi-buyer, multi-supplier framework agreement with second-stage competition for the purchase of office supplies by two buyers: Biblioteca del Congreso Nacional and Servicio Local de Educación Pública Puerto Cordillera. The framework agreement is split into two lots. #### Invitation to participate in the first stage of a framework agreement procedure -Chile Compra publishes a tender notice inviting suppliers to participate in the framework agreement. The tender notice specifies that multiple suppliers can join the framework agreement. The framework agreement is open, since all the framework agreements in Chile involve the setting up of a dynamic purchasing system. The framework agreement is for multiple buyers, since the tender notice specifies two contracting authorities. The tender notice describes two lots. +Chile Compra invites suppliers to participate in the framework agreement. -The notice is modelled as an OCDS release with a `tag` of 'tender' and the following properties: +An OCDS release describes the opportunity: -* The techniques extension is declared in the package metadata. -* Since this contracting process is for the set-up of a framework agreement, `tender.techniques.hasFrameworkAgreement` is set to `true`. -* Since any supplier is able to submit a response to the invitation to participate, `tender.procurementMethod` is set to 'selective'. -* Since the framework agreement is open, `tender.expressionOfInterestDeadline` is set to the last date that new suppliers can be added, which in this case matches the last date of the framework agreement. -* Since there are two buyers, the 'buyer' object is not set, and the buyers are declared in the `parties` array. -* Since Chile Compra is the organization that manages the contracting process, `tender.procuringEntity` is set to reference Chile Compra's object in the `parties` array. +* `tag` is set to `["tender"]` because this is the first release about the opportunity +* The release describes the set up of a framework agreement so the techniques extension is declared in the package metadata and `tender.techniques.hasFrameworkAgreement` is set to `true` +* Only qualified suppliers can respond to the invitation so `tender.procurementMethod` is set to 'selective' +* The framework agreement is open (a dynamic purchasing system) so `tender.expressionOfInterestDeadline` is set to the last date that new suppliers can be added +* There are two buyers so `buyer` is omitted and both buyers are listed in `parties` +* `tender.procuringEntity` is set to the organization that manages the contracting process: Chile Compra +* The lots are listed in `lots` ```{jsoninclude} ../../examples/frameworks/open_multiple_first_stage.json :jsonpointer: -:expand: extensions, releases, tender, procuringEntity, parties, roles -:title: First Stage +:expand: extensions, releases, tag, tender, procuringEntity, parties, roles ``` #### First-stage selection and addition of suppliers to the framework agreement -Chile Compra issues an award notice to announce that the framework agreement has been awarded to two suppliers: Rodrigo Alejandro Vidal Campos and Comercializadora e Importadora Grupo RAVC SPA. +Chile Compra concludes the framework agreement with two suppliers: Rodrigo Alejandro Vidal Campos and Comercializadora e Importadora Grupo RAVC SPA. -The notice is modelled as an OCDS release with the same `ocid` as the previous release, a `tag` of 'award', and the following properties: +An OCDS release describes the selection and addition of the supplier to the framework agreement: -* Since other suppliers are still able to submit a request to participate in the framework agreement, no change is made to `tender.status`. -* An `Award` object is added to the `awards` array. -* An `Organization` object is added to the `parties` array for each supplier with its details. -* An `OrganizationReference` object is added to the award's `.suppliers` array for each supplier to reference its object in the `parties` array. +* `ocid` is set to the same value as the previous release because both releases relate to the first stage of the framework agreement +* `tag` is set `["award"]` because this the first release about the award +* `tender.status` remains 'active' because further suppliers can be added to the framework agreement +* An `Organization` object is added to the `parties` array for each supplier +* An `Award` object is added to the `awards` array with references to the suppliers in `.suppliers` ```{jsoninclude} ../../examples/frameworks/open_multiple_supplier.json :jsonpointer: -:expand: releases, awards, suppliers, parties, roles -:title: Adding a supplier +:expand: releases, tag, awards, suppliers, parties, roles ``` -The framework is now established, and both buyers can now purchase items from the suppliers. +The framework is now established and both buyers can purchase items from the suppliers. #### Invitation to participate in a second-stage competition -Servicio Local de Educación Pública Puerto Cordillera publishes a tender notice, inviting suppliers on the framework agreement to bid to supply 200 pencils. This represents an invitation to participate in a second-stage competition, related to a lot described in the first-stage tender notice. +A buyer invites suppliers on the framework agreement to participate in a second-stage competition to supply goods included in the first lot. -The release has the following properties: +An OCDS release describes the invitation: -* A new `ocid` is used. -* The `relatedProcesses` section is populated with a reference to the contracting process for the first stage, including the relevant lot in `.relatedLots`. -* The `tag` is set to 'tender'. -* The tender section includes details about the competition, and `tender.competitive` is set to `true`. -* Since this new contracting process has a single buyer, the `buyer` is set to Servicio Local de Educación Pública Puerto Cordillera. +* `ocid` differs from releases describing the first stage of the procedure because the second stage of the procedure is modelled as a separate contracting process +* `tag` is set to `["tender"]` because this is the first release describing the competition +* `relatedProcesses` links to the contracting process for the first stage of the procedure and the lot to which the competition is related +* `tender.competitive` is set to `true` because there is competition at the second stage and the [Competitive](https://extensions.open-contracting.org/en/extensions/competitive/master/) extension is declared in the package metadata +* Since this new contracting process has a single buyer, `buyer` is populated accordingly ```{jsoninclude} ../../examples/frameworks/open_multiple_second_stage.json :jsonpointer: -:expand: releases, tag, tender, buyer, parties, roles, relatedProcesses, relationship -:title: Second Stage +:expand: releases, tag, tender, buyer, parties, roles, relatedProcesses, relationship, relatedLots ``` #### Award of a procurement contract resulting from a second-stage competition -Following the invitation to participate in the second-stage competition, Servicio Local de Educación Pública Puerto Cordillera awards a contract to Comercializadora e Importadora Grupo RAVC SPA. +The buyer awards a contract to a supplier. -The release has the following properties: +An OCDS release describes the award: -* The same `ocid` as the invitation to participate in the second-stage competition is used. -* The `relatedProcesses` section is populated with a reference to the contracting process for the first stage, including the relevant lot in `.relatedLots`. -* The `tag` is set to 'award'. -* The `tender.status` is updated to 'complete'. -* The `awards` section is populated with the award value, period and items. -* The `awards.suppliers` and `parties` fields are populated with the details of the supplier. +* `ocid` is set to the same value as release describing the invitation to participate in the second-stage competition +* `tag` is set to `["award"]` because this is the first release describing the award. +* `tender.status` is set to complete +* The `awards` section is populated with the details of the award +* The `awards.suppliers` and `parties` fields are populated with the details of the supplier ```{jsoninclude} ../../examples/frameworks/open_multiple_award.json :jsonpointer: -:expand: releases, tag, tender, procuringEntity, awards, suppliers, parties, roles, relatedProcesses, relationship -:title: Award of a procurement contract +:expand: releases, tag, tender, awards, suppliers, parties, roles ``` From cbaa1548067e59b9425071deffa341ad3699ac7f Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 11 Mar 2024 15:53:43 +1300 Subject: [PATCH 13/36] docs/guidance/map/framework_agreements: Split multi-award supplier --- docs/examples/frameworks/open_multiple_supplier.json | 8 +++++++- docs/guidance/map/framework_agreements.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/examples/frameworks/open_multiple_supplier.json b/docs/examples/frameworks/open_multiple_supplier.json index 5cf91e7c2..a101bee22 100644 --- a/docs/examples/frameworks/open_multiple_supplier.json +++ b/docs/examples/frameworks/open_multiple_supplier.json @@ -32,7 +32,13 @@ { "name": "RODRIGO ALEJANDRO VIDAL CAMPOS", "id": "4" - }, + } + ] + }, + { + "id": "2", + "title": "Convenio Marco de Artículos de Escritorio y Papelería", + "suppliers": [ { "name": "COMERCIALIZADORA E IMPORTADORA GRUPO RAVC SPA", "id": "5" diff --git a/docs/guidance/map/framework_agreements.md b/docs/guidance/map/framework_agreements.md index 1dc98fc3e..2e9d9731e 100644 --- a/docs/guidance/map/framework_agreements.md +++ b/docs/guidance/map/framework_agreements.md @@ -251,7 +251,7 @@ An OCDS release describes the selection and addition of the supplier to the fram * `tag` is set `["award"]` because this the first release about the award * `tender.status` remains 'active' because further suppliers can be added to the framework agreement * An `Organization` object is added to the `parties` array for each supplier -* An `Award` object is added to the `awards` array with references to the suppliers in `.suppliers` +* An `Award` object is added to the `awards` array for each supplier with a reference to the supplier in `.suppliers` ```{jsoninclude} ../../examples/frameworks/open_multiple_supplier.json :jsonpointer: From 12337144a6ec68456a80a5ffcb41413360d423ba Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 13:12:45 +1300 Subject: [PATCH 14/36] docs/guidance/map/pre-qualification.md: Make examples minimal --- .../pre-qualification_paraguay.json | 15 ++++--------- .../pre-qualification_tender.json | 19 ++++------------- .../pre-selection_tender.json | 21 +++++-------------- docs/guidance/map/pre-qualification.md | 15 ++++++------- 4 files changed, 19 insertions(+), 51 deletions(-) diff --git a/docs/examples/pre-qualification/pre-qualification_paraguay.json b/docs/examples/pre-qualification/pre-qualification_paraguay.json index 03450fc0c..57061f6e3 100644 --- a/docs/examples/pre-qualification/pre-qualification_paraguay.json +++ b/docs/examples/pre-qualification/pre-qualification_paraguay.json @@ -2,22 +2,15 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-213czf-2017-528", - "id": "2017-528-01", + "ocid": "ocds-213czf-0002", + "id": "1", "date": "2017-06-14T00:00:00-04:00", "tag": [ "tender" ], - "buyer": { - "name": "Ministerio de Obras Públicas y Comunicaciones (MOPC)" - }, "tender": { - "id": "2017-528", - "title": "LLAMADO UEP ? MOPC N° 22/2017 EXPRESION DE INTERES SERVICIOS DE CONSULTORÍA PARA LA ELABORACIÓN DE ESTUDIOS DE FACTIBILIDAD Y DISEÑO FINAL DE INGENIERÍA DE TRAMOS DE CAMINOS VECINALES EN LOS DEPARTAMENTO DE SAN PEDRO, CAAGUAZU, CANINDEYU, CAAZAPA Y GUAIRA", - "expressionOfInterestDeadline": "2017-06-21T10:00:00-04:00", - "tenderPeriod": { - "endDate": "2017-06-29T10:00:00-04:00" - }, + "id": "1", + "title": "Road construction in San Pedro and Caaguazu", "procurementMethod": "selective" } } diff --git a/docs/examples/pre-qualification/pre-qualification_tender.json b/docs/examples/pre-qualification/pre-qualification_tender.json index ebfcfea10..8f5575fb4 100644 --- a/docs/examples/pre-qualification/pre-qualification_tender.json +++ b/docs/examples/pre-qualification/pre-qualification_tender.json @@ -2,26 +2,15 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-213czf-b744019f-c7c3-4f78-8811-1845d0c18c8d", - "id": "2019/S 040-090873", + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2019-02-22T00:00:00Z", "tag": [ "tender" ], - "buyer": { - "name": "Bank of England" - }, "tender": { - "id": "2019/S 040-090873", - "description": "The Bank of England has a requirement for FM (M&E, security and cleaning) services at its site in Roehampton, SW15 5JQ.", - "classification": { - "scheme": "CPV", - "id": "71300000" - }, - "expressionOfInterestDeadline": "2019-03-05T12:00:00Z", - "tenderPeriod": { - "endDate": "2019-04-05T12:00:00Z" - }, + "id": "1", + "title": "Office supplies", "procurementMethod": "selective" } } diff --git a/docs/examples/pre-qualification/pre-selection_tender.json b/docs/examples/pre-qualification/pre-selection_tender.json index 9174b0bfb..b60aa00f0 100644 --- a/docs/examples/pre-qualification/pre-selection_tender.json +++ b/docs/examples/pre-qualification/pre-selection_tender.json @@ -5,31 +5,20 @@ ], "releases": [ { - "ocid": "ocds-213czf-2d4d7408-4743-4d04-b57d-18d5ecdd8ef8", - "id": "2020/S 014-028681", + "ocid": "ocds-213czf-0001", + "id": "1", "date": "2020-01-17T00:00:00Z", "tag": [ "tender" ], - "buyer": { - "name": "National Nuclear Laboratory" - }, "tender": { - "id": "2020/S 014-028681", - "description": "The NNL Preston Laboratory is located on the Springfields Fuels Ltd (SFL) site near Preston, Lancashire. NNL are carrying out their regulatory responsibilities as a Dutyholder to protect nuclear materials (NM) and other radioactive materials (ORM) from theft and sabotage by malicious threats. The facility operates under an approved nuclear site security plan in accordance with the Nuclear Industries Security Regulations (2003). This project is to further upgrade the physical protection system (PPS) arrangements at Preston Laboratory.", - "classification": { - "scheme": "CPV", - "id": "35120000" - }, - "expressionOfInterestDeadline": "2020-02-10T12:00:00Z", - "tenderPeriod": { - "endDate": "2020-02-17T12:00:00Z" - }, + "id": "1", + "title": "IT equipment", "procurementMethod": "selective", "selectionCriteria": { "criteria": [ { - "description": "The SSQ will be utilised. Responses to the SSQ will either be pass/fail, scored or for information only. The five top scoring suppliers will be taken through to award stage, following successful completion of a security audit. Further details can be found within the procurement documentation." + "description": "Suppliers must complete the Supplier Selection Questionnaire (SSQ). The five top scoring suppliers will be invited to submit a proposal. For more information, refer to the procurement documents." } ] } diff --git a/docs/guidance/map/pre-qualification.md b/docs/guidance/map/pre-qualification.md index 7e02c3597..6c03e3d96 100644 --- a/docs/guidance/map/pre-qualification.md +++ b/docs/guidance/map/pre-qualification.md @@ -111,13 +111,12 @@ The `tender` section is also used to disclose information about the procedure us ## Example: Pre-qualification -The Bank of England issues a [restricted procedure contract notice](https://ted.europa.eu/udl?uri=TED:NOTICE:90873-2019:TEXT:EN:HTML) to invite potential suppliers to pre-qualify for a tender to provide facilities management services. +A buyer in the European Union invites potential suppliers to participate in a restricted procedure for the purchase of office supplies. -The notice represents the initiation of the contracting process, so it is modelled using the `tender` section in OCDS: +The invitation represents the initiation of the contracting process, so it is modelled using the `tender` section in OCDS. ```{jsoninclude} ../../examples/pre-qualification/pre-qualification_tender.json :jsonpointer: /releases/0/tender -:title: Tender section ``` Any potential supplier can submit a request to take part in the first stage, but only qualified potential suppliers will be invited to submit a bid for the contract. Therefore, `tender.procurementMethod` is set to 'selective'. @@ -130,20 +129,19 @@ Contact the [Data Support Team](../../support/index) if you want to disclose thi ## Example: Pre-selection -The National Nuclear Laboratory issues a [restricted procedure contract notice](https://ted.europa.eu/udl?uri=TED:NOTICE:28681-2020:TEXT:EN:HTML&src=0) to invite potential suppliers to pre-qualify for a project to update its physical security system arrangements. +A buyer in the European Union invites potential suppliers to participate in a restricted procedure for the purchase of IT equipment. -The notice represents the initiation of the contracting process, so it is modelled using the `tender` section in OCDS. +The invitation represents the initiation of the contracting process, so it is modelled using the `tender` section in OCDS. -The procuring entity will invite a maximum of 5 qualified potential suppliers to submit a bid at the next stage, so `tender.procurementMethod` is set to 'selective'. The [selectionCriteria extension](https://extensions.open-contracting.org/en/extensions/selectionCriteria/master/) is used to disclose the criteria for choosing which potential suppliers to invite proposals from. +The buyer will invite a maximum of 5 qualified potential suppliers to submit a bid at the next stage, so `tender.procurementMethod` is set to 'selective'. The [selectionCriteria extension](https://extensions.open-contracting.org/en/extensions/selectionCriteria/master/) is used to disclose the criteria for choosing which potential suppliers to invite proposals from. ```{jsoninclude} ../../examples/pre-qualification/pre-selection_tender.json :jsonpointer: /releases/0/tender -:title: Tender section ``` ## Example: Pre-qualification in Paraguay -The Ministry of Public Works and Communications issues an [invitation for potential suppliers to pre-qualify for two tenders for road construction in different neighbourhoods](https://contrataciones.gov.py/licitaciones/convocatoria/338229-servicios-consultoria-estudios-factibilidad-diseno-final-ingenieria-tramos-caminos-1/precalificacion.html). Each tender will reuse the list of pre-qualified potential suppliers established as a result of this first procedure. +The buyer in Paraguay invites potential suppliers to pre-qualify for two road construction tenders. Each tender will reuse the list of pre-qualified potential suppliers established as a result of the pre-qualification procedure. The invitation represents the initiation of a contracting process to establish a list of pre-qualified potential suppliers, so it is modelled using the `tender` section in OCDS. @@ -151,7 +149,6 @@ Only qualified potential suppliers will be invited to bid in subsequent tenders ```{jsoninclude} ../../examples/pre-qualification/pre-qualification_paraguay.json :jsonpointer: /releases/0/tender -:title: Tender section ``` ```{note} From 42bcaeb9f2a460a35c74c447833c5437e1a8c9e8 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 13:57:42 +1300 Subject: [PATCH 15/36] docs/guidance/map/organization_identifiers.md: Make example minimal, copy-edit --- docs/examples/organizations/identifiers.json | 102 ++---------------- docs/guidance/map/organization_identifiers.md | 19 +++- 2 files changed, 22 insertions(+), 99 deletions(-) diff --git a/docs/examples/organizations/identifiers.json b/docs/examples/organizations/identifiers.json index e6dcc29a5..c365ffed0 100644 --- a/docs/examples/organizations/identifiers.json +++ b/docs/examples/organizations/identifiers.json @@ -3,117 +3,29 @@ "extensions": [], "releases": [ { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-04-award", + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2010-05-10T09:30:00Z", "tag": [ "award" ], "parties": [ { - "identifier": { - "scheme": "GB-LAC", - "id": "E09000003", - "legalName": "London Borough of Barnet" - }, - "name": "London Borough of Barnet", - "address": { - "streetAddress": "4, North London Business Park, Oakleigh Rd S", - "locality": "London", - "region": "London", - "postalCode": "N11 1NP", - "country": "GB" - }, - "contactPoint": { - "name": "Procurement Team", - "email": "procurement-team@example.com", - "telephone": "01234 345 346", - "faxNumber": "01234 345 345", - "url": "http://www.barnet.gov.uk/" - }, - "roles": [ - "buyer" - ], - "id": "GB-LAC-E09000003" - }, - { + "id": "GB-COH-04336774", + "name": "IBM", "identifier": { "scheme": "GB-COH", - "id": "04336774", - "legalName": "IBM LP LIMITED", - "uri": "http://data.companieshouse.gov.uk/doc/company/04336774" + "id": "04336774" }, "additionalIdentifiers": [ { "scheme": "GB-VAT", - "id": "GB107328000", - "legalName": "IBM UK LIMITED" + "id": "GB107328000" } ], - "name": "IBM", - "address": { - "streetAddress": "76, 78 Upper Ground", - "locality": "London", - "region": "London", - "postalCode": "SE1 9PZ", - "country": "GB" - }, - "contactPoint": { - "name": "Contracts Team", - "email": "ibm_crc@uk.ibm.com", - "telephone": "+44 (0) 370 909 9997" - }, "roles": [ "supplier" - ], - "id": "GB-COH-04336774" - } - ], - "buyer": { - "id": "GB-LAC-E09000003", - "name": "London Borough of Barnet" - }, - "awards": [ - { - "id": "ocds-213czf-000-00001-award-01", - "title": "Licenses for analytical software", - "description": "IBM has been awarded for licenses for the SPSS Statistics software", - "status": "pending", - "date": "2010-05-10T09:30:00Z", - "value": { - "amount": 1096000, - "currency": "GBP" - }, - "suppliers": [ - { - "id": "GB-COH-04336774", - "name": "IBM" - } - ], - "items": [ - { - "id": "0001", - "description": "string", - "classification": { - "scheme": "CPV", - "id": "48218000", - "description": "Construction work for highways", - "uri": "http://cpv.data.ac.uk/code-48218000" - }, - "quantity": 8, - "unit": { - "name": "unit", - "value": { - "amount": 137000, - "currency": "GBP" - } - } - } - ], - "contractPeriod": { - "startDate": "2010-07-01T00:00:00Z", - "endDate": "2011-07-31T23:59:00Z" - } + ] } ] } diff --git a/docs/guidance/map/organization_identifiers.md b/docs/guidance/map/organization_identifiers.md index cf6346b0c..44d62b919 100644 --- a/docs/guidance/map/organization_identifiers.md +++ b/docs/guidance/map/organization_identifiers.md @@ -15,14 +15,25 @@ If you choose not to register an organization list with org-id.guide, you ought ## Worked example -The Government of the United Kingdom uses identifiers from [Companies House](https://www.gov.uk/government/organisations/companies-house) to identify suppliers. Companies House is assigned the "GB-COH" prefix in [org-id.guide](http://org-id.guide/list/GB-COH). IBM has been assigned the company number "04336774" by the Companies House. The globally unique organization identifier for IBM can be disclosed in the organization's `identifier` section, as below: +A publisher in the United Kingdom collects [Companies House](https://www.gov.uk/government/organisations/companies-house) numbers as its primary organization identifiers for suppliers. + +A buyer awards a contract to IBM. In IBM's entry in the `parties` array, `.identifier.scheme` is set to the org-id scheme prefix for Companies House ([GB-COH](http://org-id.guide/list/GB-COH)) and `.identifier.id` is set to IBM's Companies House number (04336774). ```{jsoninclude} ../../examples/organizations/identifiers.json -:jsonpointer: /releases/0/parties/1 -:expand: identifier, additionalIdentifiers +:jsonpointer: /releases/0/parties/0 +:expand: identifier ``` -The publisher collects an additional identifier, which is disclosed using the `additionalIdentifiers` array. This is the VAT identification number for the supplier. The VAT list is not described by org-id.guide, so the publisher followed the instructions in the [org-id meta-data guide](http://docs.org-id.guide/en/latest/metadata/#assigning-a-code) to assign the "GB-VAT" prefix. This prefix is composed of the two-letter country code ("GB") and a short abbreviation for the list ("VAT"). The publisher checked that this prefix was not in use by another list in org-id.guide. +The publisher also collects an additional identifier: A VAT identification number. + +The VAT identification number list is not described by org-id.guide so the publisher follows the [instructions](http://docs.org-id.guide/en/latest/metadata/#assigning-a-code) and assigns a new prefix: GB-VAT. The prefix is composed of the two-letter country code for the United Kingdom and an abbreviation of the list name. The publisher checks that the prefix is not already assigned in org-id.guide + +In IBM's entry in the `parties` array, `.additionalIdentifiers.scheme` is set to the new list prefix and `.additionalIdentifiers.id` is set to IBM's VAT identification number. + +```{jsoninclude} ../../examples/organizations/identifiers.json +:jsonpointer: /releases/0/parties/0 +:expand: additionalIdentifiers +``` ## Local IDs From 53827804e98ac53421c654237757a484dc17fe12 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 14:05:34 +1300 Subject: [PATCH 16/36] docs/guidance/map/organization_personal_identifiers.md: Make example minimal, copy-edit --- .../organizations/personal_identifier.json | 78 ++----------------- .../map/organization_personal_identifiers.md | 10 +-- 2 files changed, 11 insertions(+), 77 deletions(-) diff --git a/docs/examples/organizations/personal_identifier.json b/docs/examples/organizations/personal_identifier.json index dfd3a15ba..51c47427b 100644 --- a/docs/examples/organizations/personal_identifier.json +++ b/docs/examples/organizations/personal_identifier.json @@ -3,87 +3,25 @@ "extensions": [], "releases": [ { - "ocid": "ocds-213czf-000-00001", - "id": "ocds-213czf-000-00001-02-tender", + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2010-03-15T09:30:00Z", "tag": [ - "tender" + "award" ], "parties": [ { "id": "COL-IDCARD-1234567", "name": "VICTOR HUGO GONZALEZ PEREZ", - "roles": [ - "tenderer" - ], "identifier": { "id": "1234567", - "scheme": "COL-IDCARD", - "legalName": "VICTOR HUGO GONZALEZ PEREZ" + "scheme": "COL-IDCARD" }, - "contactPoint": { - "name": "VICTOR HUGO GONZALEZ PEREZ" - } + "roles": [ + "tenderer" + ] } - ], - "tender": { - "id": "ocds-213czf-000-00001-01-tender", - "title": "Planned cycle lane improvements", - "description": "Tenders solicited for work to build new cycle lanes in the centre of town.", - "status": "active", - "tenderers": [ - { - "id": "COL-IDCARD-1234567", - "name": "VICTOR HUGO GONZALEZ PEREZ" - } - ], - "items": [ - { - "id": "0001", - "description": "string", - "classification": { - "scheme": "CPV", - "id": "45233130", - "description": "Construction work for highways", - "uri": "http://cpv.data.ac.uk/code-45233130" - }, - "additionalClassifications": [ - { - "scheme": "CPV", - "id": "45233162-2", - "description": "Cycle path construction work", - "uri": "http://cpv.data.ac.uk/code-45233162.html" - } - ], - "quantity": 8, - "unit": { - "name": "Miles", - "value": { - "amount": 120000, - "currency": "GBP" - } - } - } - ], - "minValue": { - "amount": 600000, - "currency": "GBP" - }, - "value": { - "amount": 1100000, - "currency": "GBP" - }, - "procurementMethod": "open", - "procurementMethodRationale": "An open competitive tender is required by EU Rules", - "awardCriteria": "bestProposal", - "awardCriteriaDetails": "The best proposal, subject to value for money requirements, will be accepted.", - "submissionMethodDetails": "Submit through the online portal at http://example.com/submissions/ocds-213czf-000-00001-01/", - "enquiryPeriod": { - "startDate": "2010-03-01T09:00:00Z", - "endDate": "2010-03-14T17:30:00Z" - }, - "hasEnquiries": false - } + ] } ] } diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index 13d9399ef..ab142b26c 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -18,21 +18,17 @@ There are two components to an identifier in OCDS: * a code indicating the list or register from which the identifier is drawn (the `scheme`); and * the identifier itself (the `id`). -Follow the [guidance](https://standard.openownership.org/en/0.2.0/schema/guidance/identifiers.html#shared-identifiers) from the Beneficial Ownership Data Standard to construct a `scheme` value for the personal identifier: +Follow the [guidance](https://standard.openownership.org/en/0.2.0/schema/guidance/identifiers.html#shared-identifiers) from the Beneficial Ownership Data Standard to construct a `scheme` value for a personal identifier: > the scheme should have the pattern {JURISDICTION}-{TYPE} where JURISDICTION is an uppercase ISO 3166-1 alpha-3 country code and TYPE is one of PASSPORT, TAXID or IDCARD ## Worked example -In the example below: +A publisher in Colombia collects national ID card numbers as identifiers for natural persons who are tenderers or suppliers. -* A self-employed individual submits a bid for a tender in Colombia -* The individual is listed in the `parties` section with 'tenderer' in `.roles` -* The individual's ID card number is published in `.identifier.id` -* `.identifier.scheme` is constructed from the ISO 3166-1 alpha-3 country code for Colombia ('COL') and the type of the identifier ('IDCARD') +A self-employed individual submits a bid for an opportunity. The individual is listed in the `parties` section with 'tenderer' in `.roles`. `.identifier.id` is set to the individual's ID card number and `.identifier.scheme` is constructed from the ISO 3166-1 alpha-3 country code for Colombia ('COL') and the type of the identifier ('IDCARD'). ```{jsoninclude} ../../examples/organizations/personal_identifier.json :jsonpointer: :expand: releases, parties, identifier -:title: personal-identifiers ``` From 6e72c76f1c2cdb374f560ee9b7009c23f371069e Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 14:06:46 +1300 Subject: [PATCH 17/36] docs/guidance/map/organization_identifiers.md: Copy edit --- docs/guidance/map/organization_identifiers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guidance/map/organization_identifiers.md b/docs/guidance/map/organization_identifiers.md index 44d62b919..583143a58 100644 --- a/docs/guidance/map/organization_identifiers.md +++ b/docs/guidance/map/organization_identifiers.md @@ -17,11 +17,11 @@ If you choose not to register an organization list with org-id.guide, you ought A publisher in the United Kingdom collects [Companies House](https://www.gov.uk/government/organisations/companies-house) numbers as its primary organization identifiers for suppliers. -A buyer awards a contract to IBM. In IBM's entry in the `parties` array, `.identifier.scheme` is set to the org-id scheme prefix for Companies House ([GB-COH](http://org-id.guide/list/GB-COH)) and `.identifier.id` is set to IBM's Companies House number (04336774). +A buyer awards a contract to IBM. The supplier is listed in the `parties` array with 'supplier' in `.roles`. `.identifier.scheme` is set to the org-id scheme prefix for Companies House ([GB-COH](http://org-id.guide/list/GB-COH)) and `.identifier.id` is set to IBM's Companies House number (04336774). ```{jsoninclude} ../../examples/organizations/identifiers.json :jsonpointer: /releases/0/parties/0 -:expand: identifier +:expand: identifier, roles ``` The publisher also collects an additional identifier: A VAT identification number. From 2701a5cbe88ac1df882abcba20bdb255bf29be52 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 15:20:48 +1300 Subject: [PATCH 18/36] docs/guidance/map/organizational_units.md: Make examples minimal, copy edit --- ...nduras_organization_identifier_scheme.json | 74 +++--------- .../paraguay_organization_name.json | 108 +----------------- docs/guidance/map/organizational_units.md | 59 ++++++---- 3 files changed, 58 insertions(+), 183 deletions(-) diff --git a/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json b/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json index d121091e0..e9c5ffb82 100644 --- a/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json +++ b/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json @@ -2,29 +2,16 @@ "version": "1.1", "releases": [ { + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2011-02-23T12:59:31.133000-06:00", - "ocid": "ocds-lcuori-4LOxWG-139-2011-1", "tag": [ "planning" ], "parties": [ { + "id": "HN-ONCAE-H1-10001-102", "name": "Secretaría de Salud Pública - Hospital San Felipe", - "roles": [ - "buyer", - "procuringEntity" - ], - "address": { - "region": "Francisco Morazan", - "streetAddress": "Ave. Los Proceseres", - "locality": "Tegucigalpa", - "country": "HN" - }, - "contactPoint": { - "telephone": "236-5786", - "name": "Dr. Arnoldo Zelaya Rodríguez", - "faxNumber": "236-5786" - }, "identifier": { "scheme": "HN-ONCAE-H1", "id": "10001", @@ -37,46 +24,23 @@ "legalName": "Hospital San Felipe" } ], - "id": "HN-ONCAE-H1-10001" + "address": { + "streetAddress": "Ave. Los Proceseres", + "locality": "Tegucigalpa", + "region": "Francisco Morazan", + "country": "HN" + }, + "contactPoint": { + "name": "Dr. Arnoldo Zelaya Rodríguez", + "telephone": "236-5786", + "faxNumber": "236-5786" + }, + + "roles": [ + "buyer" + ] } - ], - "buyer": { - "id": "HN-ONCAE-H1-10001", - "name": "Secretaría de Salud Pública - Hospital San Felipe" - }, - "tender": { - "status": "planned", - "description": "SOLICITADO POR LA BODEGA DE VIVERES, PARA SER UTILIZADO EN LA ALIMENTACION DE PACIENTES INTERNOS Y EMPLEADOS DE ESTE CENTRO ASISTENCIAL, DURANTE EL 4to. TRIMESTRE DEL 2019", - "tenderPeriod": { - "startDate": "2011-02-23T12:59:00-06:00", - "endDate": "2011-02-28T12:59:00-06:00" - }, - "title": "139-2011", - "items": [ - { - "quantity": 150, - "description": "Huevos de gallina (cartones de 30 unidades)", - "classification": { - "scheme": "UNSPSC", - "id": "50131606", - "description": "Huevos frescos" - }, - "id": "1" - } - ], - "enquiryPeriod": { - "startDate": "2011-02-23T12:59:00-06:00", - "endDate": "2011-02-28T12:59:00-06:00" - }, - "procuringEntity": { - "id": "HN-ONCAE-H1-10001", - "name": "Secretaría de Salud Pública - Hospital San Felipe" - }, - "procurementMethod": "open", - "procurementMethodDetails": "Compra Menor", - "id": "4LOxWG-139-2011-1" - }, - "id": "ocds-lcuori-4LOxWG-139-2011-1/2" + ] } ] } diff --git a/docs/examples/organizations/organizational_units/paraguay_organization_name.json b/docs/examples/organizations/organizational_units/paraguay_organization_name.json index 8354c7388..dd066c77e 100644 --- a/docs/examples/organizations/organizational_units/paraguay_organization_name.json +++ b/docs/examples/organizations/organizational_units/paraguay_organization_name.json @@ -2,16 +2,12 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-03ad3f-373449-1", - "id": "ocds-03ad3f-373449-1/1", + "ocid": "ocds-213czf-0002", + "id": "1", "date": "2019-12-05T12:36:58-04:00", "tag": [ "planning" ], - "buyer": { - "id": "PY-RUC-80001180-5", - "name": "Facultad de Ciencias Médicas - Hospital de Clínicas" - }, "parties": [ { "id": "PY-RUC-80001180-5", @@ -22,104 +18,10 @@ "legalName": "FACULTAD DE CIENCIAS MEDICAS" }, "roles": [ - "buyer", - "procuringEntity", - "payer" - ], - "address": { - "streetAddress": "AVDA. MCAL LOPEZ ESQ. CORONEL CAZAL", - "locality": "San Lorenzo", - "region": "Central", - "country": "PY" - }, - "contactPoint": { - "name": "LIC. LIZ RAQUEL DUARTE QUINTANA", - "telephone": "+595 21 683.930 INT. 102", - "email": "uoc@med.una.py" - } - } - ], - "planning": { - "budget": { - "description": "Nombre de la Licitación ADQUISICION DE REACTIVOS E INSUMOS DE HEMOCENTRO Y UMT DEL HOSPITAL DE CLINICAS ? AD RERENDUM PRESUPUESTO 2020", - "amount": { - "currency": "PYG", - "amount": 950000000 - } + "buyer" + ] } - }, - "tender": { - "id": "359402", - "description": "ADQUISICION DE REACTIVOS E INSUMOS DE HEMOCENTRO Y UMT DEL HOSPITAL DE CLINICAS ? AD RERENDUM PRESUPUESTO 2020", - "status": "planned", - "procurementMethod": "open", - "mainProcurementCategory": "goods", - "procuringEntity": { - "id": "PY-RUC-80001180-5", - "name": "Facultad de Ciencias Médicas - Hospital de Clínicas" - }, - "value": { - "amount": 895351000, - "currency": "PYG" - }, - "tenderPeriod": { - "startDate": "2019-01-13T08:00:00-04:00", - "endDate": "2019-01-28T11:00:00-04:00" - }, - "items": [ - { - "id": "41116105", - "description": "Anti A Monoclonal", - "quantity": 110, - "unit": { - "name": "Unidad", - "value": { - "amount": 44100, - "currency": "PYG" - } - }, - "classification": { - "scheme": "UNSPSC", - "id": "41116105", - "description": "Reactivos o soluciones quimicos" - } - }, - { - "id": "41116002", - "description": "REACTIVO PARA HIV", - "quantity": 11500, - "unit": { - "name": "Unidad", - "value": { - "amount": 27000, - "currency": "PYG" - } - }, - "classification": { - "scheme": "UNSPSC", - "id": "41116002", - "description": "Reactivo para HIV" - } - }, - { - "id": "42222308", - "description": "Bolsa colectora de sangre", - "quantity": 2000, - "unit": { - "name": "Unidad", - "value": { - "amount": 290000, - "currency": "PYG" - } - }, - "classification": { - "scheme": "UNSPSC", - "id": "42222308", - "description": "Bolsa colectora de sangre" - } - } - ] - } + ] } ] } diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index 1d5a276fc..a9fd435fe 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -4,35 +4,38 @@ # Organizational units -For some use cases, publishers might need to disclose the organizational units involved in the contracting (or planning) process, e.g agency branches or divisions. +Publishers sometimes need to disclose an organizational unit that is involved in a contracting (or planning) process, like a branch or division of a government agency. -There is more than one approach to model organizational units in OCDS: +The preferred approach to modelling organization units in OCDS is to use the fields in the [`Organization` object](../../schema/reference.md#organization): -1. **Use the fields and blocks available in the Organization building block**. This is the preferred approach, when possible. +* Set `.name` to `{organization name}-{unit name}`. +* Set `.identifier` to the organization's identifier. That is, the identifier of the legal entity of which the unit is a part. +* If the unit has a separate identifier to the organization: + * Set `.id` to `{identifier.scheme}-{identifier.id}-{unit identifier}`. + * Add the unit's identifier to `additionalIdentifiers`. Note that `.additionalIdentifiers` need to reference the same legal entity as `.identifier`. +* Set `address` and `contactPoint` to the unit's address and contact point, respectively. - * Unit names can be included in the `name` field alongside the organization name. - * The `additionalIdentifiers` array can be used to provide any unit identifiers. It is important to note that `identifier` and `additionalIdentifiers` need to point toward the *same legal entity*. The main `identifier` ought to belong to the organization and the `legalName` field can be used to provide the organization name alone. - * The `address` and `contactPoint` blocks can be filled with the unit information. - * Unit identifiers can also be appended to `parties/id`. +If the fields in the `Organization` object are not sufficient to express your data, you can use or create an extension to add fields to the `parties.details` object. -2. When the first option is not enough to model the publisher's case, **use or create an extension**. Any additional fields can be placed in the `details` section of the Organization building block. - -Some publishers use the [memberOf](https://github.com/open-contracting-extensions/ocds_memberOf_extension) extension to represent organization hierarchies, including organizational units. This is strongly discouraged unless there is a clear use case to support it, because OCDS is not designed to disclose hierarchical organization information. Ideally, organizational hierarchies would be represented in separate, non-OCDS datasets, and organizational units would be modelled using one of the alternatives described above. +Disclosing organizational hierarchies in OCDS is strongly discouraged unless there is a clear use case to support it. Ideally, organizational hierarchies ought to be represented in separate, non-OCDS datasets that use the same organization and unit identifiers. To design a hierarchy-oriented dataset, refer to the [W3C Organization Ontology](https://www.w3.org/TR/vocab-org/). However, if you need to represent organizational hierarchies in OCDS, you can use the [memberOf extension](https://github.com/open-contracting-extensions/ocds_memberOf_extension). ## Worked examples -### 1. Using the Organization building block +### 1. Using the Organization object -In Honduras, the Ministry of Health is planning the procurement of food supplies for the San Felipe Hospital. For the purposes of the example, San Felipe Hospital is considered to be a unit belonging to the Ministry of Health, and it is not a legal entity of its own. +In Honduras, San Felipe Hospital announces a planning process for the purchase of food supplies. The hospital is a unit of the Ministry of Health (Secretaría de Salud Pública) and is not a separate legal entity. -In the release below, the publisher adds the hospital name at the end of the procuring entity name. The main identifier for the organization (*Secretaría de Salud Pública*) is extracted from a local list in the "HonduCompras" platform, used to publish procurement information in the country. +The hospital is listed in the `parties` section with: -An identifier for the hospital has been added using the "HN-ONCAE-UNIT" list code. The `address` and `contactPoint` information belongs to the hospital only. +* `.id` is set to `{identifier.scheme}-{identifier.id}-{unit identifier}`: HN-ONCAE-H1-10001-102 +* `.name` set to `{organization name}-{unit name}`: Secretaría de Salud Pública - Hospital San Felipe +* `.identifier` set to the identifier for the legal entity to which the organizational unit belongs, the Ministry of Health. +* the identifier for the organizational unit is listed in `.additionalIdentifiers`. +* `address` and `contactPoint` are set to the address and contact point of the hospital. ```{jsoninclude} ../../examples/organizations/organizational_units/honduras_organization_identifier_scheme.json -:jsonpointer: -:expand: releases, parties, identifier, additionalIdentifiers -:title: release +:jsonpointer: /releases/0/parties/0 +:expand: parties, identifier, additionalIdentifiers ``` ### 2. Defining a new Extension @@ -63,24 +66,30 @@ The branch name (*Chişinău Branch*) is appended at the end of the name of the The `extension.json` and `release-schema.json` files for the Division code extension can be displayed using the combo box above the JSON example. Instructions on how to create an OCDS extension can be found [here](https://github.com/open-contracting/standard_extension_template). -### 3. Using the Organization building block with an organizational hierarchy +### 3. Publishing a separate organizational hierarchy dataset + +In Paraguay, the Hospital Clinic (Hospital de Clínicas) is an organizational unit of the Faculty of Medical Sciences (Facultad de Ciencias Médicas) at the National University of Asuncion (Universidad Nacional de Asunción). The hospital is part of the same legal entity as the faculty, but the faculty is a separate legal entity from the university. -The *Hospital de Clínicas* is planning to procure supplies for their Blood Center. The Hospital is part of the Medical School in the National University of Asuncion. Since the hospital is key in the provision of healthcare for low income groups in the community, it is in the interest of many to clearly identify the procurement of the Hospital only. It is also important for the publisher that users can group the data following organizational hierarchies. +Users need to analyse procurement at hospital, faculty and university level. To serve that needs, Paraguay publishes an OCDS dataset and a separate organizational hierarchy dataset. -It is important to note that OCDS ought to not be used to publish organizational hierarchies unless there is a strong case to support it. Organizational hierarchies can be disclosed in additional datasets. Publishers can refer to the [W3C Organization Ontology](https://www.w3.org/TR/vocab-org/) to design a hierarchy-oriented dataset. +In the OCDS dataset, the hospital is listed in `parties` section with: -The release below shows how the publisher chooses to model the hospital as an organizational unit of the Medical School (*Facultad de Ciencias Médicas*). The source systems collect the name of the organizational unit only, and this is appended to the organization name. +* `.name` set to `{organization name}-{unit name}`: Facultad de Ciencias Médicas - Hospital de Clínicas +* `.identifier` set to the Faculty of Medical Sciences' identifier + +Users can group by `.name` to identify the hospital's contracting processes and by `.identifier` to identify the faculty's contracting processes. ```{jsoninclude} ../../examples/organizations/organizational_units/paraguay_organization_name.json -:jsonpointer: -:expand: releases, tag, parties, identifier +:jsonpointer: /releases/0/parties/0 +:expand: identifier :title: release ``` -In a separate dataset, the publisher discloses the organizational hierarchy. This dataset, in combination with the OCDS publication, would allow users to summarize contracting information. The table below shows an extract of the dataset. +The organizational hierarchy dataset describes the relationship between the faculty and the university. It uses the same organization identifiers as the OCDS dataset. + +Users can use the organization identifiers to join the dataset and identify the university's contracting processes. ```{csv-table-no-translate} :header-rows: 1 :file: ../../examples/organizations/organizational_units/paraguay_organizations.csv ``` - From be526c50b1efbb09a6fc3a20b180b814cb0932a0 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Mar 2024 15:23:32 +1300 Subject: [PATCH 19/36] docs/examples/organizations: Indent examples --- docs/examples/organizations/identifiers.json | 2 +- .../honduras_organization_identifier_scheme.json | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/examples/organizations/identifiers.json b/docs/examples/organizations/identifiers.json index c365ffed0..08b164c93 100644 --- a/docs/examples/organizations/identifiers.json +++ b/docs/examples/organizations/identifiers.json @@ -11,7 +11,7 @@ ], "parties": [ { - "id": "GB-COH-04336774", + "id": "GB-COH-04336774", "name": "IBM", "identifier": { "scheme": "GB-COH", diff --git a/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json b/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json index e9c5ffb82..3afb51107 100644 --- a/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json +++ b/docs/examples/organizations/organizational_units/honduras_organization_identifier_scheme.json @@ -35,7 +35,6 @@ "telephone": "236-5786", "faxNumber": "236-5786" }, - "roles": [ "buyer" ] From 0e402cfa864b0578b1650e69a38184aa3fd47ae0 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 11:34:26 +1300 Subject: [PATCH 20/36] docs/guidance/map/framework_agreements.md: Update examples --- docs/guidance/map/framework_agreements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guidance/map/framework_agreements.md b/docs/guidance/map/framework_agreements.md index 2e9d9731e..1e19118c0 100644 --- a/docs/guidance/map/framework_agreements.md +++ b/docs/guidance/map/framework_agreements.md @@ -168,7 +168,7 @@ An OCDS release describes the opportunity: * `tag` is set to `["tender"]` because this is the first release about the opportunity * The release describes the set up of a framework agreement so the techniques extension is declared in the package metadata and `tender.techniques.hasFrameworkAgreement` is set to `true` -* Only qualified suppliers can respond to the invitation so `tender.procurementMethod` is set to 'selective' +* Whilst any supplier can submit a request to participate, only qualified suppliers can submit a proposal, so `tender.procurementMethod` is set to 'selective' * The framework agreement is closed so `tender.expressionOfInterestDeadline` is set to the deadline for responses to the invitation * There is only one buyer so `buyer` is set to reference the buyer's object in the `parties` array @@ -230,7 +230,7 @@ An OCDS release describes the opportunity: * `tag` is set to `["tender"]` because this is the first release about the opportunity * The release describes the set up of a framework agreement so the techniques extension is declared in the package metadata and `tender.techniques.hasFrameworkAgreement` is set to `true` -* Only qualified suppliers can respond to the invitation so `tender.procurementMethod` is set to 'selective' +* Whilst any supplier can submit a request to participate, only qualified suppliers can submit a proposal, so `tender.procurementMethod` is set to 'selective' * The framework agreement is open (a dynamic purchasing system) so `tender.expressionOfInterestDeadline` is set to the last date that new suppliers can be added * There are two buyers so `buyer` is omitted and both buyers are listed in `parties` * `tender.procuringEntity` is set to the organization that manages the contracting process: Chile Compra From 19ba27fb87561560eefc1327c323fb6a4146675f Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 11:55:47 +1300 Subject: [PATCH 21/36] docs/guidance/map/unsuccessful_processes.md: Update examples --- .../unsuccessful_tender/new_tender.json | 27 ++ .../unsuccessful_tender/planning.json | 46 ---- .../unsuccessful_tender/related_process.json | 243 ------------------ docs/examples/unsuccessful_tender/tender.json | 115 +-------- .../unsuccessful_tender/tenderUpdate.json | 18 ++ docs/guidance/map/unsuccessful_processes.md | 51 ++-- 6 files changed, 75 insertions(+), 425 deletions(-) create mode 100644 docs/examples/unsuccessful_tender/new_tender.json delete mode 100644 docs/examples/unsuccessful_tender/planning.json delete mode 100644 docs/examples/unsuccessful_tender/related_process.json create mode 100644 docs/examples/unsuccessful_tender/tenderUpdate.json diff --git a/docs/examples/unsuccessful_tender/new_tender.json b/docs/examples/unsuccessful_tender/new_tender.json new file mode 100644 index 000000000..764182ef3 --- /dev/null +++ b/docs/examples/unsuccessful_tender/new_tender.json @@ -0,0 +1,27 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0002", + "id": "1", + "date": "2024-01-14T00:00:00Z", + "tag": [ + "tender" + ], + "tender": { + "id": "2", + "title": "Office supplies" + }, + "relatedProcesses": [ + { + "id": "1", + "relationship": [ + "unsuccessfulProcess" + ], + "scheme": "ocid", + "identifier": "ocds-213czf-0001" + } + ] + } + ] +} diff --git a/docs/examples/unsuccessful_tender/planning.json b/docs/examples/unsuccessful_tender/planning.json deleted file mode 100644 index d0316aa4a..000000000 --- a/docs/examples/unsuccessful_tender/planning.json +++ /dev/null @@ -1,46 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "id": "331547-servicio-rastreo-satelital-1-1511346066", - "ocid": "ocds-03ad3f-331547-0", - "date": "2017-11-22T10:21:06-04:00", - "buyer": { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata" - }, - "planning": { - "identifier": "331547", - "budget": { - "description": "ADQUISISCION DE MAQUINARIA, IMPLENTO Y VEHICULO", - "amount": { - "currency": "PYG", - "amount": 700000000 - } - } - }, - "parties": [ - { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata", - "identifier": { - "scheme": "DNCP-SICP-CODE", - "id": "321", - "legalName": "Municipalidad de Loma Plata" - }, - "contactPoint": { - "email": "uoc_municip_lomaplata@hotmail.com", - "name": "Armanda Armanda Acosta", - "telephone": "0492 - 252163" - }, - "roles": [ - "buyer" - ] - } - ], - "tag": [ - "planning" - ] - } - ] -} diff --git a/docs/examples/unsuccessful_tender/related_process.json b/docs/examples/unsuccessful_tender/related_process.json deleted file mode 100644 index 96842d7c6..000000000 --- a/docs/examples/unsuccessful_tender/related_process.json +++ /dev/null @@ -1,243 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "id": "331547-adquisicion-maquinaria-implemento-vehiculo-3-1511346066", - "awards": [ - { - "id": "331547-kurosu-cia-sa-2", - "status": "active", - "date": "2017-10-30T12:00:00-04:00", - "value": { - "amount": 417343000, - "currency": "PYG" - }, - "suppliers": [ - { - "name": "KUROSU Y CIA SA", - "id": "PY-RUC-80002592-0" - } - ], - "items": [ - { - "id": "iFlsx1SrzT4=", - "description": "ROTATIVA", - "classification": { - "scheme": "catalogoNivel5DNCP", - "id": "26101510-001", - "description": "Rotativa hidraulica", - "uri": "https://www.contrataciones.gov.py/datos/api/v3/doc/itemClassification/n5/26101510-001" - }, - "additionalClassifications": [ - { - "scheme": "UNSPSC", - "id": "26101510", - "description": "Maquinas rotativas", - "uri": "https://www.contrataciones.gov.py/datos/api/v3/doc/itemClassification/n4/26101510" - } - ], - "quantity": 1, - "unit": { - "name": "Unidad", - "id": "UNI", - "value": { - "amount": 59500000, - "currency": "PYG" - } - }, - "relatedLot": "ux682+kLP2w=" - } - ] - } - ], - "tender": { - "id": "331547-adquisicion-maquinaria-implemento-vehiculo-3", - "title": "ADQUISICION DE MAQUINARIA, IMPLEMENTO Y VEHICULO", - "status": "complete", - "awardCriteria": "priceOnly", - "awardCriteriaDetails": "Por Item", - "submissionMethodDetails": "Lugar entrega ofertas: MUNICIPALIDA DE LOMA PLATA || Lugar entrega bien: Según documento del llamado || Fecha entrega bien: Según documento del llamado", - "enquiriesAddress": { - "streetAddress": "MUNICIPALIDA DE LOMA PLATA" - }, - "mainProcurementCategoryDetails": "Bienes - Maquinarias, Equipos y herramientas mayores - Equipos de transporte", - "hasEnquiries": false, - "value": { - "amount": 637000000, - "currency": "PYG" - }, - "datePublished": "2017-10-13T10:08:54-04:00", - "tenderPeriod": { - "startDate": "2017-10-13T10:08:54-04:00", - "endDate": "2017-10-27T08:00:00-04:00", - "durationInDays": 13 - }, - "awardPeriod": { - "startDate": "2017-10-27T08:15:00-04:00" - }, - "enquiryPeriod": { - "endDate": "2017-10-24T15:00:00-04:00", - "startDate": "2017-10-13T10:08:54-04:00", - "durationInDays": 11 - }, - "mainProcurementCategory": "goods", - "procurementMethod": "open", - "procurementMethodDetails": "Concurso de Ofertas", - "procuringEntity": { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata" - }, - "lots": [ - { - "id": "ux682+kLP2w=", - "title": "2 - ROTATIVA", - "status": "active", - "value": { - "amount": 32000000, - "currency": "PYG" - } - } - ], - "items": [ - { - "id": "T8wQt6GlGiC7aVwjYuAaiA==", - "description": "TRACTOR 4X4", - "classification": { - "scheme": "catalogoNivel5DNCP", - "id": "25101901-001", - "description": "Tractor agricola", - "uri": "https://www.contrataciones.gov.py/datos/api/v3/doc/itemClassification/n5/25101901-001" - }, - "quantity": 1, - "unit": { - "name": "Unidad", - "id": "UNI", - "value": { - "amount": 400000000, - "currency": "PYG" - } - }, - "relatedLot": "ux682+kLP2w=" - } - ], - "numberOfTenderers": 2, - "tenderers": [ - { - "name": "CUEVAS HERMANOS S.A.", - "id": "PY-RUC-80002465-6" - }, - { - "name": "KUROSU Y CIA SA", - "id": "PY-RUC-80002592-0" - } - ] - }, - "ocid": "ocds-03ad3f-331547-2", - "date": "2017-11-22T10:21:06-04:00", - "buyer": { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata" - }, - "relatedProcesses": [ - { - "id": "1", - "relationship": [ - "unsuccessfulProcess" - ], - "scheme": "ocid", - "identifier": "ocds-03ad3f-331547-1" - }, - { - "id": "2", - "relationship": [ - "planning" - ], - "scheme": "ocid", - "identifier": "ocds-03ad3f-331547" - } - ], - "parties": [ - { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata", - "identifier": { - "scheme": "DNCP-SICP-CODE", - "id": "321", - "legalName": "Municipalidad de Loma Plata" - }, - "contactPoint": { - "email": "uoc_municip_lomaplata@hotmail.com", - "name": "Armanda Armanda Acosta", - "telephone": "0492 - 252163" - }, - "roles": [ - "buyer", - "procuringEntity" - ], - "additionalIdentifiers": [ - { - "id": "2017.30.231", - "legalName": "Municipalidad de Loma Plata", - "scheme": "PY-PGN" - } - ] - }, - { - "name": "CUEVAS HERMANOS S.A.", - "id": "PY-RUC-80002465-6", - "identifier": { - "id": "80002465-6", - "legalName": "CUEVAS HERMANOS S.A.", - "scheme": "PY-RUC" - }, - "roles": [ - "supplier", - "tenderer" - ], - "contactPoint": { - "name": "DIDIER ARIAS QUIÑONEZ - NUFRO ARIAS GIRET - MARIA MAGDALENA QUIÑONEZ - LIZZIE ARIAS QUIÑONEZ - GISELLE ARIAS.", - "email": "licitaciones@nissan.com.py", - "faxNumber": "021/6198000", - "url": "http://www.nissan.com.py" - }, - "address": { - "country": "PY", - "locality": "ASUNCION (DISTRITO)", - "region": "Asunción", - "streetAddress": "Mcal López 5557 c/Rogelio Benitez" - } - }, - { - "name": "KUROSU Y CIA SA", - "id": "PY-RUC-80002592-0", - "identifier": { - "id": "80002592-0", - "legalName": "KUROSU Y CIA SA", - "scheme": "PY-RUC" - }, - "roles": [ - "tenderer", - "supplier" - ], - "contactPoint": { - "name": "JAIME HITOCHI KUROSU ISHIGAKI, EVA ROSA RODRIGUEZ DE HERMOSILLA, ANTONIO MACIEL ROTELA, MINA KUROSU ISHIGAKI, BASILIO JOSE RAMIREZ FLORES, NOEMI CLAUDIA CESPEDES(APODERADA)", - "email": "rubensilvero@kurosu.com.py", - "faxNumber": "214600", - "telephone": "0983 123069 (R.Silvero)", - "url": "http://www.kurosu.com.py" - }, - "address": { - "country": "PY", - "locality": "ENCARNACION", - "region": "Itapúa", - "streetAddress": "RUTA VI KM 6 - Bº ARROYO PORA" - } - } - ], - "tag": [ - "tender", - "award" - ] - } - ] -} diff --git a/docs/examples/unsuccessful_tender/tender.json b/docs/examples/unsuccessful_tender/tender.json index 05a676983..b39087a59 100644 --- a/docs/examples/unsuccessful_tender/tender.json +++ b/docs/examples/unsuccessful_tender/tender.json @@ -2,117 +2,16 @@ "version": "1.1", "releases": [ { - "id": "331547-servicio-rastreo-satelital-1-1511346066", - "tender": { - "id": "331547-servicio-rastreo-satelital-1", - "title": "SERVICIO DE RASTREO SATELITAL", - "status": "unsuccessful", - "awardCriteria": "priceOnly", - "awardCriteriaDetails": "Por Total", - "submissionMethodDetails": "Lugar entrega ofertas: MUNICIPALIDAD DE LOMA PLATA || Lugar entrega bien: Según documento del llamado || Fecha entrega bien: Según documento del llamado", - "statusDetails": "Desierta", - "enquiriesAddress": { - "streetAddress": "MUNICIPALIDAD DE LOMA PLATA" - }, - "mainProcurementCategoryDetails": "Bienes - Maquinarias, Equipos y herramientas mayores - Equipos de transporte", - "hasEnquiries": false, - "value": { - "amount": 8100000, - "currency": "PYG" - }, - "tenderPeriod": { - "startDate": "2017-05-03T09:53:46-04:00", - "endDate": "2017-05-11T09:30:00-04:00", - "durationInDays": 7 - }, - "awardPeriod": { - "startDate": "2017-05-11T10:00:00-04:00" - }, - "enquiryPeriod": { - "endDate": "2017-05-05T11:00:00-04:00", - "startDate": "2017-05-03T09:53:46-04:00", - "durationInDays": 2 - }, - "mainProcurementCategory": "goods", - "procurementMethod": "open", - "procurementMethodDetails": "Contratación Directa", - "procuringEntity": { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata" - }, - "lots": [ - { - "id": "+GmottIGrAE=", - "title": "1 - SERVICIO DE RASTREO SATELITAL", - "status": "unsuccessful", - "value": { - "amount": 8100000, - "currency": "PYG" - } - } - ], - "items": [ - { - "id": "+PMxGSG2jUzCpFMtx0fwgg==", - "description": "Servicio de Rastreo Satelital", - "classification": { - "scheme": "catalogoNivel5DNCP", - "id": "92121701-002", - "description": "Servicio de Rastreo Satelital", - "uri": "https://www.contrataciones.gov.py/datos/api/v3/doc/itemClassification/n5/92121701-002" - }, - "quantity": 6, - "unit": { - "name": "Unidad", - "id": "UNI", - "value": { - "amount": 1350000, - "currency": "PYG" - } - }, - "relatedLot": "+GmottIGrAE=" - } - ] - }, - "ocid": "ocds-03ad3f-331547-1", - "date": "2017-11-22T10:21:06-04:00", - "buyer": { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata" - }, - "parties": [ - { - "id": "DNCP-SICP-CODE-321", - "name": "Municipalidad de Loma Plata", - "identifier": { - "scheme": "DNCP-SICP-CODE", - "id": "321", - "legalName": "Municipalidad de Loma Plata" - }, - "contactPoint": { - "email": "uoc_municip_lomaplata@hotmail.com", - "name": "Armanda Armanda Acosta", - "telephone": "0492 - 252163" - }, - "roles": [ - "buyer", - "procuringEntity" - ] - } - ], + "ocid": "ocds-213czf-0001", + "id": "1", + "date": "2024-01-01T00:00:00Z", "tag": [ "tender" ], - "relatedProcesses": [ - { - "id": "1", - "relationship": [ - "planning" - ], - "scheme": "ocid", - "identifier": "ocds-03ad3f-331547" - } - ] + "tender": { + "id": "1", + "title": "Office supplies" + } } ] } diff --git a/docs/examples/unsuccessful_tender/tenderUpdate.json b/docs/examples/unsuccessful_tender/tenderUpdate.json new file mode 100644 index 000000000..2def90230 --- /dev/null +++ b/docs/examples/unsuccessful_tender/tenderUpdate.json @@ -0,0 +1,18 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0001", + "id": "1", + "date": "2024-01-07T00:00:00Z", + "tag": [ + "tenderUpdate" + ], + "tender": { + "id": "1", + "title": "Office supplies", + "status": "Unsuccessful" + } + } + ] +} diff --git a/docs/guidance/map/unsuccessful_processes.md b/docs/guidance/map/unsuccessful_processes.md index ca10c6e8f..700dcd049 100644 --- a/docs/guidance/map/unsuccessful_processes.md +++ b/docs/guidance/map/unsuccessful_processes.md @@ -4,46 +4,41 @@ # Unsuccessful processes -In most jurisdictions, if a procedure is cancelled or unsuccessful, and a **new procedure** is started to procure the same items, the two procedures are considered two **different** contracting processes. This is in keeping with the OCDS definition of a contracting process. +Contracting processes are sometimes cancelled or unsuccessful, in which case a buyer might restart a process to purchase the same items. -However, in some jurisdictions, such as Paraguay, planning activity is considered as initiating the contracting process. Furthermore, if a first attempt is unsuccessful in procuring items, the second attempt is considered to be part of the same contracting process. This differs from the OCDS definition of a contracting process. OCDS, instead, records the cancelled procedure in the `relatedProcesses` array of the new procedure, with the 'unsuccessfulProcess' code in the related process' `relationship` array. +In OCDS, when a buyer restarts a failed contracting process, the restart is modelled as the initiation of a new contracting processes. -![Unsuccessful Tender](../../_static/png/unsuccessful_tender.png) - -## Example: Modelling unsuccessful tenders in Paraguay +To link a new process to the previous attempt at procuring the same items, you ought to add the unsuccessful process to the `relatedProcesses` array of the new process, with a `.relationship` of 'unsuccessfulProcess'. -The [Sistema de Información de las Contrataciones Públicas (SICP)](https://contrataciones.gov.py/) discloses information about contracting processes for all public entities in Paraguay. SICP is managed by the National Directorate of Public Procurement (DNCP in Spanish). - -The first data disclosed is about the planning process. Planning data includes an estimate of what an entity is going to buy, when and for how much. SICP assigns an `ocid` when the planning data is first disclosed, before the tender stage. In this example, the ocid is 'ocds-03ad3f-331547'. +![Unsuccessful Tender](../../_static/png/unsuccessful_tender.png) -```{jsoninclude} ../../examples/unsuccessful_tender/planning.json -:jsonpointer: -:expand: releases, planning -:title: unsuccessful-tender-planning -``` +## Example -Next, the contracting process is disclosed, using a new `ocid`, 'ocds-03ad3f-331547-1'. The `relatedProcess` block links the planning process and the contracting process, with the relationship set to 'planning'. +This example illustrates how to model failed and restarted contracting processes in OCDS. -The tender was unsuccessful, so the tender's `status` is set to 'unsuccessful'. +A buyer attempts to purchase office supplies by announcing an opportunity. The contracting process is assigned an `ocid` of 'ocds-213czf-0001'. ```{jsoninclude} ../../examples/unsuccessful_tender/tender.json -:jsonpointer: -:expand: releases, relatedProcesses, tender, status -:title: unsuccessful-tender-tender +:jsonpointer: /releases/0 +:expand: releases, tender ``` -The buyer issues another tender to buy the same item, following from the same planning process. - -Paraguay considers the two tenders part of the same contracting process. But, in OCDS the two tenders are separate contracting processes. +The attempt is unsuccessful so the buyer sets `tender.status` to 'unsuccessful'. -To construct an `ocid` for the second contracting process, Paraguay adds a consecutive number to the `ocid` of the first process. In this example the new `ocid` is 'ocds-03ad3f-331547-2' +```{jsoninclude} ../../examples/unsuccessful_tender/tenderUpdate.json +:jsonpointer: /releases/0 +:expand: releases, tender +``` -Paraguay could also have used the identifier for the second tender as the `ocid` for the second contracting process. +The buyer announces a second opportunity to purchase the same item. The new contracting process is assigned an `ocid` of 'ocds-213czf-0002'. The failed attempt is recorded in `.relatedProcesses`. -The `relatedProcesses` block links to the unsuccessful contracting process with the relationship set to 'unsuccessfulProcess', and to the initial planning process with the relationship set to 'planning'. +```{jsoninclude} ../../examples/unsuccessful_tender/new_tender.json +:jsonpointer: /releases/0 +:expand: releases, tender, relatedProcesses +``` -```{jsoninclude} ../../examples/unsuccessful_tender/related_process.json -:jsonpointer: -:expand: releases, relatedProcesses, relationship -:title: unsuccessful-tender-related-process +```{admonition} Unsuccessful and restarted processes with a shared identifier + In some jurisdictions, such as Paraguay, if a first attempt is unsuccessful in procuring items, the second attempt is considered to be part of the same contracting process and, as a result, shares its identifier. In OCDS, the two attempts need to be modelled as separate contracting processes with different `ocid`s. + + If your data sources lack a unique identifier for the second attempt, you can assign its `ocid` by appending an incrementing number to the `ocid` of the first process, e.g. `{first process ocid}-1`. ``` From cef92bd86dbb1c54c7c25732b9b557dc98400653 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 12:48:28 +1300 Subject: [PATCH 22/36] docs/guidance/map/unsuccessful_processes.md: Update ocids --- docs/examples/unsuccessful_tender/new_tender.json | 4 ++-- docs/examples/unsuccessful_tender/tender.json | 2 +- docs/examples/unsuccessful_tender/tenderUpdate.json | 2 +- docs/guidance/map/unsuccessful_processes.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/examples/unsuccessful_tender/new_tender.json b/docs/examples/unsuccessful_tender/new_tender.json index 764182ef3..9d17615b2 100644 --- a/docs/examples/unsuccessful_tender/new_tender.json +++ b/docs/examples/unsuccessful_tender/new_tender.json @@ -2,7 +2,7 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-213czf-0002", + "ocid": "ocds-213czf-0001", "id": "1", "date": "2024-01-14T00:00:00Z", "tag": [ @@ -19,7 +19,7 @@ "unsuccessfulProcess" ], "scheme": "ocid", - "identifier": "ocds-213czf-0001" + "identifier": "ocds-213czf-0000" } ] } diff --git a/docs/examples/unsuccessful_tender/tender.json b/docs/examples/unsuccessful_tender/tender.json index b39087a59..3bcfcd431 100644 --- a/docs/examples/unsuccessful_tender/tender.json +++ b/docs/examples/unsuccessful_tender/tender.json @@ -2,7 +2,7 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-213czf-0001", + "ocid": "ocds-213czf-0000", "id": "1", "date": "2024-01-01T00:00:00Z", "tag": [ diff --git a/docs/examples/unsuccessful_tender/tenderUpdate.json b/docs/examples/unsuccessful_tender/tenderUpdate.json index 2def90230..2a3149c00 100644 --- a/docs/examples/unsuccessful_tender/tenderUpdate.json +++ b/docs/examples/unsuccessful_tender/tenderUpdate.json @@ -2,7 +2,7 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-213czf-0001", + "ocid": "ocds-213czf-0000", "id": "1", "date": "2024-01-07T00:00:00Z", "tag": [ diff --git a/docs/guidance/map/unsuccessful_processes.md b/docs/guidance/map/unsuccessful_processes.md index 700dcd049..bedd26337 100644 --- a/docs/guidance/map/unsuccessful_processes.md +++ b/docs/guidance/map/unsuccessful_processes.md @@ -16,7 +16,7 @@ To link a new process to the previous attempt at procuring the same items, you o This example illustrates how to model failed and restarted contracting processes in OCDS. -A buyer attempts to purchase office supplies by announcing an opportunity. The contracting process is assigned an `ocid` of 'ocds-213czf-0001'. +A buyer attempts to purchase office supplies by announcing an opportunity. The contracting process is assigned an `ocid` of 'ocds-213czf-0000'. ```{jsoninclude} ../../examples/unsuccessful_tender/tender.json :jsonpointer: /releases/0 @@ -30,7 +30,7 @@ The attempt is unsuccessful so the buyer sets `tender.status` to 'unsuccessful'. :expand: releases, tender ``` -The buyer announces a second opportunity to purchase the same item. The new contracting process is assigned an `ocid` of 'ocds-213czf-0002'. The failed attempt is recorded in `.relatedProcesses`. +The buyer announces a second opportunity to purchase the same item. The new contracting process is assigned a new `ocid` of 'ocds-213czf-0001'. The failed attempt is recorded in `.relatedProcesses`. ```{jsoninclude} ../../examples/unsuccessful_tender/new_tender.json :jsonpointer: /releases/0 From c2ded5ec13d1822d20eb4d6ddea3ccb00007b7ea Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 12:48:41 +1300 Subject: [PATCH 23/36] docs/guidance/map/contracting_planning_processes.md: Add example --- .../contracting.json | 31 +++++++++++++++++++ .../planning.json | 25 +++++++++++++++ .../map/contracting_planning_processes.md | 22 +++++++++++++ 3 files changed, 78 insertions(+) create mode 100644 docs/examples/contracting_planning_processes/contracting.json create mode 100644 docs/examples/contracting_planning_processes/planning.json diff --git a/docs/examples/contracting_planning_processes/contracting.json b/docs/examples/contracting_planning_processes/contracting.json new file mode 100644 index 000000000..a5fe4f5a3 --- /dev/null +++ b/docs/examples/contracting_planning_processes/contracting.json @@ -0,0 +1,31 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0001", + "id": "1", + "date": "2024-07-01T00:00:00Z", + "tag": [ + "tender" + ], + "tender": { + "id": "1", + "title": "Office supplies", + "value": { + "amount": 10000, + "currency": "USD" + } + }, + "relatedProcesses": [ + { + "id": "1", + "relationship": [ + "planning" + ], + "scheme": "ocid", + "identifier": "ocds-213czf-0000" + } + ] + } + ] +} diff --git a/docs/examples/contracting_planning_processes/planning.json b/docs/examples/contracting_planning_processes/planning.json new file mode 100644 index 000000000..327a8509c --- /dev/null +++ b/docs/examples/contracting_planning_processes/planning.json @@ -0,0 +1,25 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "planning" + ], + "planning": { + "budget": { + "amount": { + "amount": 10000, + "currency": "USD" + } + } + }, + "tender": { + "id": "1", + "title": "Office supplies" + } + } + ] +} diff --git a/docs/guidance/map/contracting_planning_processes.md b/docs/guidance/map/contracting_planning_processes.md index 0ab6e8af1..c5f359113 100644 --- a/docs/guidance/map/contracting_planning_processes.md +++ b/docs/guidance/map/contracting_planning_processes.md @@ -33,3 +33,25 @@ We recommend publishing data about planning and contracting processes under sepa ```{note} In OCDS 1.2 and earlier, it is not possible to publish all information about multi-stage procedures under a single `ocid`. There is guidance on how to deal with this for [framework agreements](framework_agreements) and for [pre-qualification and pre-selection](pre-qualification). If you want to disclose this type of information (including other types of multi-stage procedures, such as competitive dialogues and innovation partnerships), [contact the Data Support Team](../../support/index). The approach to modelling multi-stage procedures in a future, backwards-incompatible version of the standard is under discussion on [GitHub](https://github.com/open-contracting/standard/issues/440). ``` + +## Example + +This example illustrates how to model planning and contracting processes. + +A buyer announces a planning process for the purchase of office supplies. + +The process is assigned an `ocid` of "ocds-213czf-0000" and `.tag` is set to `["planning"]` to indicate that the release concerns a planning process. The `planning` object contains information about budget planning and the `tender` object contains information about the needed items. + +```{jsoninclude} ../../examples/contracting_planning_processes/planning.json +:jsonpointer: /releases/0 +:expand: releases, planning, tender +``` + +Following the completion of the planning process, the buyer initiates a contracting process to purchase the office supplies. + +The new process is assigned a new `ocid` of "ocds-213czf-0001" and `.tag` is set to `["tender"]` to indicate that the release concerns a contracting process. The `tender` object contains information about the needed items. The planning process is referenced in `relatedProcesses`. + +```{jsoninclude} ../../examples/contracting_planning_processes/contracting.json +:jsonpointer: /releases/0 +:expand: releases, tender, relatedProcesses +``` From 91313dabeba0fefa6b0825e4e519e5e4cdc1ae1c Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 14:43:50 +1300 Subject: [PATCH 24/36] docs/guidance/map/organizational_units.md: Copy edit --- docs/guidance/map/organizational_units.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index a9fd435fe..dd6721da4 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -23,13 +23,13 @@ Disclosing organizational hierarchies in OCDS is strongly discouraged unless the ### 1. Using the Organization object -In Honduras, San Felipe Hospital announces a planning process for the purchase of food supplies. The hospital is a unit of the Ministry of Health (Secretaría de Salud Pública) and is not a separate legal entity. +San Felipe Hospital in Honduras announces a planning process for the purchase of food supplies. The hospital is a unit of the Ministry of Health (Secretaría de Salud Pública) and is not a separate legal entity. -The hospital is listed in the `parties` section with: +The hospital is listed in the `parties` section and: -* `.id` is set to `{identifier.scheme}-{identifier.id}-{unit identifier}`: HN-ONCAE-H1-10001-102 -* `.name` set to `{organization name}-{unit name}`: Secretaría de Salud Pública - Hospital San Felipe -* `.identifier` set to the identifier for the legal entity to which the organizational unit belongs, the Ministry of Health. +* `.id` is set to `{identifier.scheme}-{identifier.id}-{unit identifier}`: HN-ONCAE-H1-10001-102. +* `.name` is set to `{organization name}-{unit name}`: Secretaría de Salud Pública - Hospital San Felipe. +* `.identifier` is set to the identifier for the legal entity to which the organizational unit belongs, the Ministry of Health. * the identifier for the organizational unit is listed in `.additionalIdentifiers`. * `address` and `contactPoint` are set to the address and contact point of the hospital. @@ -68,14 +68,14 @@ The `extension.json` and `release-schema.json` files for the Division code exten ### 3. Publishing a separate organizational hierarchy dataset -In Paraguay, the Hospital Clinic (Hospital de Clínicas) is an organizational unit of the Faculty of Medical Sciences (Facultad de Ciencias Médicas) at the National University of Asuncion (Universidad Nacional de Asunción). The hospital is part of the same legal entity as the faculty, but the faculty is a separate legal entity from the university. +The Hospital Clinic (Hospital de Clínicas) in Paraguay is an organizational unit of the Faculty of Medical Sciences (Facultad de Ciencias Médicas) at the National University of Asuncion (Universidad Nacional de Asunción). The hospital is part of the same legal entity as the faculty, but the faculty is a separate legal entity from the university. -Users need to analyse procurement at hospital, faculty and university level. To serve that needs, Paraguay publishes an OCDS dataset and a separate organizational hierarchy dataset. +Users need to analyse procurement at hospital, faculty and university level. To serve that need, Paraguay publishes an OCDS dataset and a separate organizational hierarchy dataset. -In the OCDS dataset, the hospital is listed in `parties` section with: +In the OCDS dataset, the hospital is listed in `parties` section and: -* `.name` set to `{organization name}-{unit name}`: Facultad de Ciencias Médicas - Hospital de Clínicas -* `.identifier` set to the Faculty of Medical Sciences' identifier +* `.name` is set to `{organization name}-{unit name}`: Facultad de Ciencias Médicas - Hospital de Clínicas. +* `.identifier` is set to the Faculty of Medical Sciences' identifier. Users can group by `.name` to identify the hospital's contracting processes and by `.identifier` to identify the faculty's contracting processes. @@ -87,7 +87,7 @@ Users can group by `.name` to identify the hospital's contracting processes and The organizational hierarchy dataset describes the relationship between the faculty and the university. It uses the same organization identifiers as the OCDS dataset. -Users can use the organization identifiers to join the dataset and identify the university's contracting processes. +Users can use the organization identifiers to join the datasets and identify the university's contracting processes. ```{csv-table-no-translate} :header-rows: 1 From a82acb788c3840681d254bd547ebe838a119bdf4 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 14:46:57 +1300 Subject: [PATCH 25/36] docs/guidance/map/organization_personal_identifiers.md: Copy edit --- docs/guidance/map/organization_personal_identifiers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index ab142b26c..a3e8b7884 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -18,7 +18,7 @@ There are two components to an identifier in OCDS: * a code indicating the list or register from which the identifier is drawn (the `scheme`); and * the identifier itself (the `id`). -Follow the [guidance](https://standard.openownership.org/en/0.2.0/schema/guidance/identifiers.html#shared-identifiers) from the Beneficial Ownership Data Standard to construct a `scheme` value for a personal identifier: +To construct a `scheme` value for a personal identifier, follow the [guidance](https://standard.openownership.org/en/0.2.0/schema/guidance/identifiers.html#shared-identifiers) from the Beneficial Ownership Data Standard: > the scheme should have the pattern {JURISDICTION}-{TYPE} where JURISDICTION is an uppercase ISO 3166-1 alpha-3 country code and TYPE is one of PASSPORT, TAXID or IDCARD @@ -29,6 +29,6 @@ A publisher in Colombia collects national ID card numbers as identifiers for nat A self-employed individual submits a bid for an opportunity. The individual is listed in the `parties` section with 'tenderer' in `.roles`. `.identifier.id` is set to the individual's ID card number and `.identifier.scheme` is constructed from the ISO 3166-1 alpha-3 country code for Colombia ('COL') and the type of the identifier ('IDCARD'). ```{jsoninclude} ../../examples/organizations/personal_identifier.json -:jsonpointer: -:expand: releases, parties, identifier +:jsonpointer: /releases/0 +:expand: parties, identifier ``` From 743384adab2a937f2398d4bd430a1a89c647d597 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 18:24:36 +1300 Subject: [PATCH 26/36] docs/guidance/map/organization_classifications.md: Update examples, copy-edit --- ...ional_wob_organization_classification.json | 52 ----------- .../moldova_organization_scale.json | 63 ------------- .../organization_classification/scale.json | 25 ++++++ .../ted_buyer_type.json | 34 +++++++ .../uk_organization_classification.json | 67 -------------- .../women_owned.json | 34 +++++++ .../map/organization_classifications.md | 90 ++++++++++--------- 7 files changed, 140 insertions(+), 225 deletions(-) delete mode 100644 docs/examples/organizations/organization_classification/fictional_wob_organization_classification.json delete mode 100644 docs/examples/organizations/organization_classification/moldova_organization_scale.json create mode 100644 docs/examples/organizations/organization_classification/scale.json create mode 100644 docs/examples/organizations/organization_classification/ted_buyer_type.json delete mode 100644 docs/examples/organizations/organization_classification/uk_organization_classification.json create mode 100644 docs/examples/organizations/organization_classification/women_owned.json diff --git a/docs/examples/organizations/organization_classification/fictional_wob_organization_classification.json b/docs/examples/organizations/organization_classification/fictional_wob_organization_classification.json deleted file mode 100644 index 92b7fd7ae..000000000 --- a/docs/examples/organizations/organization_classification/fictional_wob_organization_classification.json +++ /dev/null @@ -1,52 +0,0 @@ -{ - "extensions": [ - "https://raw.githubusercontent.com/open-contracting-extensions/ocds_organizationClassification_extension/master/extension.json" - ], - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-col-cf/1111", - "id": "ocds-213czf-col-cf/1111-02-award", - "date": "2020-01-04T13:18:31+05:45", - "parties": [ - { - "id": "CF-CDC-A564321", - "name": "Empresa de mujeres uno", - "identifier": { - "scheme": "CF-CDC", - "id": "A564321" - }, - "roles": [ - "supplier" - ], - "details": { - "classifications": [ - { - "description": "Negocio propiedad de mujeres", - "id": "NPDM", - "scheme": "COL-CF-MON" - } - ] - } - } - ], - "awards": [ - { - "suppliers": [ - { - "name": "Empresa de mujeres uno", - "id": "CF-CDC-A564321" - } - ], - "status": "active", - "date": "2019-01-01T00:00:00+05:45", - "id": "ocds-213czf-col-cf-awards/1", - "title": "Servicios de proyectos de datos abiertos de la ciudad" - } - ], - "tag": [ - "award" - ] - } - ] -} diff --git a/docs/examples/organizations/organization_classification/moldova_organization_scale.json b/docs/examples/organizations/organization_classification/moldova_organization_scale.json deleted file mode 100644 index 8533b91fe..000000000 --- a/docs/examples/organizations/organization_classification/moldova_organization_scale.json +++ /dev/null @@ -1,63 +0,0 @@ -{ - "version": "1.1", - "releases": [ - { - "ocid": "ocds-b3wdp1-MD-1554728148222-EV-1555", - "id": "ocds-b3wdp1-MD-1554728148222-EV-1555-155", - "date": "2019-05-15T10:24:48Z", - "tag": [ - "award" - ], - "parties": [ - { - "id": "MD-IDNO-1012600024777", - "name": "Companie mică", - "identifier": { - "scheme": "MD-IDNO", - "id": "1012600024777", - "legalName": "Exemplu de companie mică" - }, - "details": { - "scale": "micro" - }, - "roles": [ - "tenderer", - "supplier" - ] - } - ], - "tender": { - "id": "ocds-b3wdp1-MD-1554728148222-tender", - "title": "Îmbunătățirea planificată a pistelor ciclice", - "description": "Ofertanții au solicitat lucrări pentru construirea de noi biciclete în centrul orașului.", - "status": "complete", - "hasEnquiries": false, - "submissionMethodDetails": "Lista platformelor: achizitii, ebs, licitatie, yptender", - "tenderers": [ - { - "id": "MD-IDNO-1012600024777", - "name": "Companie mică" - } - ] - }, - "awards": [ - { - "id": "e5b771e0-715e-11e9-94b9-f5c641d7a5b5", - "description": "Compania mică a primit contractul pentru construirea de noi piste pentru biciclete în centrul orașului.", - "status": "pending", - "date": "2019-05-15T10:24:53Z", - "value": { - "amount": 27089725.78, - "currency": "MDL" - }, - "suppliers": [ - { - "id": "MD-IDNO-1012600024777", - "name": "Companie mică" - } - ] - } - ] - } - ] -} diff --git a/docs/examples/organizations/organization_classification/scale.json b/docs/examples/organizations/organization_classification/scale.json new file mode 100644 index 000000000..46978afc8 --- /dev/null +++ b/docs/examples/organizations/organization_classification/scale.json @@ -0,0 +1,25 @@ +{ + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "tender" + ], + "parties": [ + { + "id": "1", + "name": "Microsoft", + "roles": [ + "tenderer" + ], + "details": { + "scale": "large" + } + } + ] + } + ] +} diff --git a/docs/examples/organizations/organization_classification/ted_buyer_type.json b/docs/examples/organizations/organization_classification/ted_buyer_type.json new file mode 100644 index 000000000..152a3caa7 --- /dev/null +++ b/docs/examples/organizations/organization_classification/ted_buyer_type.json @@ -0,0 +1,34 @@ +{ + "extensions": [ + "https://raw.githubusercontent.com/open-contracting-extensions/ocds_organizationClassification_extension/master/extension.json" + ], + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0001", + "id": "1", + "date": "2019-03-30T17:08:14+05:45", + "tag": [ + "tender" + ], + "parties": [ + { + "id": "1", + "name": "London Borough of Haringey", + "roles": [ + "buyer" + ], + "details": { + "classifications": [ + { + "scheme": "TED_CA_TYPE", + "id": "REGIONAL_AUTHORITY", + "description": "Regional or local authority" + } + ] + } + } + ] + } + ] +} diff --git a/docs/examples/organizations/organization_classification/uk_organization_classification.json b/docs/examples/organizations/organization_classification/uk_organization_classification.json deleted file mode 100644 index e080d6a92..000000000 --- a/docs/examples/organizations/organization_classification/uk_organization_classification.json +++ /dev/null @@ -1,67 +0,0 @@ -{ - "extensions": [ - "https://raw.githubusercontent.com/open-contracting-extensions/ocds_organizationClassification_extension/master/extension.json" - ], - "version": "1.1", - "releases": [ - { - "ocid": "ocds-h6vhtk-016248", - "id": "ocds-h6vhtk-016248-02-tender", - "date": "2019-03-30T17:08:14+05:45", - "tag": [ - "tender" - ], - "tender": { - "id": "016248-Zg9B567X-001", - "description": "Tender for the provision of borough reablement services, subsection frailty 65+.", - "status": "complete", - "mainProcurementCategory": "services", - "procurementMethodDetails": "Open procedure", - "title": "Reablement — Frailty 65+", - "procurementMethod": "open" - }, - "buyer": { - "name": "London Borough of Haringey", - "id": "GB-SRS-supplierregistration.cabinetoffice.gov.uk/Zg9B567X" - }, - "parties": [ - { - "id": "GB-SRS-supplierregistration.cabinetoffice.gov.uk/Zg9B567X", - "name": "London Borough of Haringey", - "identifier": { - "legalName": "London Borough of Haringey", - "scheme": "GB-SRS", - "id": "supplierregistration.cabinetoffice.gov.uk/Zg9B567X" - }, - "roles": [ - "buyer" - ], - "details": { - "classifications": [ - { - "description": "Regional or local authority", - "id": "REGIONAL_AUTHORITY", - "scheme": "TED_CA_TYPE" - }, - { - "description": "General public services", - "id": "01", - "scheme": "COFOG" - } - ] - }, - "address": { - "streetAddress": "Haringey Council Civic Centre, Level 6, 255 High Rd", - "locality": "Wood Green", - "region": "UKG13", - "postalCode": "N22 8LE", - "country": "GB" - }, - "contactPoint": { - "url": "http://www.haringey.gov.uk" - } - } - ] - } - ] -} diff --git a/docs/examples/organizations/organization_classification/women_owned.json b/docs/examples/organizations/organization_classification/women_owned.json new file mode 100644 index 000000000..41012de7b --- /dev/null +++ b/docs/examples/organizations/organization_classification/women_owned.json @@ -0,0 +1,34 @@ +{ + "extensions": [ + "https://raw.githubusercontent.com/open-contracting-extensions/ocds_organizationClassification_extension/master/extension.json" + ], + "version": "1.1", + "releases": [ + { + "ocid": "ocds-213czf-0002", + "id": "1", + "date": "2020-01-04T13:18:31+05:45", + "tag": [ + "tender" + ], + "parties": [ + { + "id": "1", + "name": "Contadores de Medellín", + "roles": [ + "tenderer" + ], + "details": { + "classifications": [ + { + "description": "Negocio propiedad de mujeres", + "id": "NPDM", + "scheme": "COL-AN-ME-PDM" + } + ] + } + } + ] + } + ] +} diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index 55d87b218..ff65308f4 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -4,31 +4,38 @@ # Organization classifications -Many publishers wish to disclose and monitor information about different classifications of organizations involved in contracting (or planning) processes. Example classifications include organization ownership, incorporation, sector, location, and number of employees. We recognise that publishing information about a variety of organization characteristics, for example women-owned and/or indigenous-owned organizations, is an important part of monitoring participation in public procurement. +Tracking certain characteristics of organizations, for example whether an organization is women-owned and/or indigenous-owned, is an important part of monitoring participation in public procurement. Many publishers wish to disclose classifications of the organizations involved in contracting (or planning) processes. Examples of organization classifications include ownership, incorporation, sector, location, and number of employees. -Some organization classifications, such as organization scale, can be published using OCDS fields and codes. Many other classifications are context-specific, and for this case, we provide an organization classification extension that allows publishers to provide their own classifications. +## Organization scale -There are therefore two options that are encouraged for publishing organization classifications. +To classify an organization's scale, i.e. its size or number of employees, you ought to use the the `parties.details.scale` field and [party scale codelist](../../schema/codelists.md#party-scale). -1. For classifications that have become standardized, there are specific OCDS fields and codes that ought to be used. At present, this only applies to organization scale, which ought to be disclosed using the `parties.details.scale` field, using a code from the [party scale codelist](../../schema/codelists.md#party-scale). -1. For non-standardized options, such as classifying forms of organization ownership, publishers ought to use the [organization classification extension](https://extensions.open-contracting.org/en/extensions/organizationClassification/1.1/). This extension adds a [`classifications`](../../schema/reference.md#classification) array to the `parties.details` block to enable the categorization of organizations. Each `classification.id` field ought to contain a code from the particular scheme given in the `classification.scheme` field. Details about the particular organization characteristic that is being disclosed ought to be provided in the `classification.description` field. The given `classification.scheme` can be an existing scheme (drawn from the open [classificationScheme codelist](../../schema/codelists.md#classification-scheme)), or a local scheme for a particular publisher. In both cases, we encourage publishers to provide details of all schemes and classification codes used in their [publication policy](../publish.md#finalize-your-publication-policy), to help users understand the data. +## Other classifications -As fields become standardized through the use of option 2, the information can be migrated to _also_ be published via OCDS fields and codes as in option 1. Publishers can continue to publish the information in the organization classification extension to preserve backwards compatibility in data sets. +If your classification does not map to any OCDS fields or codes, you ought to use the [organization classification extension](https://extensions.open-contracting.org/en/extensions/organizationClassification/1.1/). The extension adds a [`classifications`](../../schema/reference.md#classification) array to the `parties.details` object. -A third, discouraged, example approach using local extensions is also given below, for situations where neither of the above two approaches apply to a specific use case. +A classification consists of at least two parts: an identifier for the list (scheme) from which the classification is taken, and an identifier for the category from that list being applied. It is useful to also publish a text label and/or URI that users can draw on to interpret the classification. + +If the list from which your classifications are taken is listed in the 'organization' category of the open [classificationScheme codelist](../../schema/codelists.md#classification-scheme), you ought to set `parties.details.classifications.scheme` to the scheme's code, e.g. "COFOG" for the [Classification of the Functions of Government](https://unstats.un.org/unsd/classifications/Econ/). Otherwise, you ought to assign your own 'scheme code' and prefix it with your country's [ISO-3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1) to reduce the risk of clashing with another publisher's code. + +In either case, your [publication policy](../publish.md#finalize-your-publication-policy) ought to explain the classification schemes and codes used in your data. + +```{admonition} Standardization and backwards compatibility +:class: note +Future versions of OCDS might add standardized fields like `parties.details.scale` to disclose classifications. If a new field matches the semantics of a classification that you already publish using the organization classifications extension, in order to preserve backwards compatibility, you can publish both the standardized field and the extension fields. +``` ## Worked examples -### Option 1: standardized options +### Organization scale -#### Organization scale +A publisher uses the [partyScale codelist](../../schema/codelists.md#party-scale) to classify organization scale. -In the example below, Moldova has disclosed information about the 'Companie mică' organization using the `parties.details.scale` field, to which it has assigned the 'micro' code from the [partyScale codelist](../../schema/codelists.md#party-scale). +A large organization, Microsoft, bids for an opportunity. `parties.details.scale` is set to 'large'. -```{jsoninclude} ../../examples/organizations/organization_classification/moldova_organization_scale.json -:jsonpointer: -:expand: releases, parties, details -:title: party_scale +```{jsoninclude} ../../examples/organizations/organization_classification/scale.json +:jsonpointer: /releases/0 +:expand: parties, details ``` ```{admonition} Party scale extension @@ -37,48 +44,45 @@ In the example below, Moldova has disclosed information about the 'Companie mic This example previously used the [party scale extension](https://extensions.open-contracting.org/en/extensions/partyScale/master/) for OCDS 1.1. That extension has been merged into OCDS 1.2. ``` -### Option 2: Organization classification extension - -In the examples below, two different publishers have disclosed information about organizations involved in their contracting processes. An organization classification needs to consist of at least two parts: an identifier for the list (scheme) from which the classification is taken, and an identifier for the category from that list being applied. It is useful to also publish a text label and/or URI that users can draw on to interpret the classification. In the first example below, the publisher re-uses an existing `classification.scheme`. In the second example below, where a publisher wishes to track specific policy-related data, a local list of categories is used in preference to mapping to a generic set. +### Other classifications: Common schemes -#### Classification schemes +A European Union publisher classifies buyers using the 'EU Type of contracting authority' scheme from the Tenders Electronic Daily (TED) schema. A buyer, the London Borough of Haringey, is classified as a regional or local authority. -Each `classification` block contains fields to provide information about the `description` (a textual description or title for the classification code), `id` (the classification code), `uri` (to uniquely identify the classification code) and `scheme`. The `scheme` value can be drawn from the open [classificationScheme codelist](../../schema/codelists.md#classification-scheme) (where the `Category` value is "organization"), or it can be a local scheme. Schemes are given to classify the activities of procuring authorities (i.e. procuring entities and/or buyers). +The organization classification extension is declared in the `extensions` array. The classification is modelled as a `Classification` object in `parties.details.classification` and: -Where an appropriate scheme is not listed in the [classificationScheme codelist](../../schema/codelists.md#classification-scheme), publishers can specify their own scheme. Publishers can either reuse an alternative scheme, or provide their own. Where publishers provide their own local schemes, they ought to prefix their `scheme` code with an [ISO-3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1) to preserve its global uniqueness. Details of this local scheme, and a list of possible codes, ought to be described in the [publication policy](../publish.md#finalize-your-publication-policy). +* `.scheme` is set to the scheme's code in the [classificationScheme codelist](../../schema/codelists.md#classification-scheme): "TED_CA_TYPE". +* `.id` is set to the code from TED schema: "REGIONAL_AUTHORITY". +* `.description` is set to the code's description from the TED schema: "Regional or local authority". -#### Example 2.1 disclosing data using existing schemes - -In the first fictional example below, the UK has disclosed a code from two different European Commission (EC) schemes, 'TED_CE_ACTIVITY' and 'TED_CA_TYPE' to classify the organization whose name is "London Borough of Haringey". Refer to the [classificationScheme codelist](../../schema/codelists.md#classification-scheme) for further details of these schemes. - -Note that the `classification.id` relates to the id of the code in the `classification.scheme` given, rather than its position in the `classifications` array. Therefore, the first `classification` shows that the `id` of 'Regional or local authority' in the 'TED_CA_TYPE' scheme is 'REGIONAL_AUTHORITY', and the second `classification` shows that the `id` of 'General public services' in the 'COFOG' scheme is '01'. - -```{jsoninclude} ../../examples/organizations/organization_classification/uk_organization_classification.json +```{jsoninclude} ../../examples/organizations/organization_classification/ted_buyer_type.json :jsonpointer: -:expand: releases, parties, details, classifications -:title: organization_classifications +:expand: releases, extensions, parties, details, classifications ``` -#### Example 2.2 disclosing data using a local scheme +### Other classifications: Local schemes + +A publisher in Colombia uses a local classification scheme to track the participation of women-owned businesses in procurement. A tenderer, Contadores de Medellín, is classified as women-owned. -The second example below is set in the fictional city of Ciudad Ficticia in Colombia. The procurement team wishes to monitor the participation of women-owned businesses in procurement according to specific policy priorities. The first organization declared in the `parties` array is a women-owned business, so they add a `classifications` array to it with just one `classification` object. In this object, the local `classification.scheme` is 'COL-CF-MON' and the `classification.id` is 'NPDM'. Note that the `classification.id` contains the relevant classification code from the given scheme, rather than being an internal identifier in the `classifications` array. +The organization classification extension is declared in the `extensions` array. The classification is modelled as a `Classification` object in `parties.details.classification` and: -In their publication policy, the procurement team documents all possible codes for COL-CF-MON with definitions of each code, including explaining that 'NPDM' is for businesses registered with the local Chamber of Commerce where ownership and control is at least 51% women. +* `.scheme` is set to the ISO-3166-1 alpha-3 country code for Colombia followed by an abbreviation of the classification scheme's name: "COL-AN-ME-PDM" +* `.id` is set to the code from the classification scheme: "NPDM". +* `.description` is set to the code's description from the classification scheme: "Negocio propiedad de mujeres". -```{jsoninclude} ../../examples/organizations/organization_classification/fictional_wob_organization_classification.json +```{jsoninclude} ../../examples/organizations/organization_classification/women_owned.json :jsonpointer: -:expand: releases, parties, details, classifications -:title: organization_classification +:expand: releases, extensions, parties, details, classifications ``` -### Option 3: Local extensions +The publisher's publication policy describes how the ownership of businesses is classified, including the meaning of the codes in the local classification scheme. + +> *Business ownership is classified using a local scheme, identified by "COL-AN-ME-PDM" in `parties.details.classifications.scheme`.* +> *The possible values of `parties.details.classifications.id` are:* +> * *NPDM: Negocio propiedad de mujeres (women-owned business)* -A third, discouraged, option is for publishers to use local extensions to disclose organization classification information. This option is discouraged because it is difficult for data users to compare organization classifications across multiple data sets that use many different approaches to disclosing similar information. However, in the absence of standardized options, where there is a specific use case for the data, this can be the most appropriate short-term option. Local extensions ought to document the structure and meaning of the additional fields they describe: please refer to the [extensions documentation](extensions). - -In the fictional example below, Dhanghadi has created a local extension so they can publish data in the `parties.details` block on an organization that is `femaleChaired`, with the values of the field being either `true` or `false`. The publisher would document the structure of this field and its meaning in the local extension files. +```{admonition} Mapping boolean data elements +:class: note +If you are mapping boolean data elements that describe characteristics of an organization, try to create logical groups of characteristics and create a local classification scheme for each group. It is allowed for a scheme to contain a single code. -```{jsoninclude} ../../examples/organizations/organization_classification/dhangadhi_female_chaired_example.json -:jsonpointer: -:expand: releases, parties, details -:title: femaleChaired +For example: The City of Boston's Department of Supplier Diversity defines minority-owned businesses (MBE), women-owned businesses (WBE) and small local business enterprises (SLBE), among others. Depending on your use cases, two logical groups might be ownership-based characteristics and location-based characteristics. Instead of three booleans, this information can be modelled as a USA-MA-BOS-OWNER scheme with 'MBE' and 'WBE' codes and a USA-MA-BOS-LOCATION scheme with an 'SLBE' code. ``` From 2b21b91d466a9746be862892ce7e6c622967e06a Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 18:27:07 +1300 Subject: [PATCH 27/36] docs/guidance/map/organizational_units.md: Remove extension example --- .../moldova_organization_extension.json | 74 ------------------- .../extension.json | 17 ----- .../release-schema.json | 20 ----- docs/guidance/map/organizational_units.md | 32 +------- 4 files changed, 2 insertions(+), 141 deletions(-) delete mode 100644 docs/examples/organizations/organizational_units/moldova_organization_extension.json delete mode 100644 docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json delete mode 100644 docs/examples/organizations/organizational_units/ocds_divisionCode_extension/release-schema.json diff --git a/docs/examples/organizations/organizational_units/moldova_organization_extension.json b/docs/examples/organizations/organizational_units/moldova_organization_extension.json deleted file mode 100644 index bf8b52d57..000000000 --- a/docs/examples/organizations/organizational_units/moldova_organization_extension.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "version": "1.1", - "extensions": [ - "https://raw.githubusercontent.com/open-contracting-extensions/ocds_budget_breakdown_extension/master/extension.json", - "https://standard.open-contracting.org/examples/extensions/ocds_divisionCode_extension/extension.json" - ], - "releases": [ - { - "ocid": "ocds-b3wdp1-MD-1539840280133", - "id": "ocds-b3wdp1-MD-1539840280133-1539840280205", - "date": "2018-10-18T05:24:39Z", - "tag": [ - "tender" - ], - "tender": { - "id": "ocds-b3wdp1-MD-1539840280133", - "title": "Piese consumabile pentru aparatele multifuncționale", - "description": "Livrarea timp de 30 zile", - "status": "active", - "value": { - "amount": 1400000.0, - "currency": "MDL" - }, - "procurementMethod": "open", - "mainProcurementCategory": "goods", - "hasEnquiries": false, - "items": [ - { - "id": "1", - "description": "Piese consumabile pentru aparatele multifuncționale", - "classification": { - "scheme": "CPV", - "id": "30100000-0", - "description": "Maşini, echipament şi accesorii de birou, cu excepţia computerelor, a imprimantelor şi a mobilierului" - } - } - ] - }, - "buyer": { - "id": "MD-IDNO-1006601001182", - "name": "National Bank of Moldova - Chişinău Branch" - }, - "parties": [ - { - "id": "MD-IDNO-1006601001182", - "name": "National Bank of Moldova - Chişinău Branch", - "identifier": { - "scheme": "MD-IDNO", - "id": "1006601001182", - "legalName": "National Bank of Moldova" - }, - "address": { - "streetAddress": "1 Grigore Vieru Avenue", - "locality": "Chişinău", - "region": "Chişinău", - "postalCode": "MD 2005", - "country": "MD" - }, - "contactPoint": { - "email": "official@bnm.md", - "telephone": "+373 22 822 606" - }, - "roles": [ - "payer", - "buyer" - ], - "details": { - "divisionCode": "101" - } - } - ] - } - ] -} diff --git a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json deleted file mode 100644 index 8c2e39f88..000000000 --- a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "name": { - "en": "Division codes" - }, - "description": { - "en": "Adds a divisionCode field to the Organization building block" - }, - "documentationUrl": { - "en": "http://github.com/example_publisher/ocds_division_code_extension" - }, - "schemas": [ - "release-schema.json" - ], - "compatibility": [ - "1.1" - ] -} diff --git a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/release-schema.json b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/release-schema.json deleted file mode 100644 index 875f7ed43..000000000 --- a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/release-schema.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "definitions": { - "Organization": { - "properties": { - "details": { - "properties": { - "divisionCode": { - "title": "Division code", - "description": "This field allows to provide a identifier for an organization's division or department involved in the contracting (or planning) process.", - "type": [ - "string", - "null" - ] - } - } - } - } - } - } -} diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index dd6721da4..4e59a80b9 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -21,7 +21,7 @@ Disclosing organizational hierarchies in OCDS is strongly discouraged unless the ## Worked examples -### 1. Using the Organization object +### Using the Organization object San Felipe Hospital in Honduras announces a planning process for the purchase of food supplies. The hospital is a unit of the Ministry of Health (Secretaría de Salud Pública) and is not a separate legal entity. @@ -38,35 +38,7 @@ The hospital is listed in the `parties` section and: :expand: parties, identifier, additionalIdentifiers ``` -### 2. Defining a new Extension - -In Moldova, the national procurement agency needs to include a division code for particular organizations. Since divisions can be separate legal entities in some cases, the publisher chooses to use the `identifier` block to point to the main organization for all cases, and use an additional field to provide the division code that enables data users to locate the departments and branches involved. - -In the release below, a branch of the Bank of Moldova announces a contract opportunity for the provision of consumables for electrical appliances. - -```{jsoninclude} ../../examples/organizations/organizational_units/moldova_organization_extension.json -:jsonpointer: -:expand: releases, parties, identifier, additionalIdentifiers, details -:title: release -``` - -```{jsoninclude} ../../examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json -:jsonpointer: -:expand: name, description, schemas, compatibility -:title: extension -``` - -```{jsoninclude} ../../examples/organizations/organizational_units/ocds_divisionCode_extension/release-schema.json -:jsonpointer: -:expand: definitions, Organization, properties, details, properties, divisionCode -:title: release-schema -``` - -The branch name (*Chişinău Branch*) is appended at the end of the name of the buyer. A new extension called "Division code" has been defined to add the `divisionCode` field in the `parties/details` section. The branch code in the example is "101". - -The `extension.json` and `release-schema.json` files for the Division code extension can be displayed using the combo box above the JSON example. Instructions on how to create an OCDS extension can be found [here](https://github.com/open-contracting/standard_extension_template). - -### 3. Publishing a separate organizational hierarchy dataset +### Publishing a separate organizational hierarchy dataset The Hospital Clinic (Hospital de Clínicas) in Paraguay is an organizational unit of the Faculty of Medical Sciences (Facultad de Ciencias Médicas) at the National University of Asuncion (Universidad Nacional de Asunción). The hospital is part of the same legal entity as the faculty, but the faculty is a separate legal entity from the university. From a5d6ad4022766db9904e74b4f0c16fdd2f16ca92 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 18:27:38 +1300 Subject: [PATCH 28/36] docs/examples/organizations/organization_classification: Remove unused example --- .../dhangadhi_female_chaired_example.json | 50 ------------------- 1 file changed, 50 deletions(-) delete mode 100644 docs/examples/organizations/organization_classification/dhangadhi_female_chaired_example.json diff --git a/docs/examples/organizations/organization_classification/dhangadhi_female_chaired_example.json b/docs/examples/organizations/organization_classification/dhangadhi_female_chaired_example.json deleted file mode 100644 index f0ffe7b8b..000000000 --- a/docs/examples/organizations/organization_classification/dhangadhi_female_chaired_example.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "extensions": [ - "https://raw.githubusercontent.com/publisher/ocds_femaleChaired_extension/v1.0/extension.json" - ], - "version": "1.1", - "releases": [ - { - "ocid": "ocds-213czf-IMS/1160", - "date": "2019-01-04T13:18:31+05:45", - "tag": [ - "award" - ], - "id": "ocds-213czf-IMS/1160-002-award", - "parties": [ - { - "name": "काल्पनिक महिला अध्यक्षता कम्पनी", - "id": "NP-CRO-UC-1160", - "identifier": { - "id": "UC-1160", - "scheme": "NP-CRO" - }, - "roles": [ - "supplier" - ], - "details": { - "femaleChaired": true - }, - "address": { - "streetAddress": "धनगढी ११", - "country": "NP" - } - } - ], - "awards": [ - { - "suppliers": [ - { - "name": "काल्पनिक महिला अध्यक्षता कम्पनी", - "id": "NP-CRO-UC-1160" - } - ], - "status": "active", - "date": "2019-01-01T00:00:00+05:45", - "id": "IMS/1160-awards/1", - "title": "धनगढी उदाहरण पुरस्कार" - } - ] - } - ] -} From 1636b812d7d104818da1c234632c85a80422c4e5 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 18:28:30 +1300 Subject: [PATCH 29/36] schema/codelists/releaseTag.csv: Remove reference to planning processes in 'tender' --- schema/codelists/releaseTag.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/codelists/releaseTag.csv b/schema/codelists/releaseTag.csv index 312542ea8..6c57dc003 100644 --- a/schema/codelists/releaseTag.csv +++ b/schema/codelists/releaseTag.csv @@ -1,7 +1,7 @@ Code,Title,Description planning,Planning,"Information about, for example, needs identification, budget planning and market research. This information concerns the planning process. This information typically concerns the period before contracting documents (for example, procurement documents) are available to potential suppliers." planningUpdate,Planning update,"Details of a proposed or planned contracting process are being updated. This might include addition of information and documents from consultation engagement activities, revised details or timelines for a proposed contracting process, or a tender.status update to indicate that a pipeline proposal has been withdrawn." -tender,Tender,"Information about, for example, the needed items and their estimated value, procurement method, award criteria, and various deadlines. This information concerns either the contracting process or the planning process. For a contracting process, this information typically concerns the period starting with contracting documents (for example, procurement documents) being available to potential suppliers and ending with the bid submission deadline. For a planning process, this information typically concerns the period before the contracting documents are available to potential suppliers." +tender,Tender,"Information about, for example, the needed items and their estimated value, procurement method, award criteria, and various deadlines. This information concerns the contracting process. This information typically concerns the period starting with contracting documents (for example, procurement documents) being available to potential suppliers and ending with the bid submission deadline." tenderAmendment,Tender amendment,"An amendment to an existing tender release. There should be at least one tender release with the same ocid, but an earlier release date, before a tenderAmendment is published. The term amendment has legal meaning in many jurisdictions." tenderUpdate,Tender update,"An update to an existing tender release. There should be at least one tender release with the same ocid, but an earlier release date, before a tenderUpdate is published. An update may add new information or make corrections to prior published information. It should not be used for formal legal amendments to a tender, for which the tenderAmendment tag should be used." tenderCancellation,Tender cancellation,"The cancellation of an existing tender. There should be at least one release with the same ocid, but an earlier release date, which provides details of the tender being cancelled." From 0d34b8a2705bb989f3447ec2b46610eaac6ef870 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 25 Mar 2024 18:29:33 +1300 Subject: [PATCH 30/36] docs/guidance/map/contracting_planning_processes.md: Use non-normative synonym --- docs/guidance/map/contracting_planning_processes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guidance/map/contracting_planning_processes.md b/docs/guidance/map/contracting_planning_processes.md index c5f359113..6ada707bd 100644 --- a/docs/guidance/map/contracting_planning_processes.md +++ b/docs/guidance/map/contracting_planning_processes.md @@ -24,7 +24,7 @@ OCDS defines a planning process as: ![Contracting Process](../../_static/png/contracting_process.png) -A planning process ought to have its `releaseTag` set to 'planning' (or 'planningUpdate'). A contracting process can have `releaseTag` set to [any other value from the codelist](../../schema/codelists.md#release-tag). A planning process should not contain the `releaseTag` 'tender' even if it contains a `tender` object. The two processes ought to be linked together using the `relatedProcesses` array in the releases for the contracting process, with the 'planning' code in the related process' `relationship` array. +A planning process ought to have its `releaseTag` set to 'planning' (or 'planningUpdate'). A contracting process can have `releaseTag` set to [any other value from the codelist](../../schema/codelists.md#release-tag). A planning process ought not contain the `releaseTag` 'tender' even if it contains a `tender` object. The two processes ought to be linked together using the `relatedProcesses` array in the releases for the contracting process, with the 'planning' code in the related process' `relationship` array. ```{note} We recommend publishing data about planning and contracting processes under separate `ocid`s, following the definitions above. That said, publications that combine planning and contracting data under a single `ocid` remain conformant in OCDS 1.2. A required separation can be considered for OCDS 2.0. From 0ce1660e130e48432d2cb056cac8c55a12ec8777 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 28 Mar 2024 11:56:51 +1300 Subject: [PATCH 31/36] docs/guidance/map/beneficial_ownership.md: Update examples --- docs/examples/beneficial_ownership/award.json | 23 ++-------------- .../beneficial_owners_extension.json | 20 ++------------ docs/guidance/map/beneficial_ownership.md | 27 +++++++------------ 3 files changed, 13 insertions(+), 57 deletions(-) diff --git a/docs/examples/beneficial_ownership/award.json b/docs/examples/beneficial_ownership/award.json index ad47007c2..3d92400d7 100644 --- a/docs/examples/beneficial_ownership/award.json +++ b/docs/examples/beneficial_ownership/award.json @@ -2,8 +2,8 @@ "version": "1.1", "releases": [ { - "ocid": "ocds-b5fd17-06bc003d-1b90-4148-80b0-ae1816dad552", - "id": "ocds-b5fd17-06bc003d-1b90-4148-80b0-ae1816dad552-441827-re21341", + "ocid": "ocds-213czf-0000", + "id": "1", "date": "2021-06-08T14:14:33Z", "tag": [ "award" @@ -18,25 +18,6 @@ }, "roles": [ "supplier" - ], - "address": { - "streetAddress": "Oak Works, Oak Lane, Kingswinford, West Midlands, DY6 7JW" - } - } - ], - "awards": [ - { - "id": "6031d3f9-f86b-462c-80b2-4a02c760ddcd", - "date": "2021-06-07T00:00:00Z", - "value": { - "amount": 32191, - "currency": "GBP" - }, - "suppliers": [ - { - "id": "GB-COH-00507062", - "name": "T.M. ENGINEERS (MIDLANDS) LIMITED" - } ] } ] diff --git a/docs/examples/beneficial_ownership/beneficial_owners_extension.json b/docs/examples/beneficial_ownership/beneficial_owners_extension.json index 08079e5c4..f1427c8d3 100644 --- a/docs/examples/beneficial_ownership/beneficial_owners_extension.json +++ b/docs/examples/beneficial_ownership/beneficial_owners_extension.json @@ -5,8 +5,8 @@ ], "releases": [ { - "ocid": "ocds-b3wdp1-MD-1602178295495", - "id": "ocds-b3wdp1-MD-1602178295495-EV-1602179847933-1603023717142", + "ocid": "ocds-213czf-0001", + "id": "1", "date": "2020-10-18T12:21:56Z", "tag": [ "award" @@ -31,22 +31,6 @@ } ] } - ], - "awards": [ - { - "id": "f867a510-0edf-11eb-a6ca-b5f4fa6e44dc", - "date": "2020-10-18T12:21:56Z", - "value": { - "amount": 56660, - "currency": "MDL" - }, - "suppliers": [ - { - "id": "MD-IDNO-2001100158022", - "name": "Microsoft Moldova" - } - ] - } ] } ] diff --git a/docs/guidance/map/beneficial_ownership.md b/docs/guidance/map/beneficial_ownership.md index afb0a0c81..c2d755cf5 100644 --- a/docs/guidance/map/beneficial_ownership.md +++ b/docs/guidance/map/beneficial_ownership.md @@ -47,25 +47,24 @@ The UK publishes separate contracting and beneficial ownership datasets. Both da ### Contracting data -The UK publishes OCDS data from [Contracts Finder](https://www.contractsfinder.service.gov.uk/). +A publisher in the United Kingdom collects [Companies House](https://www.gov.uk/government/organisations/companies-house) numbers as its primary organization identifiers for suppliers. -This example shows a contract award to T.M. ENGINEERS (MIDLANDS) LIMITED. `parties.identifier.id` is set to the supplier's company number (00507062) and `parties.identifier.scheme` is set to "GB-COH" to identify the register the number is drawn from. +A buyer awards a contract to T.M. ENGINEERS (MIDLANDS) LIMITED. The supplier is listed in the `parties` array with 'supplier' in `.roles`. `.identifier.scheme` is set to the org-id scheme prefix for Companies House ([GB-COH](http://org-id.guide/list/GB-COH)) and `.identifier.id` is set to the supplier's Companies House number (00507062). ```{note} For more information on publishing organization identifiers in OCDS, see [Organization identifiers](../../schema/identifiers.md#organization-identifiers). ``` ```{jsoninclude} ../../examples/beneficial_ownership/award.json -:jsonpointer: -:expand: releases, parties, identifier, awards, suppliers -:title: award +:jsonpointer: /releases/0 +:expand: releases, parties, identifier, roles ``` ### Beneficial ownership data -The UK also publishes a separate beneficial ownership dataset: the [People with significant control (PSC) snapshot](http://download.companieshouse.gov.uk/en_pscdata.html). This dataset is updated daily and includes a history of changes. The OpenOwnership Register publishes [the PSC snapshot in BODS format](https://register.openownership.org/data_sources/uk-psc-register). +The UK government publishes a separate beneficial ownership dataset, the [People with significant control (PSC) snapshot](http://download.companieshouse.gov.uk/en_pscdata.html), which is updated daily and includes a history of changes. Open Ownership publishes [the PSC snapshot in BODS format](https://register.openownership.org/data_sources/uk-psc-register). -This example shows the beneficial ownership data for the supplier from the contract award: T.M. ENGINEERS (MIDLANDS) LIMITED. +This example shows the BODS data for the supplier from the contract award: T.M. ENGINEERS (MIDLANDS) LIMITED. BODS is based on statements, where each statement describes ownership or control, entities, or natural persons. For more information, see the [BODS documentation](http://standard.openownership.org/). The example includes: @@ -93,19 +92,11 @@ BODS is based on statements, where each statement describes ownership or control ## Publish beneficial ownership data in OCDS -Moldova [collects the name and nationality](https://tender.gov.md/ro/content/formularul-standard-al-documentului-unic-de-achizi%C8%9Bii-european?fbclid=IwAR14CSxh6bo45cTq-hzVbwhnEkk9OEkY1aF86j1hVIU8kTnvaW3cU4q5loc) of the beneficial owners of bidders in its procurement system. But, Moldova does not maintain a separate beneficial ownership register. - -Therefore, Moldova can use the beneficial owners extension to publish the data in OCDS. For more information on using the beneficial ownership extension, see the [extension documentation](https://extensions.open-contracting.org/en/extensions/beneficialOwners/master/). - -This example shows a fictional contract award to Microsoft Moldova: +A publisher in Moldova collects the name and nationality of the beneficial owners of bidders in its procurement system. However, the government of Moldova does not publish a separate beneficial ownership dataset. Therefore, the publisher uses the [beneficial owners extension](https://extensions.open-contracting.org/en/extensions/beneficialOwners) to publish the data in OCDS. -* In the package metadata, the `extensions` array includes the beneficial owners extension. -* In the `parties` array: - * `beneficialOwners.name` is set to the name of the beneficial owner - * `beneficialOwners.nationality` is set to the country code for the nationality of the beneficial owner +A buyer awards a contract to Microsoft Moldova. The publisher declares the beneficial owners extension in the `extensions` array and publishes the name and nationality of the beneficial owner in `parties.beneficialOwners`. ```{jsoninclude} ../../examples/beneficial_ownership/beneficial_owners_extension.json :jsonpointer: -:expand: extensions, releases, parties, identifier, beneficialOwners -:title: beneficial-owners-extension +:expand: extensions, releases, parties, beneficialOwners ``` From 76f1ddb12e1a0bbb8bd976fd2e91026d968e74ac Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Wed, 27 Mar 2024 22:26:34 -0400 Subject: [PATCH 32/36] schema/records_reference: Use same wording as schema ("number sign") --- docs/schema/records_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/records_reference.md b/docs/schema/records_reference.md index 53b697c77..1b360ee42 100644 --- a/docs/schema/records_reference.md +++ b/docs/schema/records_reference.md @@ -64,7 +64,7 @@ The following example demonstrates the use of linked releases. Each release's `url` consists of two parts: * The URL of the release package that contains the release: `https://example.com/release_package.json` -* A fragment identifier (introduced by a hash mark #) whose value is the `id` of the release: `1`, `2` or `3` +* A fragment identifier (introduced by the number sign #) that is the `id` of the release: `1`, `2` or `3` Release `id` values are only required to be unique within the scope of a (contracting or planning) process: that is, within the scope of an `ocid` value. As such, a consuming application needs to use the fragment identifier in combination with the `ocid` of the record in order to identify the matching release within the release package. From 97bc0da5b2898f7a456d54c9ab3965b44def12bf Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Wed, 27 Mar 2024 23:16:05 -0400 Subject: [PATCH 33/36] examples: Consolidate awards_contracts examples into one directory --- .../contracts_pos.csv | 0 .../multi_award.json | 0 .../parent_contract.csv | 0 .../single_award.json | 0 docs/guidance/map/awards_contracts.md | 8 ++++---- 5 files changed, 4 insertions(+), 4 deletions(-) rename docs/examples/{purchase_orders => awards_contracts}/contracts_pos.csv (100%) rename docs/examples/{award_decisions => awards_contracts}/multi_award.json (100%) rename docs/examples/{purchase_orders => awards_contracts}/parent_contract.csv (100%) rename docs/examples/{award_decisions => awards_contracts}/single_award.json (100%) diff --git a/docs/examples/purchase_orders/contracts_pos.csv b/docs/examples/awards_contracts/contracts_pos.csv similarity index 100% rename from docs/examples/purchase_orders/contracts_pos.csv rename to docs/examples/awards_contracts/contracts_pos.csv diff --git a/docs/examples/award_decisions/multi_award.json b/docs/examples/awards_contracts/multi_award.json similarity index 100% rename from docs/examples/award_decisions/multi_award.json rename to docs/examples/awards_contracts/multi_award.json diff --git a/docs/examples/purchase_orders/parent_contract.csv b/docs/examples/awards_contracts/parent_contract.csv similarity index 100% rename from docs/examples/purchase_orders/parent_contract.csv rename to docs/examples/awards_contracts/parent_contract.csv diff --git a/docs/examples/award_decisions/single_award.json b/docs/examples/awards_contracts/single_award.json similarity index 100% rename from docs/examples/award_decisions/single_award.json rename to docs/examples/awards_contracts/single_award.json diff --git a/docs/guidance/map/awards_contracts.md b/docs/guidance/map/awards_contracts.md index eea392c66..539b42a1e 100644 --- a/docs/guidance/map/awards_contracts.md +++ b/docs/guidance/map/awards_contracts.md @@ -131,7 +131,7 @@ In Paraguay, a single award notice is used to disclose many award decisions. Det Using a single award object to model such a notice in OCDS would make it impossible to determine which items related to which suppliers or how much of the total award value related to each supplier: -```{jsoninclude} ../../examples/award_decisions/single_award.json +```{jsoninclude} ../../examples/awards_contracts/single_award.json :jsonpointer: /releases/0 :expand: awards, value, suppliers ``` @@ -140,7 +140,7 @@ For the award object in OCDS to communicate a direct relationship between items, There are no identifiers for the individual supplier/value pairings on the original award notice, so it is necessary to create a new identifier for each award object in OCDS. The approach to creating an identifier will depend on the properties of the dataset; for example, using the supplier's `.id`. -```{jsoninclude} ../../examples/award_decisions/multi_award.json +```{jsoninclude} ../../examples/awards_contracts/multi_award.json :jsonpointer: /releases/0 :expand: awards, value, suppliers ``` @@ -159,7 +159,7 @@ The UK's Department for Transport awards a £1.2m, 12-month contract to KPMG to ```{csv-table-no-translate} :header-rows: 1 -:file: ../../examples/purchase_orders/parent_contract.csv +:file: ../../examples/awards_contracts/parent_contract.csv ``` Calculating the sum of the contract value in the above example gives the correct result of £1.2m. @@ -170,7 +170,7 @@ If purchase orders were also disclosed in the `contracts` section of OCDS, by th ```{csv-table-no-translate} :header-rows: 1 -:file: ../../examples/purchase_orders/contracts_pos.csv +:file: ../../examples/awards_contracts/contracts_pos.csv ``` Calculating the sum of the contract value in the above example gives an incorrect result of £2.4m - double the actual value of the contract. From 4c5f24f9db9c50a28b77f39d7059a24bb13e8704 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Wed, 27 Mar 2024 23:34:16 -0400 Subject: [PATCH 34/36] docs(chore): Use "example" not "worked example" open-contracting/standard-development-handbook#274 --- docs/guidance/map/amendments.md | 2 +- docs/guidance/map/beneficial_ownership.md | 2 +- docs/guidance/map/framework_agreements.md | 2 +- docs/guidance/map/linked_standards.md | 2 +- docs/guidance/map/milestones.md | 6 +++--- docs/guidance/map/organization_classifications.md | 2 +- docs/guidance/map/organization_identifiers.md | 2 +- docs/guidance/map/organization_personal_identifiers.md | 2 +- docs/guidance/map/organizational_units.md | 2 +- docs/guidance/map/pre-qualification.md | 2 +- 10 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 877afd456..6fc598ec3 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -20,7 +20,7 @@ The nature of a change can be made explicit using: * **The amendments** fields (`tender.amendments`, `awards.amendments` and `contracts.amendments`), which are used to list amendments along with their rationales and references to the releases that contain "before" and "after" values. -## Worked examples +## Examples ### Example 1: Tender updates and amendments diff --git a/docs/guidance/map/beneficial_ownership.md b/docs/guidance/map/beneficial_ownership.md index c2d755cf5..bdf9589f2 100644 --- a/docs/guidance/map/beneficial_ownership.md +++ b/docs/guidance/map/beneficial_ownership.md @@ -4,7 +4,7 @@ # Beneficial ownership information -This worked example describes how to: +This example describes how to: * publish separate contracting and beneficial ownership datasets * publish beneficial ownership data using OCDS diff --git a/docs/guidance/map/framework_agreements.md b/docs/guidance/map/framework_agreements.md index a6f7352f3..127a9ae34 100644 --- a/docs/guidance/map/framework_agreements.md +++ b/docs/guidance/map/framework_agreements.md @@ -149,7 +149,7 @@ The following guidance describes how to model the different stages of a framewor * Add an `Organization` object to the `parties` array, add 'supplier' to its `.roles` and populate its other fields. * Add an `OrganizationReference` object to the award's `.suppliers` array and set `.id` and `.name` to match the supplier's object in the `parties` array. -## Worked examples +## Examples The following examples show how to model two framework agreements, covering a range of characteristics: diff --git a/docs/guidance/map/linked_standards.md b/docs/guidance/map/linked_standards.md index 654e927f0..1847b7524 100644 --- a/docs/guidance/map/linked_standards.md +++ b/docs/guidance/map/linked_standards.md @@ -16,4 +16,4 @@ The [Open Fiscal Data Package](https://www.fiscaltransparency.net/open-fiscal-da ## Beneficial Ownership Data Standard -The [Beneficial Ownership Data Standard](https://standard.openownership.org/en/0.2.0/) (BODS) provides a structured data format for collecting, sharing and using data on beneficial ownership. The [beneficial ownership worked example](beneficial_ownership) describes how to connect OCDS and BODS datasets. +The [Beneficial Ownership Data Standard](https://standard.openownership.org/en/0.2.0/) (BODS) provides a structured data format for collecting, sharing and using data on beneficial ownership. The [beneficial ownership example](beneficial_ownership) describes how to connect OCDS and BODS datasets. diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index bb23dac91..6fe4a77af 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -39,9 +39,9 @@ The `dueDate`, `dateMet`, `dateModified` and [`status`](../../schema/codelists.m To represent a planned payment, add a `Milestone`, set its `.type` to 'payment' and set its `.value` to the payment's value. Once the milestone is met, add a [Transaction](../../schema/reference.md#transaction) to `contracts/implementation/transactions`. For implementation milestones, the transaction can refer back to the milestone using the [transaction-related milestones extension](https://extensions.open-contracting.org/en/extensions/transaction_milestones/master/). -## Worked examples +## Examples -The following worked examples show how milestones are modelled. +The following examples show how milestones are modelled. ### Planning milestones @@ -56,7 +56,7 @@ Because the approval relates to a planning process, it is modelled as a mileston ### Delivery milestones -This worked example shows how delivery milestones are modelled. +This example shows how delivery milestones are modelled. #### Implementation release diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index ff65308f4..119c51d80 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -25,7 +25,7 @@ In either case, your [publication policy](../publish.md#finalize-your-publicatio Future versions of OCDS might add standardized fields like `parties.details.scale` to disclose classifications. If a new field matches the semantics of a classification that you already publish using the organization classifications extension, in order to preserve backwards compatibility, you can publish both the standardized field and the extension fields. ``` -## Worked examples +## Examples ### Organization scale diff --git a/docs/guidance/map/organization_identifiers.md b/docs/guidance/map/organization_identifiers.md index 583143a58..15867ca92 100644 --- a/docs/guidance/map/organization_identifiers.md +++ b/docs/guidance/map/organization_identifiers.md @@ -13,7 +13,7 @@ To disclose an organization identifier, first, use [org-id.guide](http://org-id. If you choose not to register an organization list with org-id.guide, you ought to describe the list in a [publication policy](../publish.md#finalize-your-publication-policy), and select a prefix that is not in use by another list in org-id.guide, by following the [org-id meta-data guide](http://docs.org-id.guide/en/latest/metadata/#assigning-a-code). -## Worked example +## Example A publisher in the United Kingdom collects [Companies House](https://www.gov.uk/government/organisations/companies-house) numbers as its primary organization identifiers for suppliers. diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index a3e8b7884..1eaf52fb2 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -22,7 +22,7 @@ To construct a `scheme` value for a personal identifier, follow the [guidance](h > the scheme should have the pattern {JURISDICTION}-{TYPE} where JURISDICTION is an uppercase ISO 3166-1 alpha-3 country code and TYPE is one of PASSPORT, TAXID or IDCARD -## Worked example +## Example A publisher in Colombia collects national ID card numbers as identifiers for natural persons who are tenderers or suppliers. diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index 4e59a80b9..35dd7343b 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -19,7 +19,7 @@ If the fields in the `Organization` object are not sufficient to express your da Disclosing organizational hierarchies in OCDS is strongly discouraged unless there is a clear use case to support it. Ideally, organizational hierarchies ought to be represented in separate, non-OCDS datasets that use the same organization and unit identifiers. To design a hierarchy-oriented dataset, refer to the [W3C Organization Ontology](https://www.w3.org/TR/vocab-org/). However, if you need to represent organizational hierarchies in OCDS, you can use the [memberOf extension](https://github.com/open-contracting-extensions/ocds_memberOf_extension). -## Worked examples +## Examples ### Using the Organization object diff --git a/docs/guidance/map/pre-qualification.md b/docs/guidance/map/pre-qualification.md index 2be6cfda9..f2cb67ed9 100644 --- a/docs/guidance/map/pre-qualification.md +++ b/docs/guidance/map/pre-qualification.md @@ -13,7 +13,7 @@ But, many jurisdictions also use multi-stage procedures. Such procedures follow :file: ../../examples/pre-qualification/multi-stage.csv ``` -This worked example describes 3 types of multi-stage procedure and explains how to model them in OCDS. +This example describes 3 types of multi-stage procedure and explains how to model them in OCDS. ## Definitions From 6f058dc3016660664e4c00a39bd44e7aa757c306 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 29 Mar 2024 12:07:05 +1300 Subject: [PATCH 35/36] docs/guidance/build/serialization.md: Update examples --- docs/examples/serialization/flat.csv | 2 -- docs/examples/serialization/flat.json | 17 ---------------- .../examples/serialization/flat_two_items.csv | 4 ++-- .../serialization/flat_two_items.json | 20 ++++++++++++++----- docs/guidance/build/serialization.md | 8 ++++---- 5 files changed, 21 insertions(+), 30 deletions(-) delete mode 100644 docs/examples/serialization/flat.csv delete mode 100644 docs/examples/serialization/flat.json diff --git a/docs/examples/serialization/flat.csv b/docs/examples/serialization/flat.csv deleted file mode 100644 index 8314bbe9b..000000000 --- a/docs/examples/serialization/flat.csv +++ /dev/null @@ -1,2 +0,0 @@ -ocid,tag,tender/id,tender/items/id,tender/items/description -ocds-a2ef3d01-1594121,tender,ocds-a2ef3d01-1594121/1,1,Standards development diff --git a/docs/examples/serialization/flat.json b/docs/examples/serialization/flat.json deleted file mode 100644 index b41ea3cc3..000000000 --- a/docs/examples/serialization/flat.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "releases": [ - { - "ocid": "ocds-a2ef3d01-1594121", - "tag": "tender", - "tender": { - "id": "ocds-a2ef3d01-1594121/1", - "items": [ - { - "id": "1", - "description": "Standards development" - } - ] - } - } - ] -} diff --git a/docs/examples/serialization/flat_two_items.csv b/docs/examples/serialization/flat_two_items.csv index 8b7210cbc..652c516b6 100644 --- a/docs/examples/serialization/flat_two_items.csv +++ b/docs/examples/serialization/flat_two_items.csv @@ -1,2 +1,2 @@ -ocid,tag,tender/id,tender/items/0/id,tender/items/0/description,tender/items/1/id,tender/items/1/description -ocds-a2ef3d01-1594121,tender,ocds-a2ef3d01-1594121/1,1,Standards development,2,Documentation authoring +ocid,id,date,tag,tender/id,tender/title,tender/value/amount,tender/value/currency,tender/items/0/id,tender/items/0/description,tender/items/1/id,tender/items/1/description +ocds-213czf-0000,1,2024-01-01T00:00:00Z,tender,1,Purchase of office supplies,6000,USD,1,Paper,2,Ink diff --git a/docs/examples/serialization/flat_two_items.json b/docs/examples/serialization/flat_two_items.json index 8a2712d7f..0f54c4d42 100644 --- a/docs/examples/serialization/flat_two_items.json +++ b/docs/examples/serialization/flat_two_items.json @@ -1,18 +1,28 @@ { + "version": "1.1", "releases": [ { - "ocid": "ocds-a2ef3d01-1594121", - "tag": "tender", + "ocid": "ocds-213czf-0000", + "id": "1", + "date": "2024-01-01T00:00:00Z", + "tag": [ + "tender" + ], "tender": { - "id": "ocds-a2ef3d01-1594121/1", + "id": "1", + "title": "Purchase of office supplies", + "value": { + "amount": 6000, + "currency": "USD" + }, "items": [ { "id": "1", - "description": "Standards development" + "description": "Paper" }, { "id": "2", - "description": "Documentation authoring" + "description": "Ink" } ] } diff --git a/docs/guidance/build/serialization.md b/docs/guidance/build/serialization.md index 64d2492b3..7a11cbfb2 100644 --- a/docs/guidance/build/serialization.md +++ b/docs/guidance/build/serialization.md @@ -40,16 +40,16 @@ In each case, fields are identified in CSV headers by their [JSON Pointer](https **JSON** -```{jsoninclude} ../../examples/serialization/flat.json -:jsonpointer: -:expand: releases, tender, items +```{jsoninclude} ../../examples/primer/primer.json +:jsonpointer: /releases/0 +:expand: tag, tender, value ``` **CSV** ```{csv-table-no-translate} :header-rows: 1 -:file: ../../examples/serialization/flat.csv +:file: ../../examples/primer/primer.csv ``` [Beta open source tooling](https://flatten-tool.readthedocs.io/en/latest/usage-ocds/) exists for generating flat CSV OCDS templates, and converting in both directions between JSON spreadsheets following these templates. The OCDS Data Review Tool incorporates this tooling and will offer to convert files uploaded to it. From 9dc21611f7f69ce566e224b00e98427c74d6e598 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Wed, 27 Mar 2024 23:57:30 -0400 Subject: [PATCH 36/36] examples: Remove empty extensions array --- docs/examples/organizations/identifiers.json | 1 - docs/examples/organizations/organization_reference.json | 1 - docs/examples/organizations/personal_identifier.json | 1 - 3 files changed, 3 deletions(-) diff --git a/docs/examples/organizations/identifiers.json b/docs/examples/organizations/identifiers.json index 08b164c93..e876955a4 100644 --- a/docs/examples/organizations/identifiers.json +++ b/docs/examples/organizations/identifiers.json @@ -1,6 +1,5 @@ { "version": "1.1", - "extensions": [], "releases": [ { "ocid": "ocds-213czf-0000", diff --git a/docs/examples/organizations/organization_reference.json b/docs/examples/organizations/organization_reference.json index 1a1588d49..6cfc6a65d 100644 --- a/docs/examples/organizations/organization_reference.json +++ b/docs/examples/organizations/organization_reference.json @@ -1,6 +1,5 @@ { "version": "1.1", - "extensions": [], "releases": [ { "ocid": "ocds-213czf-000-00001", diff --git a/docs/examples/organizations/personal_identifier.json b/docs/examples/organizations/personal_identifier.json index 51c47427b..a817f5dc1 100644 --- a/docs/examples/organizations/personal_identifier.json +++ b/docs/examples/organizations/personal_identifier.json @@ -1,6 +1,5 @@ { "version": "1.1", - "extensions": [], "releases": [ { "ocid": "ocds-213czf-0000",