Common conventions#

This style guide covers our conventions when writing:

  • OFDS schema and standard documentation

  • GitHub issues

  • Resources and guidance for publishers and users

  • Training materials

  • Associated presentations and documents

Readability#

We strive to write concise, clear documentation. To improve your writing, please learn how to write for the web (with many more resources at Nielsen Norman Group, and consider using these tools:

Spelling#

Use British English (e.g. “organisation” rather than “organization”) unless aligning a field name with an existing standard that uses alternative spellings. Notably, this means being careful about using “s” instead of “z” in many words of Latin origin.

Text formatting#

  • Do not use constructions like “node(s)” or “the node (or nodes)”. The plural is fine, like “nodes”.

  • Do not use smart quotation marks like “ ” ‘ ’. Use simple quotation marks like " '.

  • When referring to a field or codelist, use the camelCase version of the field/codelist name, and enclose it in backticks so it is displayed in a montotype font as follows: camelCase

  • When referring to a building block, use the capitalized CamelCase version of the building block name, and enclose it in backticks so it is displayed in a montotype font as follows: CamelCase

  • When referring to a code from a codelist, enclose the value in single quotes, e.g. “We have added an ‘aerial’ code to the deploymentType codelist”. Note that true and false are not codes; they are boolean values.

  • When pluralizing a field or building block, treat the field/building block name as a proper noun, and add a 's instead of an s to the end, or treat it as a mass noun and add nothing to the end

  • When referring to a field in JSON Schema, use dot notation, like tender.id. (Slash notation is reserved for JSON Pointer. For example, the JSON Pointer for tender.id is /definitions/Tender/properties/id.)

  • When referring to a field in OFDS data, use a JSON Pointer, like /nodes/id.

Word choice#

  • “codelist” not “code-list” or “code list”

  • “changelog” not “change-log” or “change log”

  • “metadata” not “meta-data” or “meta data”

  • “hyphen” not “dash”, to describe the “-” character

When describing data:

  • “publication” for the data source that persists across time

  • “collection” for the publication’s data at a specific point in time

  • “JSON data” not “JSON document”, to avoid confusion with the documents field

  • “geospatial data” not “geodata” or “geo data” or “geographical data” or “spatial data”

When describing JSON Schema:

  • “field” to refer to OFDS fields, like links.deployment

  • “property” to refer to JSON Schema metadata properties, like enum

  • “array” not “list”

  • “object” not “block”

When referring to a field, prefer the notation for the path in the data, like links.transmissionMedium, rather than the notation for the path in the schema, like Link.transmissionMedium.

These regular expressions can be used to find breaches of the style guide, accounting for false positives.

property

(?<!(`minLength| `required|geStrategy)` )propert(y|ies)

data path notation

\b[A-Z][a-zA-Z]+\.(?!(aspx|db|html|md|org|xml|zip)\b)[a-zA-Z]{2,}

JSON example filenames#

  • Name the JSON example with a descriptive, lower-case filename, with underscores between words.

  • Store the example in the docs/examples directory in the standard’s repository. Create a sub-directory to group related examples, if one doesn’t exists already, rather than using a common prefix to the filename.

  • If you need to make a file downloadable, don’t place it in docs/_static/, instead use the download role, e.g.:

   {download} [link text](../../examples/file)

Images

  • Create the image, preferably using easily accessible collaborative tools like Google Drawings.

  • Store the editable version in the this Google Drive folder.

  • Export the image in PNG format.

  • Use a descriptive, lower-case filename, with underscores between words.

  • Store the exported version in the docs/_static/png directory in the standard’s repository. Create a sub-directory to group related images, as needed, rather than using a common prefix to the filename.