open-contracting · odscjen · Nov 17, 2023 · Nov 17, 2023 · Nov 17, 2023 · Nov 17, 2023
diff --git 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 subschema"
   },
   "documentationUrl": {
     "en": "http://github.com/example_publisher/ocds_division_code_extension"

diff --git a/docs/guidance/build/merging.md b/docs/guidance/build/merging.md
@@ -48,9 +48,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` array 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
@@ -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 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/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** field (`tag`), which is used to identify the type of change. For example, 'contract' identifies information about a new contract, 'contractUpdate' identifies an update to existing information about a contract, and 'contractAmendment' identifies a formal amendment to a contract.
 
-* **The amendments** fields (`tender.amendments`, `awards.amendments` and `contracts.amendments`), which are used to list amendments along with their rationales and references to the releases that contain "before" and "after" values.
+* **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
 
@@ -109,7 +109,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
@@ -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 [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
@@ -8,28 +8,25 @@ Milestones can be included within the planning, tender, contract and contract im
 
 ## Planning
 
-The planning milestones block 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 block instead.
+If during the planning process you have information about tender process milestones, then you ought to publish it as a tender milestone.
 
 ## Tender
 
-The tender milestones block 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 the buyer or procuring entity will respond to enquiries.
+Tender milestones describe:
+  * 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
 
-The contract milestones block 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 block is used to describe:
-  * Any events related to the delivery of the contract, for example, the agreed date by which goods will be delivered.
+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
@@ -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` 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
 
-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).
+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).
 
@@ -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` 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_personal_identifiers.md b/docs/guidance/map/organization_personal_identifiers.md
@@ -6,12 +6,12 @@
 
 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
 
-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 `parties.identifier` object.
 
 There are two components to an identifier in OCDS:
 
@@ -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')
 

diff --git 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` 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