Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

remove mention of building blocks and blocks from documentation #1660

Open
wants to merge 23 commits into
base: 1.2-dev
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
9276a14
remove mention of building blocks and blocks from documentation
odscjen Nov 17, 2023
ebac7d4
update changelog.md
odscjen Nov 17, 2023
6e8e9d8
update index.md
odscjen Nov 17, 2023
c7595c3
fix typo in index.md
odscjen Nov 17, 2023
9b9e02f
update reference.md
odscjen Nov 17, 2023
6b70cd5
Apply suggestions from code review
odscjen Nov 28, 2023
2626707
Apply further suggestions from code review
odscjen Nov 28, 2023
a756f70
Merge branch '1.2-dev' into 1347_building_blocks
odscjen Dec 5, 2023
a068ac6
examples: building block -> sub-schema
jpmckinney Dec 5, 2023
038c800
documentType.csv:remove mentions of blocks
odscjen Dec 7, 2023
3e1a585
Merge branch '1.2-dev' into 1347_building_blocks
jpmckinney Dec 14, 2023
12b7af0
Apply suggestions from code review
odscjen Dec 15, 2023
112120c
Merge branch '1.2-dev' into 1347_building_blocks
odscjen Feb 2, 2024
074c946
style adjustments re use of field/array/object/subschema consistently
odscjen Feb 2, 2024
12d4371
Merge branch '1.2-dev' into 1347_building_blocks
odscjen Apr 11, 2024
9fe855d
Merge branch '1.2-dev' into 1347_building_blocks
odscjen Jul 3, 2024
793a5a6
Apply suggestions from code review
odscjen Nov 7, 2024
e685a9a
update organization_personal_identifiers.md section to array language
odscjen Nov 7, 2024
ea468d7
Merge branch '1.2-dev' into 1347_building_blocks
odscjen Nov 7, 2024
1985636
releases_and_records.md update subschema language
odscjen Nov 7, 2024
585e1a1
release_and_records.md: grammar typo correction
odscjen Nov 12, 2024
3cd83c4
reference.md: apply review suggestions
odscjen Nov 18, 2024
b8b7ca7
reference.md: copy edit grammar fix
odscjen Nov 21, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/guidance/build/merging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

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:
Expand Down
2 changes: 1 addition & 1 deletion docs/guidance/build/system_architectures.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
10 changes: 5 additions & 5 deletions docs/guidance/map/amendments.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

## Worked examples

Expand Down Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

```{jsoninclude} ../../examples/amendments/tender.json
:jsonpointer: /records/0/releases/2
Expand All @@ -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:
Expand All @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

* **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.

Expand All @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

See the example release below.

Expand Down
2 changes: 1 addition & 1 deletion docs/guidance/map/extensions.md
Original file line number Diff line number Diff line change
@@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

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.

Expand Down
10 changes: 5 additions & 5 deletions docs/guidance/map/milestones.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
odscjen marked this conversation as resolved.
Show resolved Hide resolved
* 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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

## 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:
odscjen marked this conversation as resolved.
Show resolved Hide resolved
* 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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved
* 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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

## 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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

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.
Expand Down
6 changes: 3 additions & 3 deletions docs/guidance/map/organization_classifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

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.

Expand Down Expand Up @@ -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).
odscjen marked this conversation as resolved.
Show resolved Hide resolved

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).

Expand Down Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

```{jsoninclude} ../../examples/organizations/organization_classification/dhangadhi_female_chaired_example.json
:jsonpointer:
Expand Down
2 changes: 1 addition & 1 deletion docs/guidance/map/organization_personal_identifiers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
odscjen marked this conversation as resolved.
Show resolved Hide resolved
* 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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved

There are two components to an identifier in OCDS:

Expand Down
2 changes: 1 addition & 1 deletion docs/guidance/map/organization_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
odscjen marked this conversation as resolved.
Show resolved Hide resolved
* The same needs to be applied to each `OrganizationReference` instance.

```{jsoninclude} ../../examples/organizations/organization_reference.json
Expand Down
Loading