From c1eed65a8a2c23a7ca9368ac08caadc6e88e7072 Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 12 Nov 2024 15:27:02 +0000 Subject: [PATCH 1/4] reference.md: add contracting and processing definitions --- docs/schema/reference.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 698b4754c..af0be2b9c 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -2,7 +2,7 @@ The [Release Schema](release) provides a detailed specification of the fields and data structures to use when publishing contracting data. Supplementary schemas show how to combine releases into release packages and how to compile releases into records. -Releases are immutable – presenting information about a particular event in the lifetime of a contracting (or planning) process. Publishers must not edit a release after publication; a new release can be created by changing the release's `id` and `date`. +Releases are immutable – presenting information about a particular event in the lifetime of a [contracting (or planning) process](#contracting-and-planning-processes). Publishers must not edit a release after publication; a new release can be created by changing the release's `id` and `date`. Releases must be published within a [release package](packaging/release_package). @@ -14,9 +14,29 @@ Releases must be published within a [release package](packaging/release_package) This page presents the release schema in tables, with additional information in paragraphs. You can also download the canonical version of the release schema as [JSON Schema](../../build/current_lang/release-schema.json), download it as a [CSV spreadsheet](../../build/current_lang/release-schema.csv), view it in an [interactive browser](release), or access it through the [Field-Level Mapping Template](https://www.open-contracting.org/resources/ocds-field-level-mapping-template/). ``` +## Contracting and planning processes + +OCDS recognizes two types of processes: contracting processes and planning processes. In OCDS, a given process is uniquely identified by an [open contracting process identifier](identifiers.md#open-contracting-process-identifier-ocid) (`ocid`). + +OCDS defines a contracting process as: + +% Align the two blockquotes with the top-level `description` field of the `release-schema.json` file. + +> All the actions aimed at implementing one or more contracts. This covers tendering, awarding, contracting and implementation. It does not include actions linked to planning, as these are often less structured and may be linked to multiple contracting processes. In multi-stage procedures (for example, framework agreements with reopening of competition), each round of competition is treated as a separate contracting process. +> +> Procedures that failed and were restarted are considered new processes. +> +> Boundaries between processes (for example, whether two contracts result from a single process or from two processes) are set by buyers depending on their needs (for example, efficient division of labor, clear communication with the market) and legislation (for example, rules on using procedures and lots). + +OCDS defines a planning process as: + +> All the actions aimed at planning one or more contracting processes. This covers, for example, need identification, budget planning, and market research. +> +> Planning processes are often less structured than contracting processes, so one or more planning processes may lead to one or more contracting processes. + ## Release handling -The full OCDS data model is based on the idea of publishing a new release every time information about a contracting (or planning) process changes. This way, users can gain a full view of change over time, and third-parties can understand what needs to be updated in any system that is tracking the progress of a contracting (or planning) process. +The full OCDS data model is based on the idea of publishing a new release every time information about a [contracting (or planning) process](#contracting-and-planning-processes) changes. This way, users can gain a full view of change over time, and third-parties can understand what needs to be updated in any system that is tracking the progress of a contracting (or planning) process. Publishers will need to choose how to generate new releases, and whether to repeat information in each release, or just to provide changes. This choice ought to be based on an understanding of the [merging process](merging) that is used to generate a snapshot record of a full contracting (or planning) process. @@ -56,7 +76,7 @@ For example, a publisher announcing the signing of a contract with a 'contract' ### Release -All new information about a contracting (or planning) process is described within a release. +All new information about a [contracting (or planning) process](#contracting-and-planning-processes) is described within a release. ````{admonition} Example :class: hint @@ -148,7 +168,7 @@ The planning section is used in a planning process. This includes information ab #### Budget -Apart from documents, the majority of planning information is held within the budget block. This is designed to allow both machine-readable linkable data about budgets, cross-referencing to data held in other standards such as the [Fiscal Data Package](https://specs.frictionlessdata.io/fiscal-data-package/) or [International Aid Transparency Initiative Standard](https://iatistandard.org/en/), and human readable description of the related budgets and projects, supporting users to understand the relationship of the contracting (or planning) process to existing projects and budgets even where linked data is not available. +Apart from documents, the majority of planning information is held within the budget block. This is designed to allow both machine-readable linkable data about budgets, cross-referencing to data held in other standards such as the [Fiscal Data Package](https://specs.frictionlessdata.io/fiscal-data-package/) or [International Aid Transparency Initiative Standard](https://iatistandard.org/en/), and human readable description of the related budgets and projects, supporting users to understand the relationship of the [contracting (or planning) process](#contracting-and-planning-processes) to existing projects and budgets even where linked data is not available. ````{admonition} Example :class: hint @@ -409,7 +429,7 @@ See the [parties](#parties) section. #### Identifier -The identifier block provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. +The identifier block provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a [contracting (or planning) process](#contracting-and-planning-processes). When describing an organizational unit (for example, a department or branch of an organization), the `identifier` field should identify the main organization. The other fields should describe the organizational unit. For more information, see [organizational units](../guidance/map/organizational_units.md). @@ -463,7 +483,7 @@ When describing an organizational unit (for example, a department or branch of a Documents can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each document block can consist of multiple documents, classified using the [documentType](codelists.md#document-type) codelist. -Documents related to contracting (or planning) processes should be public by default. For more information, see the Open Contracting Partnership's report [Mythbusting Confidentiality in Public Contracting](https://www.open-contracting.org/resources/mythbusting-confidentiality-public-contracting/) and the Center for Global Development's [Principles on Commercial Transparency in Public Contracts](https://www.cgdev.org/publication/principles-commercial-transparency-public-contracts). +Documents related to [contracting (or planning) process](#contracting-and-planning-processes) should be public by default. For more information, see the Open Contracting Partnership's report [Mythbusting Confidentiality in Public Contracting](https://www.open-contracting.org/resources/mythbusting-confidentiality-public-contracting/) and the Center for Global Development's [Principles on Commercial Transparency in Public Contracts](https://www.cgdev.org/publication/principles-commercial-transparency-public-contracts). Documents should be published at their own stable URLs, accessible for free and without the need to search or login, and available at the time of publication of the OCDS release that refers to them. From 84e7a9ef40e8199e52cbf83006915d20a41395b8 Mon Sep 17 00:00:00 2001 From: odscjen Date: Mon, 18 Nov 2024 10:30:04 +0000 Subject: [PATCH 2/4] release-schema: update tag description and reference doc --- docs/guidance/map/contracting_planning_processes.md | 2 +- docs/schema/reference.md | 12 +++++++++++- schema/dereferenced-release-schema.json | 2 +- schema/release-schema.json | 2 +- 4 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/guidance/map/contracting_planning_processes.md b/docs/guidance/map/contracting_planning_processes.md index 0ab6e8af1..4024c01cf 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 needs to have 'planning' (or 'planningUpdate') added to its `tag` array. A contracting process can have [any other value from the codelist](../../schema/codelists.md#release-tag) in its `tag` array. A planning process must not contain the code 'tender' in its `tag` array 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. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index af0be2b9c..ee7303a4b 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -16,7 +16,7 @@ This page presents the release schema in tables, with additional information in ## Contracting and planning processes -OCDS recognizes two types of processes: contracting processes and planning processes. In OCDS, a given process is uniquely identified by an [open contracting process identifier](identifiers.md#open-contracting-process-identifier-ocid) (`ocid`). +OCDS recognizes two types of processes: contracting processes and planning processes. OCDS defines a contracting process as: @@ -34,6 +34,16 @@ OCDS defines a planning process as: > > Planning processes are often less structured than contracting processes, so one or more planning processes may lead to one or more contracting processes. +Planning and contracting processes should be linked using the [`relatedProcesses`](#relatedprocess) 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. +``` + +```{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](../guidance/map/framework_agreements) and for [pre-qualification and pre-selection](../guidance/map/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). +``` + ## Release handling The full OCDS data model is based on the idea of publishing a new release every time information about a [contracting (or planning) process](#contracting-and-planning-processes) changes. This way, users can gain a full view of change over time, and third-parties can understand what needs to be updated in any system that is tracking the progress of a contracting (or planning) process. diff --git a/schema/dereferenced-release-schema.json b/schema/dereferenced-release-schema.json index f71c5592f..d0a1767c0 100644 --- a/schema/dereferenced-release-schema.json +++ b/schema/dereferenced-release-schema.json @@ -69,7 +69,7 @@ }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields.", + "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist may indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", "type": "array", "items": { "type": "string" diff --git a/schema/release-schema.json b/schema/release-schema.json index 46f3ea6d8..efb5b1d78 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -33,7 +33,7 @@ }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. Planning processes must not use the 'tender' code, even if they use `tender` fields.", + "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist may indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", "type": "array", "items": { "type": "string" From e21128f8b7de38987b248bc90a68888a9523c5a9 Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Tue, 19 Nov 2024 16:22:07 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Duncan Dewhurst --- docs/schema/reference.md | 2 +- schema/release-schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index ee7303a4b..262979d49 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -16,7 +16,7 @@ This page presents the release schema in tables, with additional information in ## Contracting and planning processes -OCDS recognizes two types of processes: contracting processes and planning processes. +OCDS recognizes two types of processes: contracting processes and planning processes. In OCDS, a given process is uniquely identified by an [open contracting process identifier](identifiers.md#open-contracting-process-identifier-ocid) (`ocid`). OCDS defines a contracting process as: diff --git a/schema/release-schema.json b/schema/release-schema.json index efb5b1d78..ec74eb106 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -33,7 +33,7 @@ }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist may indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", + "description": "A tag labeling the release, using the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", "type": "array", "items": { "type": "string" From 50ccf02b692e494b0cc060ff4c7788e40463a639 Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 19 Nov 2024 16:28:54 +0000 Subject: [PATCH 4/4] apply review suggestions --- docs/guidance/map.md | 1 - .../map/contracting_planning_processes.md | 35 ------------------- docs/schema/codelists.md | 1 - schema/dereferenced-release-schema.json | 2 +- 4 files changed, 1 insertion(+), 38 deletions(-) delete mode 100644 docs/guidance/map/contracting_planning_processes.md diff --git a/docs/guidance/map.md b/docs/guidance/map.md index c30bcdf6f..a36f335d1 100644 --- a/docs/guidance/map.md +++ b/docs/guidance/map.md @@ -97,7 +97,6 @@ Mapping data to OCDS is not always obvious. Please refer to our how-to guides an :maxdepth: 2 :titlesonly: -map/contracting_planning_processes map/unsuccessful_processes map/framework_agreements map/pre-qualification diff --git a/docs/guidance/map/contracting_planning_processes.md b/docs/guidance/map/contracting_planning_processes.md deleted file mode 100644 index 4024c01cf..000000000 --- a/docs/guidance/map/contracting_planning_processes.md +++ /dev/null @@ -1,35 +0,0 @@ -```{workedexample} Contracting processes and planning processes -:tags: planning -``` - -# Contracting processes and planning processes - -OCDS recognizes two types of processes: contracting processes and planning processes. In OCDS, a given process is uniquely identified by an [open contracting process identifier](../../schema/identifiers.md#open-contracting-process-identifier-ocid) (`ocid`). This section helps map your contracting activities (most often procurement procedures) to their OCDS representation. - -OCDS defines a contracting process as: - -% Align the two blockquotes with the top-level `description` field of the `release-schema.json` file. - -> All the actions aimed at implementing one or more contracts. This covers tendering, awarding, contracting and implementation. It does not include actions linked to planning, as these are often less structured and may be linked to multiple contracting processes. In multi-stage procedures (e.g. framework agreements with reopening of competition), each round of competition is treated as a separate contracting process. -> -> Procedures that failed and were restarted are considered new processes. -> -> Boundaries between processes (e.g. whether two contracts result from a single process or from two processes) are set by buyers depending on their needs (e.g. efficient division of labor, clear communication with the market) and legislation (e.g. rules on using procedures and lots). - -OCDS defines a planning process as: - -> All the actions aimed at planning one or more contracting processes. This covers, for example, need identification, budget planning, and market research. -> -> Planning processes are often less structured than contracting processes, so one or more planning processes may lead to one or more contracting processes. - -![Contracting Process](../../_static/png/contracting_process.png) - -A planning process needs to have 'planning' (or 'planningUpdate') added to its `tag` array. A contracting process can have [any other value from the codelist](../../schema/codelists.md#release-tag) in its `tag` array. A planning process must not contain the code 'tender' in its `tag` array 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. -``` - -```{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). -``` diff --git a/docs/schema/codelists.md b/docs/schema/codelists.md index bd3dc7bc6..2292f4b04 100644 --- a/docs/schema/codelists.md +++ b/docs/schema/codelists.md @@ -129,7 +129,6 @@ Added 'parent'. Deprecated 'subContract', 'replacementProcess' and 'renewalProce ``` ```{seealso} -* [Map: Contracting processes and planning processes](../guidance/map/contracting_planning_processes.md) * [Map: Framework agreements](../guidance/map/framework_agreements.md) ``` diff --git a/schema/dereferenced-release-schema.json b/schema/dereferenced-release-schema.json index d0a1767c0..3de3c3ddf 100644 --- a/schema/dereferenced-release-schema.json +++ b/schema/dereferenced-release-schema.json @@ -69,7 +69,7 @@ }, "tag": { "title": "Release Tag", - "description": "A tag labeling the release, using the the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist may indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", + "description": "A tag labeling the release, using the open [releaseTag](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#release-tag) codelist. Tags distinguish, for example, planning and contracting processes and the stages of contracting processes. Codes outside the releaseTag codelist might indicate, for example, the notice or form to which the release corresponds, or the event that triggered the publication of the release. A planning process must use either the 'planning' or 'planningUpdate' code, and must not use any other code from the releaseTag codelist. A contracting process should not use the 'planning' or 'planningUpdate' codes.", "type": "array", "items": { "type": "string"