From d562edb187f8f67d91f6c9eec3e3872a26feef41 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 9 Oct 2023 11:32:06 +1300 Subject: [PATCH 1/6] docs: Fix spelling errors --- docs/guidance/build.md | 2 +- docs/guidance/map/organization_classifications.md | 2 +- docs/guidance/map/pre-qualification.md | 2 +- docs/guidance/publish.md | 4 ++-- docs/schema/reference.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guidance/build.md b/docs/guidance/build.md index 34666beb3..e88c1d29b 100644 --- a/docs/guidance/build.md +++ b/docs/guidance/build.md @@ -115,7 +115,7 @@ Contact the [Data Support Team](../support/index) for guidance on customizing a **Resource:** To learn about how to create a spreadsheet input template for OCDS, check out our blog series on prototyping OCDS data using spreadsheets ([Part 1](https://www.open-contracting.org/2020/04/24/prototyping-ocds-data-using-spreadsheets/), [Part 2](https://www.open-contracting.org/2020/05/11/prototyping-ocds-data-using-spreadsheets-part-ii/), [Part 3](https://www.open-contracting.org/2020/05/28/prototyping-ocds-data-using-spreadsheets-part-iii/)). ```{note} -Re-using tools isn't always easy. [Tool Re-Use in Open Contracting: A Primer](https://www.open-contracting.org/resources/tool-re-use-in-open-contracting-a-primer/) is a step-by-step guide to help you determine what you need, evaluate which tool is the right fit, and evaluate whether the right conditions are in place for successful re-use of a tool. +Re-using tools isn't always easy. [Tool Re-Use in Open Contracting: A Primer](https://www.open-contracting.org/resources/tool-re-use-in-open-contracting-a-primer/) is a step-by-step guide to help you determine what you need, evaluate which tool is the right fit, and evaluate whether the right conditions are in place for successful reuse of a tool. ``` ## Build your extensions diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index d1b6810f5..1726bcf4c 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -35,7 +35,7 @@ In the examples below, two different publishers have disclosed information about 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 [itemClassificationScheme codelist](../../schema/codelists.md#item-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). -Where an appropriate scheme is not listed in the [itemClassificationScheme codelist](../../schema/codelists.md#item-classification-scheme), publishers can specify their own scheme. Publishers can either re-use 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). +Where an appropriate scheme is not listed in the [itemClassificationScheme codelist](../../schema/codelists.md#item-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). #### Example 2.1 disclosing data using existing schemes diff --git a/docs/guidance/map/pre-qualification.md b/docs/guidance/map/pre-qualification.md index 610129b12..848fa40d7 100644 --- a/docs/guidance/map/pre-qualification.md +++ b/docs/guidance/map/pre-qualification.md @@ -150,7 +150,7 @@ The procuring entity will invite a maximum of 5 qualified potential suppliers to ## Example: Pre-qualification in Paraguay -The Ministry of Public Works and Communications issues an [invitation for 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 re-use the list of pre-qualified suppliers established as a result of this first procedure. +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 invitation represents the initiation of a contracting process to establish a list of pre-qualified suppliers, so it is modelled using the `tender` section in OCDS. diff --git a/docs/guidance/publish.md b/docs/guidance/publish.md index 9dd313e3d..1624665d8 100644 --- a/docs/guidance/publish.md +++ b/docs/guidance/publish.md @@ -33,9 +33,9 @@ The publication policy ought to also contain information about future plans for ## License your data -Publishing data under an open license is an important part of open contracting. Without this, restrictions on re-use can prevent many of the important [use cases](design/user_needs) for open contracting information being realized. +Publishing data under an open license is an important part of open contracting. Without this, restrictions on reuse can prevent many of the important [use cases](design/user_needs) for open contracting information being realized. -A license statement sets out the permission that users have to access, use and re-use the data. This can take the form of a [Public Domain Dedication or Certification](https://creativecommons.org/publicdomain/) which transfers a dataset into the public domain, or re-asserts that there are no existing copyrights or database rights inherent in the dataset (which is the case for government datasets in some jurisdictions), or the application of a license which sets out the terms under which a dataset can be re-used. +A license statement sets out the permission that users have to access, use and reuse the data. This can take the form of a [Public Domain Dedication or Certification](https://creativecommons.org/publicdomain/) which transfers a dataset into the public domain, or re-asserts that there are no existing copyrights or database rights inherent in the dataset (which is the case for government datasets in some jurisdictions), or the application of a license which sets out the terms under which a dataset can be re-used. We encourage the use of either a public domain dedication/certification, or an attribution only license. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index a0fb37270..9d7926037 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -228,7 +228,7 @@ Information on subcontracts is not currently included in the core OCDS schema, b :collapse: providerOrganization,receiverOrganization,amount,payer,payee,value ``` -The transaction block is modelled on the [International Aid Transparency Initiative (IATI) transaction element](https://iatistandard.org/en/iati-standard/203/activity-standard/iati-activities/iati-activity/transaction/), and can be used to represent actual flows of money between organizations in relation to this contract. As with the [budget](#budget) block, this can be used to cross-reference to a third party `source` of data, and ought to re-use identifiers from that source. +The transaction block is modelled on the [International Aid Transparency Initiative (IATI) transaction element](https://iatistandard.org/en/iati-standard/203/activity-standard/iati-activities/iati-activity/transaction/), and can be used to represent actual flows of money between organizations in relation to this contract. As with the [budget](#budget) block, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. In most circumstances, the `payer` identifier will match that of the `buyer`, and the `payee` identifier will match that of the `supplier`. From 72d13ceed3a4ac6fb6ceeb0401c76ab0621341e5 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 9 Oct 2023 11:33:34 +1300 Subject: [PATCH 2/6] docs/guidance/build.md: Fix spelling error --- docs/guidance/build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guidance/build.md b/docs/guidance/build.md index e88c1d29b..10e78aaea 100644 --- a/docs/guidance/build.md +++ b/docs/guidance/build.md @@ -115,7 +115,7 @@ Contact the [Data Support Team](../support/index) for guidance on customizing a **Resource:** To learn about how to create a spreadsheet input template for OCDS, check out our blog series on prototyping OCDS data using spreadsheets ([Part 1](https://www.open-contracting.org/2020/04/24/prototyping-ocds-data-using-spreadsheets/), [Part 2](https://www.open-contracting.org/2020/05/11/prototyping-ocds-data-using-spreadsheets-part-ii/), [Part 3](https://www.open-contracting.org/2020/05/28/prototyping-ocds-data-using-spreadsheets-part-iii/)). ```{note} -Re-using tools isn't always easy. [Tool Re-Use in Open Contracting: A Primer](https://www.open-contracting.org/resources/tool-re-use-in-open-contracting-a-primer/) is a step-by-step guide to help you determine what you need, evaluate which tool is the right fit, and evaluate whether the right conditions are in place for successful reuse of a tool. +Re-using tools isn't always easy. [Tool Reuse in Open Contracting: A Primer](https://www.open-contracting.org/resources/tool-re-use-in-open-contracting-a-primer/) is a step-by-step guide to help you determine what you need, evaluate which tool is the right fit, and evaluate whether the right conditions are in place for successful reuse of a tool. ``` ## Build your extensions From c52d0ec1ef494177d7ee91dde37c8927965ea330 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Wed, 21 Feb 2024 10:13:35 -0500 Subject: [PATCH 3/6] build/hosting: Clarify subject --- docs/guidance/build/hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guidance/build/hosting.md b/docs/guidance/build/hosting.md index c905b7530..e4da5308c 100644 --- a/docs/guidance/build/hosting.md +++ b/docs/guidance/build/hosting.md @@ -138,7 +138,7 @@ In either case: * Use `limit=NUMBER`, to limit the number of results returned on each page. * Include the total number of results across all pages. -In addition to performance reasons, the seek method is preferred to the offset method when results are ordered in reverse chronology, because: +In addition to performance reasons, the seek method is preferred to the offset method when results are ordered in reverse chronology, because, with the offset method: * A given page won't return the same results over time. `page=1` will return different results today, next week, and next year. * Users can receive duplicate results while paginating. For example, if a new release is published to page 1 while users are paginating, then the result at the bottom of each page will be moved to the top of the following page. From 36d8bbfbdba77dabdcc799384b21001cbf08d1f0 Mon Sep 17 00:00:00 2001 From: Yohanna Lisnichuk Date: Mon, 17 Jun 2024 15:42:28 -0400 Subject: [PATCH 4/6] guidance/publish/quality: update basic and contunuous improvement criteria To match the new OCP MEL definitions --- docs/guidance/publish/quality.md | 45 ++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/guidance/publish/quality.md b/docs/guidance/publish/quality.md index a782cf5d3..b983b13c0 100644 --- a/docs/guidance/publish/quality.md +++ b/docs/guidance/publish/quality.md @@ -36,7 +36,8 @@ All OCDS publications ought to meet the following criteria: 1. **Reviewable**: The [OCDS Data Review Tool](https://standard.open-contracting.org/review/) is able to report results on the data. 1. **Appropriate**: Concepts are published in semantic accordance with the rules of the OCDS (or registered extensions) rather than using a non-OCDS field or code. 1. **Active**: For each publisher, there is an OCDS release with a top-level `date` field value within the last 12 months. -1. **Parity**: For each publisher, for the _time period_ and _buyers_ covered by the data, there isn’t another dataset by the same publisher that covers more than 25% more contracting processes. +1. **Representative**: It describes all contracting processes within a relevant population. For example: all contracts for a public-private partnership; all above-threshold contracts since 2020 excluding those by state-owned enterprises, etc. +1. **Relevant**: Whether at least 1 contracting process answers "who bought what from whom, for how much, when, and how". The Data Support Team is happy to review draft and newly published OCDS data and can work with publishers with advice to meet the above criteria. A publication that does not meet this minimum threshold will not be listed as a publisher by OCP as part of [OCP’s regular reporting](https://www.open-contracting.org/why-open-contracting/learning/). @@ -48,31 +49,43 @@ From the minimum threshold above, we want to support publishers to continue to i Improvement on the below indicators demonstrate that the published information is becoming more complete about the contracting processes within the publisher’s jurisdiction. +1. Increase the number of indicators covered (volume) +1. Increase the average coverage of fields per compiled release, for example either new fields not previously published in any release, or an increase in the use of a field across releases (e.g. very little data was published about direct awards and now more is being published about direct awards) (density) +1. Increase the number of buyers covered in the publication ("who") +1. Increase the number of methods covered in the publication ("how") 1. Publish subsequent releases per OCID to show how the contracting process is progressing over time -1. Increase the publication of historical information (based on a minimal set of date fields that appear across all sources, e.g. `tender.tenderPeriod`, `awards.date`, and `contracts.dateSigned`) -1. Increase the average coverage of fields per compiled release, for example either new fields not previously published in any release, or an increase in the use of a field across releases (e.g. very little data was published about direct awards and now more is being published about direct awards) -1. Increase the number of buyers covered in the publication -1. Increase the number of concepts covered relative to non-OCDS data +1. Increase the temporal coverage into the past (based on a minimal set of date fields that appear across all sources, e.g. `tender.tenderPeriod`, `awards.date`, and `contracts.dateSigned`) ("when") + +### Timeliness + +1. Publish multiple updates per contracting process +1. Decrease the delay between the information’s creation and publication + +### Accessibility + +Improvements on the below indicators demonstrate that it is becoming easier for users to access the published information. + +1. Publish a user guide or publication policy that describes the scope, at minimum +1. Publish API documentation that describes the endpoints and parameters, at minimum +1. Increase the number of access methods (API endpoints, bulk downloads) +1. Increase the number of data formats (JSON, Excel, CSV) +1. Facilitate indirect data use (e.g. search, dashboards, etc.) + +### Retrievability and legal + +1. Decrease the number of HTTP errors +1. Use a data license that conforms to the [Open Definition](https://opendefinition.org) ### Correctness Improvement on the below indicators demonstrates that the concepts are being published more correctly, improving usability. 1. Decrease the types and number of structural errors reported by the OCDS Data Review Tool, e.g. moving from 20 types of errors, each occurring more than 100,000 times, to 10 types of errors, each occurring less than 100 times -1. Decrease the average number of structural errors per release -1. Decrease the number of instances in which a concept is not published in conformance with OCDS semantics +1. Decrease the average number of structural errors per contracting process +1. Decrease the number of conformance issues 1. Decrease the number of types of quality warnings using OCDS Pelican 1. Decrease the average number of quality warnings per release using OCDS Pelican -### Access - -Improvements on the below indicators demonstrate that it is becoming easier for users to access the published information. - -1. Publish record packages containing compiled releases -1. Decrease the number of HTTP errors -1. Increase the number of access methods (API endpoints, bulk downloads) -1. Decrease the number of license restrictions - As publishers improve, the Data Support Team can work with them to identify how they can improve on the above criteria. OCP will note whether a publisher has improved in [OCP’s regular reporting](https://www.open-contracting.org/why-open-contracting/learning/). ## Advanced criteria From eb114b9718a94242346406cfb538516b54ab0a8c Mon Sep 17 00:00:00 2001 From: Yohanna Lisnichuk Date: Mon, 17 Jun 2024 15:51:27 -0400 Subject: [PATCH 5/6] changelog: record #1697 --- docs/history/changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/history/changelog.md b/docs/history/changelog.md index db4b7304c..1b8857e6b 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -49,6 +49,7 @@ Per the [normative and non-normative content and changes policy](https://docs.go * [#1414](https://github.com/open-contracting/standard/pull/1414) Remove the planning section from Easy releases and Change history. * [#1494](https://github.com/open-contracting/standard/pull/1497) Add guidance on preparing test data to Check your data section. * Publish: + * [#1697](https://github.com/open-contracting/standard/pull/1697) Update the Basic Criteria and Continuous improvement to match the OCP's new MEL definitions. * Merge Publication policy and Licensing pages into Publish page [#986](https://github.com/open-contracting/standard/pull/986) [#1012](https://github.com/open-contracting/standard/pull/1012). * Replace guidance on publication levels [#980](https://github.com/open-contracting/standard/pull/980) [#1013](https://github.com/open-contracting/standard/pull/1013) [#1045](https://github.com/open-contracting/standard/pull/1045). * [#1427](https://github.com/open-contracting/standard/pull/1427) Add guidance about recommended extensions. From 78f188c8ada33d8f5e85bd6d6b2bbba4c3bbece3 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Fri, 28 Jun 2024 18:18:00 -0400 Subject: [PATCH 6/6] guidance/publish/quality: Better align wording with MEL --- docs/guidance/publish/quality.md | 30 +++++++++++++++--------------- docs/history/changelog.md | 4 ++-- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/guidance/publish/quality.md b/docs/guidance/publish/quality.md index b983b13c0..6e79403c3 100644 --- a/docs/guidance/publish/quality.md +++ b/docs/guidance/publish/quality.md @@ -31,13 +31,13 @@ Understanding all of the challenges above, we understand that increasing the tra All OCDS publications ought to meet the following criteria: 1. **Registered**: The data uses a [registered OCID prefix](../../schema/identifiers.md#contracting-process-identifier-ocid). +1. **Reviewable**: The [OCDS Data Review Tool](https://standard.open-contracting.org/review/) can report results for the data. +1. **Appropriate**: The data is in semantic accordance with OCDS. Additional fields and codes do not overlap semantically with standardized fields and codes. +1. **Relevant**: The data answers "who bought what from whom, for how much, when, and how" for at least one contracting process. 1. **Discoverable**: It is possible to discover the data by navigating a website whose homepage is indexed by popular web search engines. -1. **Retrievable**: It is possible to automate the download of all the data, either using an HTML page listing bulk download URLs, or using only machine-readable data as input. -1. **Reviewable**: The [OCDS Data Review Tool](https://standard.open-contracting.org/review/) is able to report results on the data. -1. **Appropriate**: Concepts are published in semantic accordance with the rules of the OCDS (or registered extensions) rather than using a non-OCDS field or code. -1. **Active**: For each publisher, there is an OCDS release with a top-level `date` field value within the last 12 months. -1. **Representative**: It describes all contracting processes within a relevant population. For example: all contracts for a public-private partnership; all above-threshold contracts since 2020 excluding those by state-owned enterprises, etc. -1. **Relevant**: Whether at least 1 contracting process answers "who bought what from whom, for how much, when, and how". +1. **Representative**: The data describes all contracting processes within a relevant population. For example: all contracts for a public-private partnership; all above-threshold contracts since 2020 excluding those by state-owned enterprises, etc. +1. **Active**: The data contains a contracting process release with a top-level `date` value within the previous four calendar quarters. +1. **Retrievable**: It is possible for software to download the data in full, either by using an HTML page listing bulk download URLs, or by using machine-readable data as the only input. The Data Support Team is happy to review draft and newly published OCDS data and can work with publishers with advice to meet the above criteria. A publication that does not meet this minimum threshold will not be listed as a publisher by OCP as part of [OCP’s regular reporting](https://www.open-contracting.org/why-open-contracting/learning/). @@ -50,16 +50,16 @@ From the minimum threshold above, we want to support publishers to continue to i Improvement on the below indicators demonstrate that the published information is becoming more complete about the contracting processes within the publisher’s jurisdiction. 1. Increase the number of indicators covered (volume) -1. Increase the average coverage of fields per compiled release, for example either new fields not previously published in any release, or an increase in the use of a field across releases (e.g. very little data was published about direct awards and now more is being published about direct awards) (density) -1. Increase the number of buyers covered in the publication ("who") -1. Increase the number of methods covered in the publication ("how") +1. Increase the average number of fields covered per contracting process (density) +1. Increase the number of buyers covered ("who") +1. Increase the number of methods covered ("how") 1. Publish subsequent releases per OCID to show how the contracting process is progressing over time -1. Increase the temporal coverage into the past (based on a minimal set of date fields that appear across all sources, e.g. `tender.tenderPeriod`, `awards.date`, and `contracts.dateSigned`) ("when") +1. Increase the temporal coverage into the past ("when") ### Timeliness 1. Publish multiple updates per contracting process -1. Decrease the delay between the information’s creation and publication +1. Decrease the delay between the information's creation and publication ### Accessibility @@ -80,11 +80,11 @@ Improvements on the below indicators demonstrate that it is becoming easier for Improvement on the below indicators demonstrates that the concepts are being published more correctly, improving usability. -1. Decrease the types and number of structural errors reported by the OCDS Data Review Tool, e.g. moving from 20 types of errors, each occurring more than 100,000 times, to 10 types of errors, each occurring less than 100 times +1. Decrease the number of types of structural errors 1. Decrease the average number of structural errors per contracting process -1. Decrease the number of conformance issues -1. Decrease the number of types of quality warnings using OCDS Pelican -1. Decrease the average number of quality warnings per release using OCDS Pelican +1. Decrease the number of [conformance](../../schema/conformance_and_extensions) issues +1. Decrease the number of types of quality warnings +1. Decrease the average number of quality warnings per contracting process As publishers improve, the Data Support Team can work with them to identify how they can improve on the above criteria. OCP will note whether a publisher has improved in [OCP’s regular reporting](https://www.open-contracting.org/why-open-contracting/learning/). diff --git a/docs/history/changelog.md b/docs/history/changelog.md index 1b8857e6b..de29b17fd 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -49,9 +49,9 @@ Per the [normative and non-normative content and changes policy](https://docs.go * [#1414](https://github.com/open-contracting/standard/pull/1414) Remove the planning section from Easy releases and Change history. * [#1494](https://github.com/open-contracting/standard/pull/1497) Add guidance on preparing test data to Check your data section. * Publish: - * [#1697](https://github.com/open-contracting/standard/pull/1697) Update the Basic Criteria and Continuous improvement to match the OCP's new MEL definitions. * Merge Publication policy and Licensing pages into Publish page [#986](https://github.com/open-contracting/standard/pull/986) [#1012](https://github.com/open-contracting/standard/pull/1012). - * Replace guidance on publication levels [#980](https://github.com/open-contracting/standard/pull/980) [#1013](https://github.com/open-contracting/standard/pull/1013) [#1045](https://github.com/open-contracting/standard/pull/1045). + * Replace publication levels guidance with data quality guidance [#980](https://github.com/open-contracting/standard/pull/980) [#1013](https://github.com/open-contracting/standard/pull/1013). + * Update data quality guidance to match [OCP Strategy 2024-2030](https://www.open-contracting.org/strategy-2024-2030/) [#1045](https://github.com/open-contracting/standard/pull/1045) [#1697](https://github.com/open-contracting/standard/pull/1697). * [#1427](https://github.com/open-contracting/standard/pull/1427) Add guidance about recommended extensions. * Various minor improvements [#1051](https://github.com/open-contracting/standard/pull/1051) [#1080](https://github.com/open-contracting/standard/pull/1080) [#1083](https://github.com/open-contracting/standard/pull/1083) [#1085](https://github.com/open-contracting/standard/pull/1085) [#1091](https://github.com/open-contracting/standard/pull/1091) [#1130](https://github.com/open-contracting/standard/pull/1130) [#1227](https://github.com/open-contracting/standard/pull/1227) [#1299](https://github.com/open-contracting/standard/pull/1299) [#1337](https://github.com/open-contracting/standard/pull/1337) [#1384](https://github.com/open-contracting/standard/pull/1384).