From 9276a143a3890bc6852cb64dcbe16344d5dd3183 Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 17 Nov 2023 15:50:41 +0000 Subject: [PATCH 01/17] remove mention of building blocks and blocks from documentation --- docs/guidance/build/merging.md | 4 +-- docs/guidance/build/system_architectures.md | 2 +- docs/guidance/map/amendments.md | 10 +++---- docs/guidance/map/extensions.md | 2 +- docs/guidance/map/milestones.md | 10 +++---- .../map/organization_classifications.md | 6 ++-- .../map/organization_personal_identifiers.md | 2 +- docs/guidance/map/organization_reference.md | 2 +- docs/guidance/map/organizational_units.md | 12 ++++---- docs/guidance/map/unsuccessful_processes.md | 4 +-- docs/primer/releases_and_records.md | 2 +- docs/schema/codelists.md | 4 +-- docs/schema/reference.md | 30 +++++++++---------- 13 files changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/guidance/build/merging.md b/docs/guidance/build/merging.md index 76921a3fb..3752b354d 100644 --- a/docs/guidance/build/merging.md +++ b/docs/guidance/build/merging.md @@ -93,9 +93,9 @@ Another government agency in Colombia publishes a new procurement opportunity. D A few days after releasing the tender notice, the government agency receives feedback for potential bidders, and they realize that the estimated contract period set for the tender could be infeasible. They decide to instead negotiate the contract period with the supplier, and they remove the contract period from the opportunity to avoid confusing potential bidders. -A release with a 'tenderAmendment' tag is published, in which both the `startDate` and `endDate` of the `contractPeriod` block have been set to `null`. Also, an `amendments` block is provided to explain the changes. +A release with a 'tenderAmendment' tag is published, in which both the `startDate` and `endDate` of the `contractPeriod` object have been set to `null`. Also, an `amendments` object is provided to explain the changes. -The final record is shown below. Note that the fields in the `contractPeriod` block have disappeared in the `compiledRelease`, and the `versionedRelease` contains the previous values. +The final record is shown below. Note that the fields in the `contractPeriod` object have disappeared in the `compiledRelease`, and the `versionedRelease` contains the previous values. ```{jsoninclude} ../../examples/merging/deletions/object_tender.json :jsonpointer: diff --git a/docs/guidance/build/system_architectures.md b/docs/guidance/build/system_architectures.md index 1f55d19fb..50846c7cb 100644 --- a/docs/guidance/build/system_architectures.md +++ b/docs/guidance/build/system_architectures.md @@ -74,7 +74,7 @@ This approach puts the burden of data conversion on data sources. Yet it might b This approach might also be suitable to combine data from many data sources. Each source becomes an OCDS publisher. The middleware becomes less complex since it only ingests data in a single format. -The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses OCDS building blocks as the foundation for data sources' data models. +The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses OCDS sub-schema as the foundation for data sources' data models. A variant in this scenario is to store files in a web-accessible file system, as shown below. A periodical invocation of the conversion module updates the file system. diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 32c126d9e..0af245537 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -18,7 +18,7 @@ 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 amendments** building block. This can contain an array of amendment explanations, and clearly identify the releases that contain before and after values. +* **The amendments** object. This can contain an array of amendment explanations, and clearly identify the releases that contain before and after values. ## Worked examples @@ -48,7 +48,7 @@ Weeks later, the publisher expands the `description` of the tender to provide mo #### Tender Amendment -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. +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` object 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. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/2 @@ -58,7 +58,7 @@ 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. +A full record is provided below, with all the releases for the process and a `compiledRelease` and `versionedRelease`. The `versionedRelease` object reflects all the changes made in the tender. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: @@ -72,7 +72,7 @@ It is encouraged to [download](../../examples/amendments/tender.json) the record 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 amendments object does not contain data on what was changed**. Changes are recorded by updating the fields of the `tender` object 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. @@ -96,7 +96,7 @@ See the JSON release below. #### 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. +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` object and the value of the contract is increased. A `amendments` object is included to explain the rationale of the changes. See the example release below. diff --git a/docs/guidance/map/extensions.md b/docs/guidance/map/extensions.md index 70e537d16..110196953 100644 --- a/docs/guidance/map/extensions.md +++ b/docs/guidance/map/extensions.md @@ -1,6 +1,6 @@ # Extensions -OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [building blocks](../../schema/reference.md#building-block-reference) for describing contracting (or planning) processes. +OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [objects](../../schema/reference.md#object-reference) for describing contracting (or planning) processes. Many publishers will have additional data that they could publish. Instead of ignoring this data and leaving it unpublished, OCDS encourages publishers to collaborate on the creation of **extensions** to the standard. diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index c2de80451..ee3e0ec6c 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -8,27 +8,27 @@ Milestones can be included within the planning, tender, contract and contract im ## Planning -The planning milestones block is used for two types of milestones: +The planning milestones object 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 -populate the tender milestones block instead. +populate the tender milestones object instead. ## Tender -The tender milestones block is used to describe two types of milestone: +The tender milestones object is used to describe two types of milestone: * Key dates in the tender and award stages which are not covered by other fields, for example, the date by which procuring entity will respond to enquiries. * Anticipated milestones during the contract implementation stage, for example, the date by which goods need to be delivered. ## Contract -The contract milestones block is used to describe: +The contract milestones object is used to describe: * Events related to the signing of the contract, for example, the date of commercial close in a PPP contract. ## Contract Implementation -The contract implementation milestones block is used to describe: +The contract implementation milestones object 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. diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index 55d87b218..65a4be562 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -11,7 +11,7 @@ Some organization classifications, such as organization scale, can be published There are therefore two options that are encouraged for publishing organization classifications. 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. +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` sub-schema 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. 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. @@ -43,7 +43,7 @@ In the examples below, two different publishers have disclosed information about #### Classification schemes -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). +Each `classification` object 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). 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). @@ -75,7 +75,7 @@ In their publication policy, the procurement team documents all possible codes f 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. +In the fictional example below, Dhanghadi has created a local extension so they can publish data in the `parties.details` sub-schema 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. ```{jsoninclude} ../../examples/organizations/organization_classification/dhangadhi_female_chaired_example.json :jsonpointer: diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index 13d9399ef..30b4c321e 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -11,7 +11,7 @@ Details of natural persons can be disclosed using the `parties` section in OCDS * The natural person is a tenderer or supplier; and * The laws in your jurisdiction permit the publication of such details -Subject to the above, you can disclose identifiers for natural persons using the `Identifier` building block. +Subject to the above, you can disclose identifiers for natural persons using the `Identifier` sub-schema. There are two components to an identifier in OCDS: diff --git a/docs/guidance/map/organization_reference.md b/docs/guidance/map/organization_reference.md index 9578bd169..4b5a828e5 100644 --- a/docs/guidance/map/organization_reference.md +++ b/docs/guidance/map/organization_reference.md @@ -16,7 +16,7 @@ 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. +* If a user looks at the `tenderers` object 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 diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index 1d5a276fc..9717a566c 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -8,20 +8,20 @@ For some use cases, publishers might need to disclose the organizational units i There is more than one approach to model organizational units in OCDS: -1. **Use the fields and blocks available in the Organization building block**. This is the preferred approach, when possible. +1. **Use the fields and objects available in the Organization sub-schema**. This is the preferred approach, when possible. * 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. + * The `address` and `contactPoint` objects can be filled with the unit information. * Unit identifiers can also be appended to `parties/id`. -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. +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 sub-schema. 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. ## Worked examples -### 1. Using the Organization building block +### 1. Using the Organization sub-schema 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. @@ -37,7 +37,7 @@ An identifier for the hospital has been added using the "HN-ONCAE-UNIT" list cod ### 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 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` object 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. @@ -63,7 +63,7 @@ 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. Using the Organization sub-schema with an organizational hierarchy 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. diff --git a/docs/guidance/map/unsuccessful_processes.md b/docs/guidance/map/unsuccessful_processes.md index 3ce997497..7457352b7 100644 --- a/docs/guidance/map/unsuccessful_processes.md +++ b/docs/guidance/map/unsuccessful_processes.md @@ -22,7 +22,7 @@ The first data disclosed is about the planning process. Planning data includes a :title: unsuccessful-tender-planning ``` -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'. +Next, the contracting process is disclosed, using a new `ocid`, 'ocds-03ad3f-331547-1'. The `relatedProcess` object links the planning process and the contracting process, with the relationship set to 'planning'. The tender was unsuccessful, so the tender's `status` is set to ‘unsuccessful’. @@ -40,7 +40,7 @@ To construct an `ocid` for the second contracting process, Paraguay adds a conse Paraguay could also have used the identifier for the second tender as the `ocid` for the second contracting process. -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’. +The `relatedProcesses` object 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/related_process.json :jsonpointer: diff --git a/docs/primer/releases_and_records.md b/docs/primer/releases_and_records.md index 4a1b7b3d3..debdb902d 100644 --- a/docs/primer/releases_and_records.md +++ b/docs/primer/releases_and_records.md @@ -38,7 +38,7 @@ Each time a new release is published it is added to the index, the compiled rele ![A contracting (or planning) process is described by many releases, which are aggregated into a single record](../_static/png/change_history_process_record.png) -Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out standard building blocks for items across releases, including the name of the item, a description, each item’s value, and the currency used. +Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out standard sub-schema for items across releases, including the name of the item, a description, each item’s value, and the currency used. When you publish OCDS releases and records, you are encouraged to: diff --git a/docs/schema/codelists.md b/docs/schema/codelists.md index 02d796dab..b2ce33ff9 100644 --- a/docs/schema/codelists.md +++ b/docs/schema/codelists.md @@ -121,7 +121,7 @@ The submission method codelist is used to identify the mechanism through which a ```{versionadded} 1.1 ``` -The related process block is used at the release level to point backwards to prior processes, such as planning or framework establishment, and at the contract level to point onwards to subcontracts or to renewal or replacement processes. The related process codelist determines the kind of relationship that is being described. +The related process object is used at the release level to point backwards to prior processes, such as planning or framework establishment, and at the contract level to point onwards to subcontracts or to renewal or replacement processes. The related process codelist determines the kind of relationship that is being described. ```{csv-table-no-translate} :header-rows: 1 @@ -145,7 +145,7 @@ The related process scheme describes the kind of identifier used to cross-refere ```{versionadded} 1.1 ``` -The milestone block can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. +The milestone object can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. ```{csv-table-no-translate} :header-rows: 1 diff --git a/docs/schema/reference.md b/docs/schema/reference.md index d9c14e891..535f6f179 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -78,7 +78,7 @@ The majority of OCDS data is held within a release structure. One or more releas A release has a [tag](codelists.md#release-tag) to indicate whether it is about a planning process or a contracting process and, if it is about the latter, to indicate the stage of the contracting process to which it relates. However, there are no formal restrictions on when information about a stage of the process can be provided. -For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the award and tender blocks in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. +For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the award and tender objects in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. ### Release @@ -174,7 +174,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 object. 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. ````{admonition} Example :class: hint @@ -228,7 +228,7 @@ The [Bid statistics and details](https://extensions.open-contracting.org/en/exte ### Award -The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. A related award block is required for every contract block, as the award contains information on the suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). +The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. A related award object is required for every contract object, as the award contains information on the suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). ````{admonition} Example :class: hint @@ -280,7 +280,7 @@ The contract section is used to provide details of contracts that have been ente ### Implementation -Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. Implementation blocks include the following elements: +Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. Implementation objects include the following elements: ````{admonition} Example :class: hint @@ -322,7 +322,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 reuse identifiers from that source. +The transaction object 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) object, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. ```{note} To represent planned payments, use [Milestones](#milestones) instead. @@ -350,7 +350,7 @@ See [document](#document) reference below. A release may amend values from a previous release. Whilst the release & record model of OCDS offers the opportunity to keep a full versioned history of changes, in many cases it is important for changes to a tender, award or contract to be explicitly declared. -The amendment array in a tender, award or contract block provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. +The amendment array in a tender, award or contract objects provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. ````{admonition} Example :class: hint @@ -381,9 +381,9 @@ Structured information on the former value of specific fields may be provided in See the [amendment implementation guidance](../guidance/map/amendments) for more details. ``` -## Building block reference +## Sub-schema reference -The following building blocks are commonly re-used throughout the standard. +The following sub-schema are commonly re-used throughout the standard. ### OrganizationReference @@ -415,7 +415,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 object provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. 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). @@ -467,7 +467,7 @@ When describing an organizational unit (for example, a department or branch of a ### Document -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 can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each document object 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). @@ -539,7 +539,7 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The items block is used to list the line-items associated with a tender, award or contract. +The items object is used to list the line-items associated with a tender, award or contract. ````{admonition} Example :class: hint @@ -561,7 +561,7 @@ The items block is used to list the line-items associated with a tender, award o #### Unit -The `unit` block allows detailed specification of the parameters and price of units that make up a line-item. +The `unit` object allows detailed specification of the parameters and price of units that make up a line-item. If the [Quantities, Units, Dimensions and Data Types Ontologies](https://www.qudt.org) unit classification scheme is used, then publishers can use its CamelCase unit names, such as "SquareMile", in the `unit.name` field. @@ -599,7 +599,7 @@ Other unit classification schemes can be used, including those in the [unitClass ### Milestone -Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) blocks. +Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` either updated, or re-confirmed. @@ -666,7 +666,7 @@ In OCDS each contracting process can have only one tender stage. There are a num * When a contract results in the award of sub-contracts - and those sub-contracts are also tracked using OCDS; * When a contract is coming up for renewal or replacement, and there is a contracting process to award the renewal/replacement contract; -In all these cases, the `relatedProcess` block should be used to cross-reference between the relevant contracting processes using their `ocid`. +In all these cases, the `relatedProcess` object should be used to cross-reference between the relevant contracting processes using their `ocid`. ````{admonition} Example :class: hint @@ -687,7 +687,7 @@ A related process can be declared at two points in an OCDS release. **(2) At the contract level** - used to point onward to sub-contracts, renewal or replacement processes that relate solely to the particular contract the field appears in. -As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant `documents` blocks. For example: +As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant `documents` objects. For example: * When recording a `release/relatedProcess` pointing to the ocid of the planning process that resulted in a tender, a `tender/documents` entry with a `documentType` of 'procurementPlan' and a link to web pages about the procurement plan could be provided; * When recording a `contract/relatedProcess` pointing to the ocid of a sub-contracting process, a `contract/documents` entry with a `documentType` of 'subContract' and a title that describes it as the subcontracting process, could be provided; From ebac7d424a97cc95ae3c50e7e244ac075b747573 Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 17 Nov 2023 16:00:32 +0000 Subject: [PATCH 02/17] update changelog.md --- docs/history/changelog.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/history/changelog.md b/docs/history/changelog.md index cfb316b33..d94310858 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -310,6 +310,7 @@ Per the [normative and non-normative content and changes policy](../governance/n * [#1643](https://github.com/open-contracting/standard/pull/1643) Update identifier section in release reference. * [#1655](https://github.com/open-contracting/standard/pull/1655) Rewrite identifiers reference and examples for clarity. * [#1659](https://github.com/open-contracting/standard/pull/1659) Add `Record` definition schema table to record reference. +* [#1660](https://github.com/open-contracting/standard/pull/1660) Remove all references to "building blocks" and "blocks". ## [1.1.5] - 2020-08-20 @@ -525,8 +526,8 @@ See the changelogs for: #### Schema definition updates * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - We have replaced receiverOrganization and providerOrganization with payee and payer, to align with more familiar terminology, and have replaced 'amount' with 'value' for consistency with other areas of the standard. -* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to core budget block](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. -* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the tenders block, and cross-referenced the bid extension. +* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to core budget sub-schema](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. +* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the tenders sub-schema, and cross-referenced the bid extension. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have updated the definition of hasEnquiries. * [#246](https://github.com/open-contracting/standard/issues/246) **[In what scope must a release ID be unique?](../schema/reference.md#release)** - We have updated the definition of release.id to reflect the scope in which it must be unique @@ -546,8 +547,8 @@ See the changelogs for: ### Added -* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new RelatedProcess block at the release and contract level -* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the period building block +* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new RelatedProcess object at the release and contract level +* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the period sub-schema * [#374](https://github.com/open-contracting/standard/issues/374) **[Contract and Award Periods in Tender](../schema/reference.md#tender)** - We have introduced contract period in tender and updated the definition of award period. * [#376](https://github.com/open-contracting/standard/issues/376) **[Contract type (supplies, works and services)](../schema/codelists.md#procurement-category)** - We have introduced a procurementCategory field to specify whether contracts are for supplies, works, services, consultancyServices or mixed * [#373](https://github.com/open-contracting/standard/issues/373) **[Milestone types](../schema/codelists.md#milestone-type)** - We have introduced the milestoneType property and codelist @@ -558,9 +559,9 @@ See the changelogs for: * [#335](https://github.com/open-contracting/standard/issues/335) [#411](https://github.com/open-contracting/standard/pull/411) **[Core and community extensions](../guidance/map/extensions)** - We have introduced widespread use of extensions throughout the standard. An extension provides fields and data structures that are optional, either because (a) they are only relevant in particular contexts or contracting processes; or (b) they represent a 'stretch goal' for most data publishers, and so are not currently suitable for inclusion in the main standard. We divide these extensions into 'core extensions' which have wide enough relevance, and technical maturity to be included in the main standard documentation (and which are versioned along with the standard documentation), and 'community extensions' which may have less technical maturity, or which might be versioned independently of the main standard. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have introduced a core enquiries extension for providing information on enquiries received during the tender stage. * [#342](https://github.com/open-contracting/standard/issues/342) **[Overall contracting process description](../schema/reference.md#release)** - We have introduced a new top-level title and description for the contracting process as a core extension. -* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the Contract block to support contract cross-referencing between contracts. +* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the Contract sub-schema to support contract cross-referencing between contracts. * [#381](https://github.com/open-contracting/standard/issues/381) **[Lots](https://extensions.open-contracting.org/en/extensions/lots/)** - We have introduced a core extension to provide a model for contracting processes which are divided into lots. -* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top level Bids section, with BidStatistics and Bid building blocks for detailed information on individual bids. This supersedes the current tender/tenderers section. +* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top level Bids section, with BidStatistics and Bid objects for detailed information on individual bids. This supersedes the current tender/tenderers section. * [#250](https://github.com/open-contracting/standard/issues/250) **[Location extension](https://extensions.open-contracting.org/en/extensions/location/)** - We have moved the location extensions to become a core extension * [#33](https://github.com/open-contracting/standard/issues/33) **[Participation fees (bid document and submission costs)](https://extensions.open-contracting.org/en/extensions/participation_fee/)** - We have introduced a core extension for declaring the participation fees related to a contracting process. * [#249](https://github.com/open-contracting/standard/issues/249) **[Extend contract with a supplier array](https://extensions.open-contracting.org/en/extensions/contract_suppliers/)** - We have introduced a core extension to allow inclusion of supplier information at the contract level. @@ -568,7 +569,7 @@ See the changelogs for: ### Deprecated * [#355](https://github.com/open-contracting/standard/issues/355) **[Deprecating milestone documents](../schema/reference.md#milestone)** - We have deprecated milestone documents from core, and added a milestone documents extension for those who wish to continue to use documents at the milestone level. -* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full organization block at points other than the parties array. +* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full organization sub-schema at points other than the parties array. * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - receiverOrganization, providerOrganization and amount properties have been deprecated in favour or other terms. ## [1.0.3] - 2017-07-31 From 6e8e9d86476b8dbfe04d5fb20b1500072f8da70d Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 17 Nov 2023 16:02:49 +0000 Subject: [PATCH 03/17] update index.md --- docs/schema/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/index.md b/docs/schema/index.md index bee616bb8..57f2bed17 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ The Open Contracting Data Standard is maintained using JSON Schema. In this section you will find the schemas for [releases](release) and [records](record) along with the schemas for [packaging](packaging/index.md), which act as envelopes for releases and records. -The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [building blocks](reference.md#building-block-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. +The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [objectss](reference.md#object-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. OCDS data must follow the I-JSON (Internet JSON) specification in [RFC7493](https://tools.ietf.org/html/rfc7493), according to which JSON text must be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8), and which introduces a number of requirements for numbers, objects and dates. From c7595c3040ce02989f30940d97796bdc1aef45e9 Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 17 Nov 2023 16:06:00 +0000 Subject: [PATCH 04/17] fix typo in index.md --- docs/schema/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/index.md b/docs/schema/index.md index 57f2bed17..92164da32 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ The Open Contracting Data Standard is maintained using JSON Schema. In this section you will find the schemas for [releases](release) and [records](record) along with the schemas for [packaging](packaging/index.md), which act as envelopes for releases and records. -The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [objectss](reference.md#object-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. +The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [objects](reference.md#object-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. OCDS data must follow the I-JSON (Internet JSON) specification in [RFC7493](https://tools.ietf.org/html/rfc7493), according to which JSON text must be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8), and which introduces a number of requirements for numbers, objects and dates. From 9b9e02f8e4ca27fa680719fddd6dc5d00c6c2be2 Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 17 Nov 2023 16:08:43 +0000 Subject: [PATCH 05/17] update reference.md --- docs/schema/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 535f6f179..72eac677c 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -381,7 +381,7 @@ Structured information on the former value of specific fields may be provided in See the [amendment implementation guidance](../guidance/map/amendments) for more details. ``` -## Sub-schema reference +## Object reference The following sub-schema are commonly re-used throughout the standard. From 6b70cd5d6c7869e5680566c8f0342b4e6b5e437f Mon Sep 17 00:00:00 2001 From: odscjen <95221058+odscjen@users.noreply.github.com> Date: Tue, 28 Nov 2023 11:13:08 +0000 Subject: [PATCH 06/17] Apply suggestions from code review Co-authored-by: Duncan Dewhurst --- docs/guidance/build/merging.md | 2 +- docs/guidance/map/amendments.md | 8 +++---- docs/guidance/map/extensions.md | 2 +- docs/guidance/map/milestones.md | 12 ++++------ .../map/organization_classifications.md | 6 ++--- docs/guidance/map/organization_reference.md | 2 +- docs/guidance/map/organizational_units.md | 2 +- docs/guidance/map/unsuccessful_processes.md | 2 +- docs/history/changelog.md | 14 +++++------ docs/primer/releases_and_records.md | 2 +- docs/schema/codelists.md | 4 ++-- docs/schema/index.md | 2 +- docs/schema/reference.md | 24 +++++++++---------- 13 files changed, 40 insertions(+), 42 deletions(-) diff --git a/docs/guidance/build/merging.md b/docs/guidance/build/merging.md index 3752b354d..f2481532e 100644 --- a/docs/guidance/build/merging.md +++ b/docs/guidance/build/merging.md @@ -93,7 +93,7 @@ Another government agency in Colombia publishes a new procurement opportunity. D A few days after releasing the tender notice, the government agency receives feedback for potential bidders, and they realize that the estimated contract period set for the tender could be infeasible. They decide to instead negotiate the contract period with the supplier, and they remove the contract period from the opportunity to avoid confusing potential bidders. -A release with a 'tenderAmendment' tag is published, in which both the `startDate` and `endDate` of the `contractPeriod` object have been set to `null`. Also, an `amendments` object is provided to explain the changes. +A release with a 'tenderAmendment' tag is published, in which both the `startDate` and `endDate` of the `contractPeriod` object have been set to `null`. Also, an `amendments` array is provided to explain the changes. The final record is shown below. Note that the fields in the `contractPeriod` object have disappeared in the `compiledRelease`, and the `versionedRelease` contains the previous values. diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 0af245537..28f105e5e 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -18,7 +18,7 @@ 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 amendments** object. This can contain an array of amendment explanations, and clearly identify the releases that contain before and after values. +* **The amendments** array. Each item in the array is an `Amendment` object, including a rationale, a description, and references to the releases that contain before and after values. ## Worked examples @@ -48,7 +48,7 @@ Weeks later, the publisher expands the `description` of the tender to provide mo #### Tender Amendment -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` object 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. +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` array 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. ```{jsoninclude} ../../examples/amendments/tender.json :jsonpointer: /records/0/releases/2 @@ -72,7 +72,7 @@ It is encouraged to [download](../../examples/amendments/tender.json) the record Note in this example that: -* **The amendments object does not contain data on what was changed**. Changes are recorded by updating the fields of the `tender` object a new release. +* **The amendments array does not contain data on what was changed**. Changes are recorded by updating the fields of the `tender` object in 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. @@ -96,7 +96,7 @@ See the JSON release below. #### 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` object and the value of the contract is increased. A `amendments` object is included to explain the rationale of the changes. +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` array and the value of the contract is increased. A `amendments` array is included to explain the rationale of the changes. See the example release below. diff --git a/docs/guidance/map/extensions.md b/docs/guidance/map/extensions.md index 110196953..72517a5d9 100644 --- a/docs/guidance/map/extensions.md +++ b/docs/guidance/map/extensions.md @@ -1,6 +1,6 @@ # Extensions -OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [objects](../../schema/reference.md#object-reference) for describing contracting (or planning) processes. +OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [sub-schemas](../../schema/reference.md#sub-schema-reference) for describing contracting (or planning) processes. Many publishers will have additional data that they could publish. Instead of ignoring this data and leaving it unpublished, OCDS encourages publishers to collaborate on the creation of **extensions** to the standard. diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index ee3e0ec6c..d33ca5a3a 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -8,28 +8,26 @@ Milestones can be included within the planning, tender, contract and contract im ## Planning -The planning milestones object is used for two types of milestones: +Planning milestones describe: * 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 -populate the tender milestones object instead. +ought to publish it as a tender milestone. ## Tender -The tender milestones object is used to describe two types of milestone: +Tender milestones describe: * Key dates in the tender and award stages which are not covered by other fields, for example, the date by which procuring entity will respond to enquiries. * Anticipated milestones during the contract implementation stage, for example, the date by which goods need to be delivered. ## Contract -The contract milestones object is used to describe: - * Events related to the signing of the contract, for example, the date of commercial close in a PPP contract. +Contract milestones describe events related to the signing of the contract, for example, the date of commercial close in a PPP contract. ## Contract Implementation -The contract implementation milestones object is used to describe: - * Any events related to the delivery of the contract, for example, the agreed date by which goods will be delivered. +Contract implementation milestones describe 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. diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index 65a4be562..834b237dd 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -11,7 +11,7 @@ Some organization classifications, such as organization scale, can be published There are therefore two options that are encouraged for publishing organization classifications. 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` sub-schema 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. +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 `parties.details` 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. 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. @@ -43,7 +43,7 @@ In the examples below, two different publishers have disclosed information about #### Classification schemes -Each `classification` object 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). +Each `Classification` 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). 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). @@ -75,7 +75,7 @@ In their publication policy, the procurement team documents all possible codes f 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` sub-schema 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. +In the fictional example below, Dhanghadi has created a local extension so they can publish data in the `parties.details` object 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. ```{jsoninclude} ../../examples/organizations/organization_classification/dhangadhi_female_chaired_example.json :jsonpointer: diff --git a/docs/guidance/map/organization_reference.md b/docs/guidance/map/organization_reference.md index 4b5a828e5..5e2f20c8c 100644 --- a/docs/guidance/map/organization_reference.md +++ b/docs/guidance/map/organization_reference.md @@ -16,7 +16,7 @@ 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` object and wants to contact *Open Data Services*, then the user has to search for the `id` *GB-COH-09506232* in the `parties` array. +* If a user looks at the `tenderers` array 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 diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index 9717a566c..d6eb9110d 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -15,7 +15,7 @@ There is more than one approach to model organizational units in OCDS: * The `address` and `contactPoint` objects can be filled with the unit information. * Unit identifiers can also be appended to `parties/id`. -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 sub-schema. +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` sub-schema. 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. diff --git a/docs/guidance/map/unsuccessful_processes.md b/docs/guidance/map/unsuccessful_processes.md index 7457352b7..5d47affab 100644 --- a/docs/guidance/map/unsuccessful_processes.md +++ b/docs/guidance/map/unsuccessful_processes.md @@ -40,7 +40,7 @@ To construct an `ocid` for the second contracting process, Paraguay adds a conse Paraguay could also have used the identifier for the second tender as the `ocid` for the second contracting process. -The `relatedProcesses` object links to the unsuccessful contracting process with the relationship set to ‘unsuccessfulProcess’, and to the initial planning process with the relationship set to ‘planning’. +The `relatedProcesses` array 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/related_process.json :jsonpointer: diff --git a/docs/history/changelog.md b/docs/history/changelog.md index d94310858..9495384ea 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -526,8 +526,8 @@ See the changelogs for: #### Schema definition updates * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - We have replaced receiverOrganization and providerOrganization with payee and payer, to align with more familiar terminology, and have replaced 'amount' with 'value' for consistency with other areas of the standard. -* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to core budget sub-schema](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. -* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the tenders sub-schema, and cross-referenced the bid extension. +* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to `Budget` sub-schema](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. +* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the `Tender` sub-schema, and cross-referenced the bid extension. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have updated the definition of hasEnquiries. * [#246](https://github.com/open-contracting/standard/issues/246) **[In what scope must a release ID be unique?](../schema/reference.md#release)** - We have updated the definition of release.id to reflect the scope in which it must be unique @@ -547,8 +547,8 @@ See the changelogs for: ### Added -* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new RelatedProcess object at the release and contract level -* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the period sub-schema +* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new `relatedProcesses` field at the release and contract level +* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the `Period` sub-schema * [#374](https://github.com/open-contracting/standard/issues/374) **[Contract and Award Periods in Tender](../schema/reference.md#tender)** - We have introduced contract period in tender and updated the definition of award period. * [#376](https://github.com/open-contracting/standard/issues/376) **[Contract type (supplies, works and services)](../schema/codelists.md#procurement-category)** - We have introduced a procurementCategory field to specify whether contracts are for supplies, works, services, consultancyServices or mixed * [#373](https://github.com/open-contracting/standard/issues/373) **[Milestone types](../schema/codelists.md#milestone-type)** - We have introduced the milestoneType property and codelist @@ -559,9 +559,9 @@ See the changelogs for: * [#335](https://github.com/open-contracting/standard/issues/335) [#411](https://github.com/open-contracting/standard/pull/411) **[Core and community extensions](../guidance/map/extensions)** - We have introduced widespread use of extensions throughout the standard. An extension provides fields and data structures that are optional, either because (a) they are only relevant in particular contexts or contracting processes; or (b) they represent a 'stretch goal' for most data publishers, and so are not currently suitable for inclusion in the main standard. We divide these extensions into 'core extensions' which have wide enough relevance, and technical maturity to be included in the main standard documentation (and which are versioned along with the standard documentation), and 'community extensions' which may have less technical maturity, or which might be versioned independently of the main standard. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have introduced a core enquiries extension for providing information on enquiries received during the tender stage. * [#342](https://github.com/open-contracting/standard/issues/342) **[Overall contracting process description](../schema/reference.md#release)** - We have introduced a new top-level title and description for the contracting process as a core extension. -* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the Contract sub-schema to support contract cross-referencing between contracts. +* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the `Contract` sub-schema to support contract cross-referencing between contracts. * [#381](https://github.com/open-contracting/standard/issues/381) **[Lots](https://extensions.open-contracting.org/en/extensions/lots/)** - We have introduced a core extension to provide a model for contracting processes which are divided into lots. -* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top level Bids section, with BidStatistics and Bid objects for detailed information on individual bids. This supersedes the current tender/tenderers section. +* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top-level Bids section, with BidStatistics and Bid sub-schemas for detailed information on individual bids. This supersedes the current tender/tenderers section. * [#250](https://github.com/open-contracting/standard/issues/250) **[Location extension](https://extensions.open-contracting.org/en/extensions/location/)** - We have moved the location extensions to become a core extension * [#33](https://github.com/open-contracting/standard/issues/33) **[Participation fees (bid document and submission costs)](https://extensions.open-contracting.org/en/extensions/participation_fee/)** - We have introduced a core extension for declaring the participation fees related to a contracting process. * [#249](https://github.com/open-contracting/standard/issues/249) **[Extend contract with a supplier array](https://extensions.open-contracting.org/en/extensions/contract_suppliers/)** - We have introduced a core extension to allow inclusion of supplier information at the contract level. @@ -569,7 +569,7 @@ See the changelogs for: ### Deprecated * [#355](https://github.com/open-contracting/standard/issues/355) **[Deprecating milestone documents](../schema/reference.md#milestone)** - We have deprecated milestone documents from core, and added a milestone documents extension for those who wish to continue to use documents at the milestone level. -* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full organization sub-schema at points other than the parties array. +* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full `Organization` sub-schema at points other than the parties array. * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - receiverOrganization, providerOrganization and amount properties have been deprecated in favour or other terms. ## [1.0.3] - 2017-07-31 diff --git a/docs/primer/releases_and_records.md b/docs/primer/releases_and_records.md index debdb902d..8c6e00782 100644 --- a/docs/primer/releases_and_records.md +++ b/docs/primer/releases_and_records.md @@ -38,7 +38,7 @@ Each time a new release is published it is added to the index, the compiled rele ![A contracting (or planning) process is described by many releases, which are aggregated into a single record](../_static/png/change_history_process_record.png) -Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out standard sub-schema for items across releases, including the name of the item, a description, each item’s value, and the currency used. +Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out a standard sub-schema for items across releases, including the name of the item, a description, each item’s value, and the currency used. When you publish OCDS releases and records, you are encouraged to: diff --git a/docs/schema/codelists.md b/docs/schema/codelists.md index b2ce33ff9..8cbc79b7d 100644 --- a/docs/schema/codelists.md +++ b/docs/schema/codelists.md @@ -121,7 +121,7 @@ The submission method codelist is used to identify the mechanism through which a ```{versionadded} 1.1 ``` -The related process object is used at the release level to point backwards to prior processes, such as planning or framework establishment, and at the contract level to point onwards to subcontracts or to renewal or replacement processes. The related process codelist determines the kind of relationship that is being described. +The `RelatedProcess` sub-schema is used at the release level to point backwards to prior processes, such as planning or framework establishment, and at the contract level to point onwards to subcontracts or to renewal or replacement processes. The related process codelist determines the kind of relationship that is being described. ```{csv-table-no-translate} :header-rows: 1 @@ -145,7 +145,7 @@ The related process scheme describes the kind of identifier used to cross-refere ```{versionadded} 1.1 ``` -The milestone object can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. +The `Milestone` sub-schema can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. ```{csv-table-no-translate} :header-rows: 1 diff --git a/docs/schema/index.md b/docs/schema/index.md index 92164da32..6e73a1146 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ The Open Contracting Data Standard is maintained using JSON Schema. In this section you will find the schemas for [releases](release) and [records](record) along with the schemas for [packaging](packaging/index.md), which act as envelopes for releases and records. -The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [objects](reference.md#object-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. +The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [sub-schemas](reference.md#sub-schema-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. OCDS data must follow the I-JSON (Internet JSON) specification in [RFC7493](https://tools.ietf.org/html/rfc7493), according to which JSON text must be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8), and which introduces a number of requirements for numbers, objects and dates. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 72eac677c..4b3ae47da 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -78,7 +78,7 @@ The majority of OCDS data is held within a release structure. One or more releas A release has a [tag](codelists.md#release-tag) to indicate whether it is about a planning process or a contracting process and, if it is about the latter, to indicate the stage of the contracting process to which it relates. However, there are no formal restrictions on when information about a stage of the process can be provided. -For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the award and tender objects in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. +For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the awards array and tender object in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. ### Release @@ -228,7 +228,7 @@ The [Bid statistics and details](https://extensions.open-contracting.org/en/exte ### Award -The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. A related award object is required for every contract object, as the award contains information on the suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). +The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. Awards contain information about suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). ````{admonition} Example :class: hint @@ -280,7 +280,7 @@ The contract section is used to provide details of contracts that have been ente ### Implementation -Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. Implementation objects include the following elements: +Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. The implementation sub-schema includes the following fields: ````{admonition} Example :class: hint @@ -322,7 +322,7 @@ Information on subcontracts is not currently included in the core OCDS schema, b :collapse: providerOrganization,receiverOrganization,amount,payer,payee,value ``` -The transaction object 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) object, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. +The `Transaction` sub-schema 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) object, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. ```{note} To represent planned payments, use [Milestones](#milestones) instead. @@ -381,9 +381,9 @@ Structured information on the former value of specific fields may be provided in See the [amendment implementation guidance](../guidance/map/amendments) for more details. ``` -## Object reference +## Sub-schema reference -The following sub-schema are commonly re-used throughout the standard. +The following sub-schemas are commonly re-used throughout the standard. ### OrganizationReference @@ -415,7 +415,7 @@ See the [parties](#parties) section. #### Identifier -The identifier object provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. +The identifier sub-schema provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. 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). @@ -467,7 +467,7 @@ When describing an organizational unit (for example, a department or branch of a ### Document -Documents can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each document object can consist of multiple documents, classified using the [documentType](codelists.md#document-type) codelist. +Documents can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each documents array 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). @@ -539,7 +539,7 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The items object is used to list the line-items associated with a tender, award or contract. +The `Item` sub-schema is used to describe the line-items associated with a tender, award or contract. ````{admonition} Example :class: hint @@ -561,7 +561,7 @@ The items object is used to list the line-items associated with a tender, award #### Unit -The `unit` object allows detailed specification of the parameters and price of units that make up a line-item. +The `unit` sub-schema allows detailed specification of the parameters and price of units that make up a line-item. If the [Quantities, Units, Dimensions and Data Types Ontologies](https://www.qudt.org) unit classification scheme is used, then publishers can use its CamelCase unit names, such as "SquareMile", in the `unit.name` field. @@ -666,7 +666,7 @@ In OCDS each contracting process can have only one tender stage. There are a num * When a contract results in the award of sub-contracts - and those sub-contracts are also tracked using OCDS; * When a contract is coming up for renewal or replacement, and there is a contracting process to award the renewal/replacement contract; -In all these cases, the `relatedProcess` object should be used to cross-reference between the relevant contracting processes using their `ocid`. +In all these cases, the `relatedProcess` sub-schema should be used to cross-reference between the relevant contracting processes using their `ocid`. ````{admonition} Example :class: hint @@ -687,7 +687,7 @@ A related process can be declared at two points in an OCDS release. **(2) At the contract level** - used to point onward to sub-contracts, renewal or replacement processes that relate solely to the particular contract the field appears in. -As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant `documents` objects. For example: +As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant `documents` arrays. For example: * When recording a `release/relatedProcess` pointing to the ocid of the planning process that resulted in a tender, a `tender/documents` entry with a `documentType` of 'procurementPlan' and a link to web pages about the procurement plan could be provided; * When recording a `contract/relatedProcess` pointing to the ocid of a sub-contracting process, a `contract/documents` entry with a `documentType` of 'subContract' and a title that describes it as the subcontracting process, could be provided; From 26267078cd221304009dc8b43a0eaac0ada9e766 Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 28 Nov 2023 11:41:33 +0000 Subject: [PATCH 07/17] Apply further suggestions from code review --- docs/guidance/map/milestones.md | 3 +-- docs/schema/reference.md | 22 +++++++++++----------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index d33ca5a3a..67e804c4f 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -12,8 +12,7 @@ Planning milestones describe: * 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 -ought to publish it as a tender milestone. +If during the planning process you have information about tender process milestones, then you ought to publish it as a tender milestone. ## Tender diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 4b3ae47da..d332bbedd 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -78,11 +78,11 @@ The majority of OCDS data is held within a release structure. One or more releas A release has a [tag](codelists.md#release-tag) to indicate whether it is about a planning process or a contracting process and, if it is about the latter, to indicate the stage of the contracting process to which it relates. However, there are no formal restrictions on when information about a stage of the process can be provided. -For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the awards array and tender object in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. +For example, a publisher announcing the signing of a contract with a 'contract' tag might also include information in the awards array and tender object in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed. ### Release -All new information about a contracting (or planning) process is described within a release. +All new information about a contracting (or planning) process is described within a release. ````{admonition} Example :class: hint @@ -107,7 +107,7 @@ All new information about a contracting (or planning) process is described withi ### Parties -Each of the organizations referenced in a release must be included in the parties section. +Each of the organizations referenced in a release must be included in the parties section. ```{versionadded} 1.1 In OCDS 1.0, the details (address, contact point, etc.) of the organizations involved in a contracting process were repeated across many fields (`tenderers`, `suppliers`, etc.). In OCDS 1.1, these details are instead collected under a top-level `parties` array, with the other fields referencing entries in this array, using [organization references](#organizationreference). This reduces repetition and supports publication of information about additional organizations: for example, multiple buyers. @@ -172,7 +172,7 @@ The planning section is used in a planning process. This includes information ab :tag: planning ``` -#### Budget +#### Budget Apart from documents, the majority of planning information is held within the budget object. 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. @@ -198,7 +198,7 @@ Apart from documents, the majority of planning information is held within the bu The tender section includes details of the announcement that an organization intends to source some particular goods, services or works and to establish one or more contract(s) for these. -It can contain details of a forthcoming process to receive and evaluate proposals to supply these goods, services or works and can also be used to record details of a completed tender stage, including details of bids received. +It can contain details of a forthcoming process to receive and evaluate proposals to supply these goods, services or works and can also be used to record details of a completed tender stage, including details of bids received. ````{admonition} Example :class: hint @@ -254,7 +254,7 @@ The award section is used to announce any awards issued for this tender. There c ### Contract -The contract section is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. +The contract section is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. ````{admonition} Example :class: hint @@ -328,7 +328,7 @@ The `Transaction` sub-schema is modelled on the [International Aid Transparency To represent planned payments, use [Milestones](#milestones) instead. ``` -In most circumstances, the `payer` identifier will match that of the `buyer`, and the `payee` identifier will match that of the `supplier`. +In most circumstances, the `payer` identifier will match that of the `buyer`, and the `payee` identifier will match that of the `supplier`. ```{extensionlist} The following extensions are available for transactions :list: transaction @@ -338,13 +338,13 @@ In most circumstances, the `payer` identifier will match that of the `buyer`, an See [milestone](#milestone) reference below. -The implementation milestones should be updated to reflect when they are met. +The implementation milestones should be updated to reflect when they are met. #### Documents Documents related to contract implementation are stored here. This can include subcontracts. -See [document](#document) reference below. +See [document](#document) reference below. ### Amendment @@ -539,7 +539,7 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The `Item` sub-schema is used to describe the line-items associated with a tender, award or contract. +The `Item` sub-schema is used to describe the line-items associated with a tender, award or contract. ````{admonition} Example :class: hint @@ -601,7 +601,7 @@ Other unit classification schemes can be used, including those in the [unitClass Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. -The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` either updated, or re-confirmed. +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) From a068ac688bd04dfcab502bf337e7646a70a2b3b9 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 5 Dec 2023 15:11:43 -0500 Subject: [PATCH 08/17] examples: building block -> sub-schema --- .../ocds_divisionCode_extension/extension.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json index 8c2e39f88..4b3de9fc3 100644 --- a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json +++ b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json @@ -3,7 +3,7 @@ "en": "Division codes" }, "description": { - "en": "Adds a divisionCode field to the Organization building block" + "en": "Adds a divisionCode field to the Organization sub-schema" }, "documentationUrl": { "en": "http://github.com/example_publisher/ocds_division_code_extension" From 038c800e807d25c71a14151c48df3fd529a5064d Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 7 Dec 2023 12:07:50 +0000 Subject: [PATCH 09/17] documentType.csv:remove mentions of blocks --- schema/codelists/documentType.csv | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schema/codelists/documentType.csv b/schema/codelists/documentType.csv index 0f3c2d068..0b7dc64e2 100644 --- a/schema/codelists/documentType.csv +++ b/schema/codelists/documentType.csv @@ -33,11 +33,11 @@ award,winningBid,Winning bid,"Documentation of the winning bid, including, where "tender, award",complaints,Complaints and decisions,"Documentation of any complaints received, or decisions in response to complaints.",, contract,contractAnnexe,Annexes to the contract,"Any document which contains additional terms, obligations or information related to the contract, such as an annex, appendix, schedule, attachment or addendum.",, "tender, contract",contractGuarantees,Guarantees,Documentation of guarantees relating to a contracting process or contract.,, -contract,subContract,Subcontracts,"Documentation detailing subcontracts and/or providing a copy of subcontracts themselves. Where OCDS data on the subcontracts exists, this can be declared using the relatedProcess block.",, +contract,subContract,Subcontracts,Documentation detailing subcontracts and/or providing a copy of subcontracts themselves.,, planning,needsAssessment,Needs assessment,Documentation of the needs assessments carried out for a future contracting process addressing demand for the project or investment from the affected communities or users.,, planning,feasibilityStudy,Feasibility study,"Documentation of feasibility studies carried out for a future contracting process, providing information on net benefits or costs of the proposed goods, works or services.",, planning,projectPlan,Project plan,"Documentation of project planning for a future contracting process, and, where applicable, a copy of the project plan document.",, -tender,billOfQuantity,Bill of quantity,"Documentation that provides itemized information on materials, parts and labour, and the terms and conditions for their provision, providing information that would enable bidders to price work effectively. Structured versions of item and quantity information at each of tender, award and contract stage can be provided using units within the items building block.",, +tender,billOfQuantity,Bill of quantity,"Documentation that provides itemized information on materials, parts and labour, and the terms and conditions for their provision, providing information that would enable bidders to price work effectively.",, tender,bidders,Information on bidders,"Documentation on bidders or participants, their validation documents and any procedural exemptions for which they qualify.",, "tender, award, contract, implementation",conflictOfInterest,Conflict of interest,Documentation of conflicts of interest declared or uncovered.,, implementation,debarments,Debarments,Documentation of any debarments issued.,, From 12b7af0d9624dc30625c010a8ad71385c7e83c2b Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Fri, 15 Dec 2023 15:50:42 +0000 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com> --- docs/guidance/map/organization_classifications.md | 2 +- docs/guidance/map/organization_personal_identifiers.md | 2 +- docs/guidance/map/organizational_units.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index 834b237dd..ce7d18a60 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -43,7 +43,7 @@ In the examples below, two different publishers have disclosed information about #### Classification schemes -Each `Classification` 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). +A classification object can set the fields: `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). 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). diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index 30b4c321e..18a7daf0f 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -11,7 +11,7 @@ Details of natural persons can be disclosed using the `parties` section in OCDS * The natural person is a tenderer or supplier; and * The laws in your jurisdiction permit the publication of such details -Subject to the above, you can disclose identifiers for natural persons using the `Identifier` sub-schema. +Subject to the above, you can disclose identifiers for natural persons using the `identifier` field. There are two components to an identifier in OCDS: diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index d6eb9110d..7bff36216 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -8,14 +8,14 @@ For some use cases, publishers might need to disclose the organizational units i There is more than one approach to model organizational units in OCDS: -1. **Use the fields and objects available in the Organization sub-schema**. This is the preferred approach, when possible. +1. **Use the fields available in the Organization sub-schema**. This is the preferred approach, when possible. * 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` objects can be filled with the unit information. * Unit identifiers can also be appended to `parties/id`. -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` sub-schema. +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 under the `details` field of the `Organization` sub-schema. 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. From 074c94668c90aa530ceb1463088d32244f0ea9e2 Mon Sep 17 00:00:00 2001 From: odscjen Date: Fri, 2 Feb 2024 18:01:54 +0000 Subject: [PATCH 11/17] style adjustments re use of field/array/object/subschema consistently --- .../extension.json | 2 +- docs/guidance/build/system_architectures.md | 2 +- docs/guidance/map/amendments.md | 4 +- docs/guidance/map/extensions.md | 2 +- .../map/organization_classifications.md | 4 +- docs/guidance/map/organizational_units.md | 8 +-- docs/history/changelog.md | 10 +-- docs/primer/releases_and_records.md | 2 +- docs/schema/codelists.md | 10 +-- docs/schema/index.md | 2 +- docs/schema/reference.md | 68 +++++++++---------- 11 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json index 4b3de9fc3..c05ba50c1 100644 --- a/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json +++ b/docs/examples/organizations/organizational_units/ocds_divisionCode_extension/extension.json @@ -3,7 +3,7 @@ "en": "Division codes" }, "description": { - "en": "Adds a divisionCode field to the Organization sub-schema" + "en": "Adds a divisionCode field to the Organization subschema" }, "documentationUrl": { "en": "http://github.com/example_publisher/ocds_division_code_extension" diff --git a/docs/guidance/build/system_architectures.md b/docs/guidance/build/system_architectures.md index 77d5a37ed..8b97762d8 100644 --- a/docs/guidance/build/system_architectures.md +++ b/docs/guidance/build/system_architectures.md @@ -74,7 +74,7 @@ This approach puts the burden of data conversion on data sources. Yet it might b This approach might also be suitable to combine data from many data sources. Each source becomes an OCDS publisher. The middleware becomes less complex since it only ingests data in a single format. -The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses OCDS sub-schema as the foundation for data sources' data models. +The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses OCDS subschema as the foundation for data sources' data models. A variant in this scenario is to store files in a web-accessible file system, as shown below. A periodical invocation of the conversion module updates the file system. diff --git a/docs/guidance/map/amendments.md b/docs/guidance/map/amendments.md index 28f105e5e..f1cf837cd 100644 --- a/docs/guidance/map/amendments.md +++ b/docs/guidance/map/amendments.md @@ -96,7 +96,7 @@ See the JSON release below. #### 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` array and the value of the contract is increased. A `amendments` array is included to explain the rationale of the changes. +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` array and the value of the contract is increased. An `amendments` array is included to explain the rationale of the changes. See the example release below. @@ -149,7 +149,7 @@ This can be modelled as the separate releases in OCDS as shown below. The origin :title: ContractAmendment ``` -Note that the mapping of the fields remains the same for the contract amendments, except for the `description` column. When a row in the contract signature notices table is identified as an original contract, the description is included in the `contracts/description` field, and when the row represents a contract amendment, it is mapped to the `contracts/amendments/description` field. This aligns with the use of the `description` column, because for contract amendments it is used to include an explanation of the change. +Note that the mapping of the fields remains the same for the contract amendments, except for the `description` column. When a row in the contract signature notices table is identified as an original contract, the description is included in the `contracts.description` field, and when the row represents a contract amendment, it is mapped to the `contracts.amendments.description` field. This aligns with the use of the `description` column, because for contract amendments it is used to include an explanation of the change. The advantage of this approach, in contrast with the Easy releases proposal, is that the users have access to the details of each amendment instead of the latest values only without any additional effort of their end. diff --git a/docs/guidance/map/extensions.md b/docs/guidance/map/extensions.md index fc98318b7..251d4c21c 100644 --- a/docs/guidance/map/extensions.md +++ b/docs/guidance/map/extensions.md @@ -1,6 +1,6 @@ # Extensions -OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [sub-schemas](../../schema/reference.md#sub-schema-reference) for describing contracting (or planning) processes. +OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [subschemas](../../schema/reference.md#subschema-reference) for describing contracting (or planning) processes. Many publishers will have additional data that they could publish. Instead of ignoring this data and leaving it unpublished, OCDS encourages publishers to collaborate on the creation of **extensions** to the standard. diff --git a/docs/guidance/map/organization_classifications.md b/docs/guidance/map/organization_classifications.md index ce7d18a60..37dd4dd3c 100644 --- a/docs/guidance/map/organization_classifications.md +++ b/docs/guidance/map/organization_classifications.md @@ -11,7 +11,7 @@ Some organization classifications, such as organization scale, can be published There are therefore two options that are encouraged for publishing organization classifications. 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 `parties.details` 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. +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` object 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. 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. @@ -43,7 +43,7 @@ In the examples below, two different publishers have disclosed information about #### Classification schemes -A classification object can set the fields: `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). +A `classification` object can set the fields: `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). 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). diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index 7bff36216..26d1504d8 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -8,20 +8,20 @@ For some use cases, publishers might need to disclose the organizational units i There is more than one approach to model organizational units in OCDS: -1. **Use the fields available in the Organization sub-schema**. This is the preferred approach, when possible. +1. **Use the fields available in the Organization subschema**. This is the preferred approach, when possible. * 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` objects can be filled with the unit information. * Unit identifiers can also be appended to `parties/id`. -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 under the `details` field of the `Organization` sub-schema. +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 under the `details` field of the `Organization` subschema. 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. ## Worked examples -### 1. Using the Organization sub-schema +### 1. Using the Organization subschema 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. @@ -63,7 +63,7 @@ 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 sub-schema with an organizational hierarchy +### 3. Using the Organization subschema with an organizational hierarchy 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. diff --git a/docs/history/changelog.md b/docs/history/changelog.md index 80da2f93d..2a6e09e1a 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -548,8 +548,8 @@ See the changelogs for: #### Schema definition updates * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - We have replaced receiverOrganization and providerOrganization with payee and payer, to align with more familiar terminology, and have replaced 'amount' with 'value' for consistency with other areas of the standard. -* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to `Budget` sub-schema](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. -* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the `Tender` sub-schema, and cross-referenced the bid extension. +* [#378](https://github.com/open-contracting/standard/issues/378) **[Updates to `Budget` subschema](../schema/reference.md#budget)** - We have updated references to the Fiscal Data Package in the schema. +* [#337](https://github.com/open-contracting/standard/issues/337) **[Definition of "tenderer" to enhance clarity](../schema/reference.md#tender)** - We have updated the definition of tenderer in the `Tender` subschema, and cross-referenced the bid extension. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have updated the definition of hasEnquiries. * [#246](https://github.com/open-contracting/standard/issues/246) **[In what scope must a release ID be unique?](../schema/reference.md#release)** - We have updated the definition of release.id to reflect the scope in which it must be unique @@ -570,7 +570,7 @@ See the changelogs for: ### Added * [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new `relatedProcesses` field at the release and contract level -* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the `Period` sub-schema +* [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the `Period` subschema * [#374](https://github.com/open-contracting/standard/issues/374) **[Contract and Award Periods in Tender](../schema/reference.md#tender)** - We have introduced contract period in tender and updated the definition of award period. * [#376](https://github.com/open-contracting/standard/issues/376) **[Contract type (supplies, works and services)](../schema/codelists.md#procurement-category)** - We have introduced a procurementCategory field to specify whether contracts are for supplies, works, services, consultancyServices or mixed * [#373](https://github.com/open-contracting/standard/issues/373) **[Milestone types](../schema/codelists.md#milestone-type)** - We have introduced the milestoneType property and codelist @@ -581,7 +581,7 @@ See the changelogs for: * [#335](https://github.com/open-contracting/standard/issues/335) [#411](https://github.com/open-contracting/standard/pull/411) **[Core and community extensions](../guidance/map/extensions)** - We have introduced widespread use of extensions throughout the standard. An extension provides fields and data structures that are optional, either because (a) they are only relevant in particular contexts or contracting processes; or (b) they represent a 'stretch goal' for most data publishers, and so are not currently suitable for inclusion in the main standard. We divide these extensions into 'core extensions' which have wide enough relevance, and technical maturity to be included in the main standard documentation (and which are versioned along with the standard documentation), and 'community extensions' which may have less technical maturity, or which might be versioned independently of the main standard. * [#259](https://github.com/open-contracting/standard/issues/259) **[Enquiries](https://extensions.open-contracting.org/en/extensions/enquiries/)** - We have introduced a core enquiries extension for providing information on enquiries received during the tender stage. * [#342](https://github.com/open-contracting/standard/issues/342) **[Overall contracting process description](../schema/reference.md#release)** - We have introduced a new top-level title and description for the contracting process as a core extension. -* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the `Contract` sub-schema to support contract cross-referencing between contracts. +* [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the `Contract` subschema to support contract cross-referencing between contracts. * [#381](https://github.com/open-contracting/standard/issues/381) **[Lots](https://extensions.open-contracting.org/en/extensions/lots/)** - We have introduced a core extension to provide a model for contracting processes which are divided into lots. * [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top-level Bids section, with BidStatistics and Bid sub-schemas for detailed information on individual bids. This supersedes the current tender/tenderers section. * [#250](https://github.com/open-contracting/standard/issues/250) **[Location extension](https://extensions.open-contracting.org/en/extensions/location/)** - We have moved the location extensions to become a core extension @@ -591,7 +591,7 @@ See the changelogs for: ### Deprecated * [#355](https://github.com/open-contracting/standard/issues/355) **[Deprecating milestone documents](../schema/reference.md#milestone)** - We have deprecated milestone documents from core, and added a milestone documents extension for those who wish to continue to use documents at the milestone level. -* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full `Organization` sub-schema at points other than the parties array. +* [#368](https://github.com/open-contracting/standard/issues/368) **[Updates to organization handling in OCDS](../schema/reference.md#parties)** - We have deprecated use of the full `Organization` subschema at points other than the parties array. * [#372](https://github.com/open-contracting/standard/issues/372) **[Updates to transactions terminology](../schema/reference.md#transaction)** - receiverOrganization, providerOrganization and amount properties have been deprecated in favor or other terms. ## [1.0.3] - 2017-07-31 diff --git a/docs/primer/releases_and_records.md b/docs/primer/releases_and_records.md index 8c6e00782..7b08b2c4e 100644 --- a/docs/primer/releases_and_records.md +++ b/docs/primer/releases_and_records.md @@ -38,7 +38,7 @@ Each time a new release is published it is added to the index, the compiled rele ![A contracting (or planning) process is described by many releases, which are aggregated into a single record](../_static/png/change_history_process_record.png) -Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out a standard sub-schema for items across releases, including the name of the item, a description, each item’s value, and the currency used. +Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out a standard subschema for items across releases, including the name of the item, a description, each item’s value, and the currency used. When you publish OCDS releases and records, you are encouraged to: diff --git a/docs/schema/codelists.md b/docs/schema/codelists.md index ba4f680d4..4a5114b0b 100644 --- a/docs/schema/codelists.md +++ b/docs/schema/codelists.md @@ -80,11 +80,11 @@ The `organizationIdentifierRegistrationAgency_iati.csv` file was removed. This l ### Document Type -The following list describes documents and documentation recommended for publication as part of an open contracting implementation. The codelist indicates the section of an OCDS release they are most likely to be applicable within. +The following list describes documents and documentation recommended for publication as part of an open contracting implementation. The codelist indicates the section of an OCDS release they are most likely to be applicable within. -The code descriptions are necessarily broad, to cover their usage in a range of contracting (or planning) processes, including for goods, services and works, and in other contexts, such as public private partnerships, infrastructure or concession contracts. +The code descriptions are necessarily broad, to cover their usage in a range of contracting (or planning) processes, including for goods, services and works, and in other contexts, such as public private partnerships, infrastructure or concession contracts. -Publishers must map their existing document codes to this list, where possible. If using this list within a user interface, publishers can re-write the codelist titles and descriptions appropriately for the context they are being used in. +Publishers must map their existing document codes to this list, where possible. If using this list within a user interface, publishers can re-write the codelist titles and descriptions appropriately for the context they are being used in. ```{csv-table-no-translate} :header-rows: 1 @@ -143,7 +143,7 @@ Added 'parent'. Deprecated 'subContract', 'replacementProcess' and 'renewalProce ```{versionadded} 1.1 ``` -The related process scheme describes the kind of identifier used to cross-reference another process. +The related process scheme describes the kind of identifier used to cross-reference another process. ```{csv-table-no-translate} :header-rows: 1 @@ -155,7 +155,7 @@ The related process scheme describes the kind of identifier used to cross-refere ```{versionadded} 1.1 ``` -The `Milestone` sub-schema can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. +The `Milestone` subschema can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. ```{csv-table-no-translate} :header-rows: 1 diff --git a/docs/schema/index.md b/docs/schema/index.md index 6e73a1146..58099de6f 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ The Open Contracting Data Standard is maintained using JSON Schema. In this section you will find the schemas for [releases](release) and [records](record) along with the schemas for [packaging](packaging/index.md), which act as envelopes for releases and records. -The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [sub-schemas](reference.md#sub-schema-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. +The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [subschemas](reference.md#subschema-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. OCDS data must follow the I-JSON (Internet JSON) specification in [RFC7493](https://tools.ietf.org/html/rfc7493), according to which JSON text must be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8), and which introduces a number of requirements for numbers, objects and dates. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 592c942f6..7a2e1910f 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -40,14 +40,14 @@ OCDS 1.1 allowed data to be published in multiple languages by suffixing a langu ## Release structure -The majority of OCDS data is held within a release structure. One or more releases can be published within a [release package](packaging/release_package). Releases are made up of a number of sections, arranged in the following structure. +The majority of OCDS data is held within a release structure. One or more releases can be published within a [release package](packaging/release_package). Releases are made up of a number of objects and arrays that represent the stages in a contracting (or planning) process, arranged in the following structure. * [release](#release) - * [parties](#parties) + * [parties](#parties) * [planning](#planning) - * [tender](#tender) - * [award](#award) - * [contract](#contract) + * [tender](#tender) + * [awards](#award) + * [contracts](#contract) * [implementation](#implementation) A release has a [tag](codelists.md#release-tag) to indicate whether it is about a planning process or a contracting process and, if it is about the latter, to indicate the stage of the contracting process to which it relates. However, there are no formal restrictions on when information about a stage of the process can be provided. @@ -81,7 +81,7 @@ All new information about a contracting (or planning) process is described withi ### Parties -Each of the organizations referenced in a release must be included in the parties section. +Each of the organizations referenced in a release must be included in the `parties` array, using the `Organization` subschema. ```{versionadded} 1.1 In OCDS 1.0, the details (address, contact point, etc.) of the organizations involved in a contracting process were repeated across many fields (`tenderers`, `suppliers`, etc.). In OCDS 1.1, these details are instead collected under a top-level `parties` array, with the other fields referencing entries in this array, using [organization references](#organizationreference). This reduces repetition and supports publication of information about additional organizations: for example, multiple buyers. @@ -122,7 +122,7 @@ Each organization has a `details` object. Through extensions, this can be used t ### Planning -The planning section is used in a planning process. This includes information about, for example, needs identification, budget planning and market research. Background documents such as feasibility studies and project plans can also be included in this section. +The `planning` object is used in a planning process. This includes information about, for example, needs identification, budget planning and market research. Background documents such as feasibility studies and project plans can also be included in this object. ````{admonition} Example :class: hint @@ -148,7 +148,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 object. 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` object. 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. ````{admonition} Example :class: hint @@ -170,7 +170,7 @@ Apart from documents, the majority of planning information is held within the bu ### Tender -The tender section includes details of the announcement that an organization intends to source some particular goods, services or works and to establish one or more contract(s) for these. +The `tender` object includes details of the announcement that an organization intends to source some particular goods, services or works and to establish one or more contract(s) for these. It can contain details of a forthcoming process to receive and evaluate proposals to supply these goods, services or works and can also be used to record details of a completed tender stage, including details of bids received. @@ -202,7 +202,7 @@ The [Bid statistics and details](https://extensions.open-contracting.org/en/exte ### Award -The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. Awards contain information about suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). +The `awards` array is used to announce any awards issued for this tender. There can be multiple awards made, each of which must be detailed using the `Award` subschema. Releases can contain all, or a subset, of these awards. Awards contain information about suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). ````{admonition} Example :class: hint @@ -228,7 +228,7 @@ The award section is used to announce any awards issued for this tender. There c ### Contract -The contract section is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. +The `contracts` array is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. Each contract is detailed using the `Contract` subschema. ````{admonition} Example :class: hint @@ -254,7 +254,7 @@ The contract section is used to provide details of contracts that have been ente ### Implementation -Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. The implementation sub-schema includes the following fields: +Implementation information can be updated over the course of a contract. The `implementation` array belongs nested within the contract it relates to. The `Implementation` subschema includes the following fields: ````{admonition} Example :class: hint @@ -296,7 +296,7 @@ Information on subcontracts is not currently included in the core OCDS schema, b :collapse: providerOrganization,receiverOrganization,amount,payer,payee,value ``` -The `Transaction` sub-schema 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) object, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. +The `Transaction` subschema 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) object, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. ```{note} To represent planned payments, use [Milestones](#milestones) instead. @@ -324,7 +324,7 @@ See [document](#document) reference below. A release may amend values from a previous release. Whilst the release & record model of OCDS offers the opportunity to keep a full versioned history of changes, in many cases it is important for changes to a tender, award or contract to be explicitly declared. -The amendment array in a tender, award or contract objects provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. +The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. Each amendment is detailed using the `Amendment` subschema. ````{admonition} Example :class: hint @@ -355,9 +355,9 @@ Structured information on the former value of specific fields may be provided in See the [amendment implementation guidance](../guidance/map/amendments) for more details. ``` -## Sub-schema reference +## Subschema reference -The following sub-schemas are commonly re-used throughout the standard. +The following subschemas are commonly re-used throughout the standard. ### OrganizationReference @@ -367,8 +367,8 @@ See the [parties](#parties) section. An organization reference consists of two main components: -* An `id` used to cross-reference the entry in the [parties](#parties) section that contains full information on this organization; -* A `name` field that repeats the name given in the [parties](#parties) section, provided for the convenience of users viewing the data, and to support detection of mistakes in cross-referencing. +* An `id` used to cross-reference the entry in the [parties](#parties) array that contains full information on this organization; +* A `name` field that repeats the name given in the [parties](#parties) array, provided for the convenience of users viewing the data, and to support detection of mistakes in cross-referencing. ````{admonition} Example :class: hint @@ -385,11 +385,11 @@ An organization reference consists of two main components: ### Organization -See the [parties](#parties) section. +See the [Parties](#parties) section. #### Identifier -The identifier sub-schema provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. +The identifier subschema provides a way to [identify the legal entities](identifiers.md#organization-identifiers) involved in a contracting (or planning) process. 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). @@ -441,7 +441,7 @@ When describing an organizational unit (for example, a department or branch of a ### Document -Documents can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each documents array can consist of multiple documents, classified using the [documentType](codelists.md#document-type) codelist. +Documents can be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation. Each `documents` array 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). @@ -451,7 +451,7 @@ OCDS allows summarizing information in the document's `description` field. Provi If a document contains multiple languages, use the `languages` field to list the languages used in the document. If there are multiple versions of a document, each in a different language, add a separate `Document` object for each version of the document. -If an alternative representation of the data in an OCDS release exists, a link should be provided in the relevant `.documents` array. For example, if the data in an OCDS award release is also available as an HTML page, a link to the HTML page should be provided in `awards.documents`. Links to alternative representations of an entire contracting process should be provided in `tender.documents`. +If an alternative representation of the data in an OCDS release exists, a link should be provided in the relevant `documents` array. For example, if the data in an OCDS award release is also available as an HTML page, a link to the HTML page should be provided in `awards.documents`. Links to alternative representations of an entire contracting process should be provided in `tender.documents`. ````{admonition} Example :class: hint @@ -472,7 +472,7 @@ If an alternative representation of the data in an OCDS release exists, a link s ### Period -A period has a start date, end date, and/or duration. Start and end dates are represented using date-times. Durations are represented as a number of days. +A period has a start date, end date, and/or duration. Start and end dates are represented using date-times. Durations are represented as a number of days. Periods can also include a `maxExtentDate` which indicates the latest possible end date of this period, or the latest date up until which the period could be extended without an amendment. @@ -515,7 +515,7 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The `Item` sub-schema is used to describe the line-items associated with a tender, award or contract. +The `Item` subschema is used to describe the line-items associated with a tender, award or contract. ````{admonition} Example :class: hint @@ -537,7 +537,7 @@ The `Item` sub-schema is used to describe the line-items associated with a tende #### Unit -The `unit` sub-schema allows detailed specification of the parameters and price of units that make up a line-item. +The `unit` subschema allows detailed specification of the parameters and price of units that make up a line-item. If the [Quantities, Units, Dimensions and Data Types Ontologies](https://www.qudt.org) unit classification scheme is used, then publishers can use its CamelCase unit names, such as "SquareMile", in the `unit.name` field. @@ -577,13 +577,13 @@ Other unit classification schemes can be used, including those in the [unitClass Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. -The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` either updated, or re-confirmed. +The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` field either updated, or re-confirmed. ```{seealso} [How to represent planned payments](../guidance/map/milestones.md#delivery-and-payment-data) ``` -For delivery milestones, if there is a time frame for delivery, use `.dueAfterDate` for the start date and `.dueDate` for the end date. +For delivery milestones, if there is a time frame for delivery, use `dueAfterDate` for the start date and `dueDate` for the end date. ````{admonition} Example :class: hint @@ -639,10 +639,10 @@ In OCDS each contracting process can have only one tender stage. There are a num * When one planning process results in many tenders; * When a contract is awarded following two distinct, but related, tender processes, such as in national frameworks with locally run mini-competitions; -* When a contract results in the award of sub-contracts - and those sub-contracts are also tracked using OCDS; +* When a contract results in the award of subcontracts - and those subcontracts are also tracked using OCDS; * When a contract is coming up for renewal or replacement, and there is a contracting process to award the renewal/replacement contract; -In all these cases, the `relatedProcess` sub-schema should be used to cross-reference between the relevant contracting processes using their `ocid`. +In all these cases, the `relatedProcess` subschema should be used to cross-reference between the relevant contracting processes using their `ocid`. ````{admonition} Example :class: hint @@ -661,13 +661,13 @@ A related process can be declared at two points in an OCDS release. **(1) At the release level** - used to point backwards to prior processes, such as planning or framework establishment. -**(2) At the contract level** - used to point onward to sub-contracts, renewal or replacement processes that relate solely to the particular contract the field appears in. +**(2) At the contract level** - used to point onward to subcontracts, renewal or replacement processes that relate solely to the particular contract the field appears in. As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant `documents` arrays. For example: -* When recording a `release/relatedProcess` pointing to the ocid of the planning process that resulted in a tender, a `tender/documents` entry with a `documentType` of 'procurementPlan' and a link to web pages about the procurement plan could be provided; -* When recording a `contract/relatedProcess` pointing to the ocid of a sub-contracting process, a `contract/documents` entry with a `documentType` of 'subContract' and a title that describes it as the subcontracting process, could be provided; -* When recording a `contract/relatedProcess` pointing to the ocid of a contracting process to renew a given contract, a `contract/documents` entry with a `documentType` of 'tenderNotice' and a title that describes it as the successor process, could be provided; +* When recording a `release.relatedProcess` pointing to the ocid of the planning process that resulted in a tender, a `tender.documents` entry with a `documentType` of 'procurementPlan' and a link to web pages about the procurement plan could be provided; +* When recording a `contract.relatedProcess` pointing to the ocid of a sub-contracting process, a `contract.documents` entry with a `documentType` of 'subContract' and a title that describes it as the subcontracting process, could be provided; +* When recording a `contract.relatedProcess` pointing to the ocid of a contracting process to renew a given contract, a `contract.documents` entry with a `documentType` of 'tenderNotice' and a title that describes it as the successor process, could be provided; ### Location @@ -675,7 +675,7 @@ The [Location](https://extensions.open-contracting.org/en/extensions/location/v1 ### Link -The entries of the top-level `links` array are `Link` objects: +The entries of the `links` array are `Link` objects: ```{field-description} ../../build/current_lang/release-schema.json /properties/links ``` From 793a5a62c953e14253d3a846aaa243b739291437 Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:22:48 +0000 Subject: [PATCH 12/17] Apply suggestions from code review Co-authored-by: Duncan Dewhurst --- docs/guidance/build/system_architectures.md | 2 +- docs/guidance/map/extensions.md | 2 +- docs/guidance/map/milestones.md | 2 +- docs/guidance/map/organization_personal_identifiers.md | 2 +- docs/guidance/map/organizational_units.md | 10 +++++----- docs/history/changelog.md | 4 ++-- docs/schema/codelists.md | 2 +- docs/schema/index.md | 2 +- docs/schema/reference.md | 6 +++--- 9 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/guidance/build/system_architectures.md b/docs/guidance/build/system_architectures.md index 8b97762d8..e8e3c3e22 100644 --- a/docs/guidance/build/system_architectures.md +++ b/docs/guidance/build/system_architectures.md @@ -74,7 +74,7 @@ This approach puts the burden of data conversion on data sources. Yet it might b This approach might also be suitable to combine data from many data sources. Each source becomes an OCDS publisher. The middleware becomes less complex since it only ingests data in a single format. -The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses OCDS subschema as the foundation for data sources' data models. +The [OpenProcurement](http://openprocurement.org/en/) system adopted a similar approach. This system was developed in Ukraine and it's the base for the [Prozorro](https://prozorro.gov.ua/en/) platform. Prozorro uses the OCDS schema as the foundation for data sources' data models. A variant in this scenario is to store files in a web-accessible file system, as shown below. A periodical invocation of the conversion module updates the file system. diff --git a/docs/guidance/map/extensions.md b/docs/guidance/map/extensions.md index e6a8dda81..390a648fc 100644 --- a/docs/guidance/map/extensions.md +++ b/docs/guidance/map/extensions.md @@ -1,6 +1,6 @@ # Extensions -OCDS provides a common core of [sections](../../schema/reference.md#release-structure) and [subschemas](../../schema/reference.md#subschema-reference) for describing contracting (or planning) processes. +OCDS provides a common core of [fields](../../schema/reference.md#release-structure) and [subschemas](../../schema/reference.md#subschema-reference) for describing contracting (or planning) processes. Many publishers will have additional data that they could publish. Instead of ignoring this data and leaving it unpublished, OCDS encourages publishers to collaborate on the creation of **extensions** to the standard. diff --git a/docs/guidance/map/milestones.md b/docs/guidance/map/milestones.md index 67e804c4f..95b4524b5 100644 --- a/docs/guidance/map/milestones.md +++ b/docs/guidance/map/milestones.md @@ -17,7 +17,7 @@ If during the planning process you have information about tender process milesto ## Tender Tender milestones describe: - * Key dates in the tender and award stages which are not covered by other fields, for example, the date by which procuring entity will respond to enquiries. + * Key dates in the tender and award stages which are not covered by other fields, for example, the date by which the procuring entity will respond to enquiries. * Anticipated milestones during the contract implementation stage, for example, the date by which goods need to be delivered. ## Contract diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index 18a7daf0f..f4d460bcd 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -11,7 +11,7 @@ Details of natural persons can be disclosed using the `parties` section in OCDS * The natural person is a tenderer or supplier; and * The laws in your jurisdiction permit the publication of such details -Subject to the above, you can disclose identifiers for natural persons using the `identifier` field. +Subject to the above, you can disclose identifiers for natural persons using the `parties.identifier` object. There are two components to an identifier in OCDS: diff --git a/docs/guidance/map/organizational_units.md b/docs/guidance/map/organizational_units.md index f2ff6807d..c8311cc84 100644 --- a/docs/guidance/map/organizational_units.md +++ b/docs/guidance/map/organizational_units.md @@ -8,20 +8,20 @@ For some use cases, publishers might need to disclose the organizational units i There is more than one approach to model organizational units in OCDS: -1. **Use the fields available in the Organization subschema**. This is the preferred approach, when possible. +1. **Use the fields available in the `Organization` subschema**. This is the preferred approach, when possible. * 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` objects can be filled with the unit information. * Unit identifiers can also be appended to `parties/id`. -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 under the `details` field of the `Organization` subschema. +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 under the `Organization.details` object. 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. ## Worked examples -### 1. Using the Organization subschema +### 1. Using the `Organization` subschema 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. @@ -35,7 +35,7 @@ An identifier for the hospital has been added using the "HN-ONCAE-UNIT" list cod :title: release ``` -### 2. Defining a new Extension +### 2. Creating 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` object 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. @@ -63,7 +63,7 @@ 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 subschema with an organizational hierarchy +### 3. Using the `Organization` subschema with an organizational hierarchy 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. diff --git a/docs/history/changelog.md b/docs/history/changelog.md index 568150a9f..918c86813 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -593,7 +593,7 @@ See the changelogs for: ### Added -* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new `relatedProcesses` field at the release and contract level +* [#371](https://github.com/open-contracting/standard/issues/371) [#439](https://github.com/open-contracting/standard/pull/439) **[Linking related processes](../schema/reference.md#relatedprocess)** - We have introduced a new `relatedProcesses` array at the release and contract level * [#374](https://github.com/open-contracting/standard/issues/374) **[Duration in periods](../schema/reference.md#period)** - We have introduced fields for duration in days, and maximum extent, to the `Period` subschema * [#374](https://github.com/open-contracting/standard/issues/374) **[Contract and Award Periods in Tender](../schema/reference.md#tender)** - We have introduced contract period in tender and updated the definition of award period. * [#376](https://github.com/open-contracting/standard/issues/376) **[Contract type (supplies, works and services)](../schema/codelists.md#procurement-category)** - We have introduced a procurementCategory field to specify whether contracts are for supplies, works, services, consultancyServices or mixed @@ -607,7 +607,7 @@ See the changelogs for: * [#342](https://github.com/open-contracting/standard/issues/342) **[Overall contracting process description](../schema/reference.md#release)** - We have introduced a new top-level title and description for the contracting process as a core extension. * [#274](https://github.com/open-contracting/standard/issues/274) **[New property of contract: extendsContractID](../schema/reference.md#contract)** - We have introduced a new field 'extendsContractID' to the `Contract` subschema to support contract cross-referencing between contracts. * [#381](https://github.com/open-contracting/standard/issues/381) **[Lots](https://extensions.open-contracting.org/en/extensions/lots/)** - We have introduced a core extension to provide a model for contracting processes which are divided into lots. -* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top-level Bids section, with BidStatistics and Bid sub-schemas for detailed information on individual bids. This supersedes the current tender/tenderers section. +* [#379](https://github.com/open-contracting/standard/issues/379) **[Bids and Bid Statistics](https://extensions.open-contracting.org/en/extensions/bids/)** - We have introduced a core extension which provides a top-level `bids` array, with `BidStatistics` and `Bid` subschemas for detailed information on individual bids. This supersedes the current `tender/tenderers` array. * [#250](https://github.com/open-contracting/standard/issues/250) **[Location extension](https://extensions.open-contracting.org/en/extensions/location/)** - We have moved the location extensions to become a core extension * [#33](https://github.com/open-contracting/standard/issues/33) **[Participation fees (bid document and submission costs)](https://extensions.open-contracting.org/en/extensions/participation_fee/)** - We have introduced a core extension for declaring the participation fees related to a contracting process. * [#249](https://github.com/open-contracting/standard/issues/249) **[Extend contract with a supplier array](https://extensions.open-contracting.org/en/extensions/contract_suppliers/)** - We have introduced a core extension to allow inclusion of supplier information at the contract level. diff --git a/docs/schema/codelists.md b/docs/schema/codelists.md index 1bc5c1278..048737d82 100644 --- a/docs/schema/codelists.md +++ b/docs/schema/codelists.md @@ -155,7 +155,7 @@ The related process scheme describes the kind of identifier used to cross-refere ```{versionadded} 1.1 ``` -The `Milestone` subschema can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. +The [`Milestone` subschema](reference.md#milestone) can be used to represent a wide variety of events in the lifetime of a contracting (or planning) process. The milestone type codelist is used to indicate the nature of each milestone. ```{csv-table-no-translate} :header-rows: 1 diff --git a/docs/schema/index.md b/docs/schema/index.md index 58099de6f..a5ce918f0 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -4,7 +4,7 @@ The Open Contracting Data Standard is maintained using JSON Schema. In this section you will find the schemas for [releases](release) and [records](record) along with the schemas for [packaging](packaging/index.md), which act as envelopes for releases and records. -The [release schema reference](reference) provides guidance on using each of the [sections](reference.md#release-structure) and [subschemas](reference.md#subschema-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. +The [release schema reference](reference) provides guidance on using each of the [fields](reference.md#release-structure) and [subschemas](reference.md#subschema-reference) in the schema, and the [record schema reference](records_reference) provides additional information on publishing records with compiled and versioned releases. OCDS data must follow the I-JSON (Internet JSON) specification in [RFC7493](https://tools.ietf.org/html/rfc7493), according to which JSON text must be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8), and which introduces a number of requirements for numbers, objects and dates. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 938b072d9..f27d565e1 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -274,7 +274,7 @@ The `contracts` array is used to provide details of contracts that have been ent ### Implementation -Implementation information can be updated over the course of a contract. The `implementation` array belongs nested within the contract it relates to. The `Implementation` subschema includes the following fields: +Implementation information can be updated over the course of a contract. The `implementation` object belongs nested within the contract it relates to. It includes the following fields: ````{admonition} Example :class: hint @@ -387,7 +387,7 @@ See the [parties](#parties) section. An organization reference consists of two main components: -* An `id` used to cross-reference the entry in the [parties](#parties) array that contains full information on this organization; +* An `id` used to cross-reference the object in the [parties](#parties) array that contains full information on this organization; * A `name` field that repeats the name given in the [parties](#parties) array, provided for the convenience of users viewing the data, and to support detection of mistakes in cross-referencing. ````{admonition} Example @@ -535,7 +535,7 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The `Item` subschema is used to describe the line-items associated with a tender, award or contract. +The `Item` subschema is used to represent the line-items associated with a tender, award or contract. ````{admonition} Example :class: hint From e685a9abf583467a9e7ded29e86624797d3d9b9a Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 7 Nov 2024 10:26:31 +0000 Subject: [PATCH 13/17] update organization_personal_identifiers.md section to array language --- docs/guidance/map/organization_personal_identifiers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guidance/map/organization_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md index f4d460bcd..74ed686f1 100644 --- a/docs/guidance/map/organization_personal_identifiers.md +++ b/docs/guidance/map/organization_personal_identifiers.md @@ -6,7 +6,7 @@ Suppliers and tenderers can be organizations or individuals (natural persons). Such individuals are often referred to as "sole traders" or "self-employed individuals". -Details of natural persons can be disclosed using the `parties` section in OCDS only if: +Details of natural persons can be disclosed using the `parties` array in OCDS only if: * The natural person is a tenderer or supplier; and * The laws in your jurisdiction permit the publication of such details @@ -27,7 +27,7 @@ Follow the [guidance](https://standard.openownership.org/en/0.2.0/schema/guidanc In the example below: * 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 is listed in the `parties` array 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') From 198563675ce1585789d701576ab4873c92840899 Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 7 Nov 2024 10:44:44 +0000 Subject: [PATCH 14/17] releases_and_records.md update subschema language --- docs/primer/releases_and_records.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/primer/releases_and_records.md b/docs/primer/releases_and_records.md index 0bf5231f5..9ba932cb6 100644 --- a/docs/primer/releases_and_records.md +++ b/docs/primer/releases_and_records.md @@ -38,7 +38,7 @@ Each time a new release is published it is added to the index, the compiled rele ![A contracting (or planning) process is described by many releases, which are aggregated into a single record](../_static/png/change_history_process_record.png) -Records and releases each contain several fields which can be used in different sections. The OCDS schema sets out the fields that ought to be included in each section (where applicable), aiming to reuse simple structures to represent information. For example, a release may contain information about items being procured. OCDS’ schema sets out a standard subschema for items across releases, including the name of the item, a description, each item’s value, and the currency used. +Some concepts are common to several stages of the contracting (or planning) process. The OCDS schema provides reusable subschemas to represent common concepts. For example, the [`Item` subschema](../schema/reference.md#item) represents the items to be procured at the tender stage, awarded at the award stage and contracted at the contract stage. It contains fields applicable to any of these stages, such as an item's title, description and value. When you publish OCDS releases and records, you are encouraged to: From 585e1a1655d548853ab7ee4c7b628e3c40e835be Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 12 Nov 2024 15:41:38 +0000 Subject: [PATCH 15/17] release_and_records.md: grammar typo correction --- docs/primer/releases_and_records.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/primer/releases_and_records.md b/docs/primer/releases_and_records.md index 9ba932cb6..da4b3ec85 100644 --- a/docs/primer/releases_and_records.md +++ b/docs/primer/releases_and_records.md @@ -38,7 +38,7 @@ Each time a new release is published it is added to the index, the compiled rele ![A contracting (or planning) process is described by many releases, which are aggregated into a single record](../_static/png/change_history_process_record.png) -Some concepts are common to several stages of the contracting (or planning) process. The OCDS schema provides reusable subschemas to represent common concepts. For example, the [`Item` subschema](../schema/reference.md#item) represents the items to be procured at the tender stage, awarded at the award stage and contracted at the contract stage. It contains fields applicable to any of these stages, such as an item's title, description and value. +Some concepts are common to several stages of the contracting (or planning) process. The OCDS schema provides reusable subschemas to represent common concepts. For example, the [`Item` subschema](../schema/reference.md#item) represents the items to be procured at the tender stage, and the items to be contracted at the contract stage. It contains fields applicable to any of these stages, such as an item's title, description and value. When you publish OCDS releases and records, you are encouraged to: From 3cd83c417f3dc524b014040b8c9fe81d67676890 Mon Sep 17 00:00:00 2001 From: odscjen Date: Mon, 18 Nov 2024 11:45:12 +0000 Subject: [PATCH 16/17] reference.md: apply review suggestions --- docs/schema/reference.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index f27d565e1..6710d6628 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -222,7 +222,7 @@ The [Bid statistics and details](https://extensions.open-contracting.org/en/exte ### Award -The `awards` array is used to announce any awards issued for this tender. There can be multiple awards made, each of which must be detailed using the `Award` subschema. Releases can contain all, or a subset, of these awards. Awards contain information about suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). +The `awards` array is used to announce any awards issued for this tender. Releases can contain all, or a subset, of these awards. Awards contain information about suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of [consortia](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). ````{admonition} Example :class: hint @@ -233,6 +233,8 @@ The `awards` array is used to announce any awards issued for this tender. There ``` ```` +The items in the `awards` array are `Award` objects. Each `Award` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Award :collapse: items,value,suppliers,contractPeriod,documents,amendment,amendments @@ -248,7 +250,7 @@ The `awards` array is used to announce any awards issued for this tender. There ### Contract -The `contracts` array is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. Each contract is detailed using the `Contract` subschema. +The `contracts` array is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the `awardID` field. This is because supplier information is contained within the 'award'. ````{admonition} Example :class: hint @@ -259,6 +261,8 @@ The `contracts` array is used to provide details of contracts that have been ent ``` ```` +The items in the `contracts` array are `Contract` objects. Each `Contract` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Contract :collapse: period,value,items,documents,implementation,relatedProcesses,milestones,amendment,amendments @@ -344,7 +348,7 @@ See [document](#document) reference below. A release may amend values from a previous release. Whilst the release & record model of OCDS offers the opportunity to keep a full versioned history of changes, in many cases it is important for changes to a tender, award or contract to be explicitly declared. -The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. Each amendment is detailed using the `Amendment` subschema. +The `amendments` array in a `tender`, `Award` or `Contract` object provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment. ````{admonition} Example :class: hint @@ -355,6 +359,9 @@ The `amendments` array in a `tender`, `Award` or `Contract` object provides the ``` ```` +The items in the `amendments` array are `Amendment` objects. Each `Amendment` has the following fields: + + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Amendment :collapse: changes From b8b7ca73ed0fb665048b1841ed287044447029fe Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 21 Nov 2024 09:58:36 +0000 Subject: [PATCH 17/17] reference.md: copy edit grammar fix --- docs/schema/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 6710d6628..16e7aadb7 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -618,7 +618,7 @@ Other unit classification schemes can be used, including those in the [unitClass ### Milestone -Milestone information can be included in the [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. +Milestone information can be included in [planning](#planning), [tender](#tender), [contract](#contract) and [contract implementation](#implementation) objects. The `dateModified` field should be changed whenever the progress towards a milestone is reviewed, and the `status` field either updated, or re-confirmed.