Word choice: field preferred over object or array

[odscjen]

As part of the PR to remove instances of "block" and "building block" decision is now to use "field" to refer to json elements rather than "object" or "array" unless referring to them as such is specifically contributing to the understanding of the sentence. See open-contracting/standard#1660 (review)

[odscjen]

Also refer to top level fields as "section", e.g. the parties section. (the documentation is currently inconsistent in applying this but it is used in what feels like the bulk of instances)

[jpmckinney]

I think we can use field/object/array instead of section.

[odscjen]

Having started going through all of documentation to address this I think the following should be added to the style guide to help with this and the related language issues. (the language of my suggestions needs refined but the basic ideas are hopefully sound)

• Refer to top level elements as objects. (currently referred inconsistently using a mix of section, object and array)
• Refer to the repeatable sections of schema as sub-schema when describing them. e.g.

The Item sub-schema is used to describe the line-items associated with a tender, award or contract.

• Refer to repeatable sub-schema as objects when referencing their use in generating data, e.g.

the links array is made up of Link objects.

• Refer to an array as such if you're making mention of the fact it's made up of multiple instances of a repeatable sub-schema. Otherwise use field or object if its top level. e.g the links example above or

The contracts object is used to provide details of contracts that have been entered into.

• Refer to lower level non-repeatable parts of the schema/sub-schema as fields, unless using object would aid understanding. e.g.

OCDS allows summarizing information in the document's description field.

or

Apart from documents, the majority of planning information is held within the budget field.

(don't think using object here instead of field adds anything)

None of this is inconsistent with the current style guide, it's just adding further detail to remove some of the inconsistencies.

[jpmckinney]

Refer to top level elements as objects. (currently referred inconsistently using a mix of section, object and array)

"object" and "array" are used in their JSON sense, e.g. awards is array, tender is object. Never use "object" to describe an array, since they are different things in JSON.

"array" should always be used in contexts like "Add the 'buyer' code to the .roles array" or "Add a Lot object to the tender.lots array". The word "array" here helps clarify the use of the verb "Add" (which we should only use with arrays).

"object" is useful when we're about to talk about fields within an object.

---

To reduce ambiguity, maybe:

• Use "array" when referring to an array, always
• Use "object" when referring to an object, always
• Use "field" when referring to a literal (number, integer, string, boolean, GeoJSON), always

When referring to a subschema (i.e. Capitalized definition in the JSON schema):

• If the subschema is used in the context of building a JSON document, use "object" (e.g. add a Lot object to tender.lots)
• Otherwise, use "subschema" (do not hyphenate). However, where appropriate, consider rephrasing the sentence to be about building a JSON document (and therefore using "object").

[odscjen]

ok your suggestions look good. Just want to flag that this is going to lead to a more substantial change to the docs, particularly https://standard.open-contracting.org/latest/en/schema/reference/#release-structure than simply swapping out words like "block" (which was where this all started in open-contracting/standard#1347) EDIT: but possibly not actually that substantial now that I start looking at it again

[jpmckinney]

Hmm, okay, let me know how substantial it's looking. We want to first focus on replacing the "block" occurrences. If it turns out to be substantial, we can postpone applying the style guide for the other words.

[odscjen]

It's not actually that substantial. I was concerned that the structure of https://standard.open-contracting.org/latest/en/schema/reference/#release-structure would become slightly confusing with the change of words (and therefore require a restructure) but having gone through it now I think it's fine with just a few sentence tweaks to accommodate the word swaps.

[odscjen]

There are still various inconsistencies in that page, e.g. "Date" is included under the "Subschema reference" heading but it's not a subschema, it's a data format. Or "Document" refers only to the different stages the documents array can be attached, and "Milestone" refers only to the stage objects it can be included in, but these are the same type of subschema used in arrays so it might be clearer to a user to describe their use in the same way. But I think these sort of inconsistencies are a subject for a different issue, or maybe even things we can live with!

[jpmckinney]

Good observations! Can you add those (and any new ones) to open-contracting/standard#1075?

[odscjen]

will do, I'd forgotten there was already an issue for that page :)