Style guides

This page contains style guides for authoring and editing schema, codelists and documentation.

Schema style guide

Field descriptions

Codelists

Use the following template, noting that any _ characters in the codelist title need to be replaced with the - character in the codelist URL:

The <semantics>, from the <open|closed> [<codelist_title> codelist](https://docs.riskdatalibrary.org/en/{{version}}/reference/codelists/#codelist-title).

Changelog style guide

• Use the Keep a Changelog format.
• Begin each entry with a link to the pull request for the change.

Normative content

Changelog entries should be descriptive:

• Bad entry: Update schema.
• Good entry: Make name required.

If changes are made to files under the schema directory, it is assumed that corresponding changes were made to files under the docs directory. Do not add an entry under the "Documentation" heading if the changes directly correspond to entries under the "Codelists" and/or "Schema" headings.

For changes to schema and codelists, preserve schema/codelist ordering when adding new changelog entries. Otherwise, to reduce merge conflicts, add new changelog entries to the end of the relevant bullet list.

Non-normative content

Changelog entries should be descriptive. Do not add an entry like "Improve primer." Instead, simply add the PR number to the "Primer" list item.