remove mention of building blocks and blocks from documentation #1660

odscjen · 2023-11-17T15:54:12Z

Used primarily "objects" as per the section of the style guide that states

When describing JSON schema * “object”, not “block”

but did use "sub-schema" in a few instances.

There's 2 uses of "block" in the schema itself but they'll be covered by a PR for #850

duncandewhurst

I think the style guide needs updating to reflect the agreement in #1347, my understanding of which is that we should use 'sub-schema' when referring to the definitions in the schema and 'object' when referring to their representation in data. That aligns with the sentence that appears at the start of the sub-schema reference in OC4IDS, which explains the relationship between sub-schemas and objects.

Most of my suggested changes are based on that understanding, except where I've suggested replacing 'object' with 'array' in order to align with the types in the schema.

docs/guidance/build/merging.md

docs/guidance/map/amendments.md

docs/schema/reference.md

docs/schema/index.md

docs/guidance/map/extensions.md

Co-authored-by: Duncan Dewhurst <[email protected]>

jpmckinney · 2023-12-05T20:11:06Z

There are two occurrences in documentType.csv (subContract, billOfQuantity) where we can just delete the last clause. If those aren't handled by other PRs or issues, let's fix them here.

Noting that use of "block" on two occasions in the Milestone sub-schema will be fixed by #850

odscjen · 2023-12-07T12:10:47Z

I've removed the final sentences from both of those codes in documentType as I don't they were being picked up anywhere else

docs/guidance/map/organization_classifications.md

jpmckinney

I started reviewing, but having now read more content using the different available terms, I think we should prefer "field", unless the word "object" or "array" is contributing to the understanding of the sentence. Can you review with that in mind?

We can update the handbook accordingly.

docs/guidance/map/organization_classifications.md

docs/guidance/map/organization_personal_identifiers.md

docs/guidance/map/organizational_units.md

odscjen · 2023-12-15T15:48:21Z

added an issue to the handbook repo to update the style guide open-contracting/standard-development-handbook#285

Co-authored-by: James McKinney <[email protected]>

odscjen · 2024-01-09T11:48:40Z

@jpmckinney are you ok with the suggestions in open-contracting/standard-development-handbook#285 (comment), if so I'll redo this PR with those all in mind

duncandewhurst · 2024-11-05T22:09:33Z

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 subschema as the foundation for data sources' data models.


I don't think the mention of subschema here really adds anything so we can avoid it altogether.

Suggested change

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.

duncandewhurst · 2024-11-05T22:31:30Z

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 [subschemas](../../schema/reference.md#subschema-reference) for describing contracting (or planning) processes.


Per open-contracting/standard-development-handbook#285 (comment)

Suggested change

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.

duncandewhurst · 2024-11-05T22:32:08Z

docs/guidance/map/milestones.md

-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 procuring entity will respond to enquiries.


Suggested change

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

duncandewhurst · 2024-11-05T22:40:17Z

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` field.


Always use 'object' when referring to an object. Add parent to path to reduce ambiguity.

Suggested change

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.

duncandewhurst · 2024-11-05T22:40:45Z

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


I can't comment on line 9 but 'section' should be updated to 'array'.

Same on line 30.

duncandewhurst · 2024-11-05T23:37:24Z

docs/schema/reference.md


 ### Amendment

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


Suggested change

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.

duncandewhurst · 2024-11-05T23:37:57Z

docs/schema/reference.md

@@ -387,8 +387,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;


Suggested change

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

duncandewhurst · 2024-11-05T23:38:37Z

docs/schema/reference.md

@@ -535,7 +535,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 `Item` subschema is used to describe the line-items associated with a tender, award or contract.


Suggested change

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.

duncandewhurst · 2024-11-05T23:39:28Z

docs/schema/reference.md

@@ -605,15 +611,15 @@ The items block is used to list the line-items associated with a tender, award o

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


Suggested change

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.

duncandewhurst · 2024-11-05T23:41:10Z

docs/schema/reference.md

@@ -669,10 +675,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;


The RelatedProcess reference needs updating per #1713 so I haven't reviewed the changes here.

remove mention of building blocks and blocks from documentation

9276a14

odscjen requested a review from duncandewhurst November 17, 2023 15:54

odscjen added 4 commits November 17, 2023 16:00

update changelog.md

ebac7d4

update index.md

6e8e9d8

fix typo in index.md

c7595c3

update reference.md

9b9e02f

duncandewhurst requested changes Nov 21, 2023

View reviewed changes

odscjen and others added 3 commits November 28, 2023 11:13

Apply suggestions from code review

6b70cd5

Co-authored-by: Duncan Dewhurst <[email protected]>

Apply further suggestions from code review

2626707

Merge branch '1.2-dev' into 1347_building_blocks

a756f70

odscjen requested a review from jpmckinney December 5, 2023 15:27

jpmckinney and others added 2 commits December 5, 2023 15:11

examples: building block -> sub-schema

a068ac6

documentType.csv:remove mentions of blocks

038c800

Merge branch '1.2-dev' into 1347_building_blocks

3e1a585

jpmckinney reviewed Dec 14, 2023

View reviewed changes

docs/guidance/map/organization_classifications.md Outdated Show resolved Hide resolved

jpmckinney reviewed Dec 14, 2023

View reviewed changes

odscjen mentioned this pull request Dec 15, 2023

Word choice: field preferred over object or array open-contracting/standard-development-handbook#285

Open

Apply suggestions from code review

12b7af0

Co-authored-by: James McKinney <[email protected]>

odscjen and others added 2 commits February 2, 2024 17:00

Merge branch '1.2-dev' into 1347_building_blocks

112120c

style adjustments re use of field/array/object/subschema consistently

074c946

odscjen requested a review from jpmckinney February 7, 2024 09:55

odscjen added 2 commits April 11, 2024 09:37

Merge branch '1.2-dev' into 1347_building_blocks

12d4371

Merge branch '1.2-dev' into 1347_building_blocks

9fe855d

odscjen requested a review from duncandewhurst October 31, 2024 15:12

jpmckinney mentioned this pull request Oct 31, 2024

Docs: Refactor/review linked guidance usage, and move jsonschema directive to end of sections #1467

Open

duncandewhurst mentioned this pull request Nov 1, 2024

Change order of codelists in Reference #1405

Open

duncandewhurst requested changes Nov 5, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

remove mention of building blocks and blocks from documentation #1660

remove mention of building blocks and blocks from documentation #1660

odscjen commented Nov 17, 2023 •

edited

Loading

duncandewhurst left a comment

jpmckinney commented Dec 5, 2023

odscjen commented Dec 7, 2023

jpmckinney left a comment

odscjen commented Dec 15, 2023

odscjen commented Jan 9, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

duncandewhurst Nov 5, 2024

	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.

	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.

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

	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.

		@@ -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 `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.

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

	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.

	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.

remove mention of building blocks and blocks from documentation #1660

Are you sure you want to change the base?

remove mention of building blocks and blocks from documentation #1660

Conversation

odscjen commented Nov 17, 2023 • edited Loading

duncandewhurst left a comment

Choose a reason for hiding this comment

jpmckinney commented Dec 5, 2023

odscjen commented Dec 7, 2023

jpmckinney left a comment

Choose a reason for hiding this comment

odscjen commented Dec 15, 2023

odscjen commented Jan 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

odscjen commented Nov 17, 2023 •

edited

Loading