Reference

This section contains reference documentation describing the technical configuration of the GitHub repository and documentation site.

GitHub repository

The project repository is hosted on GitHub.

Branches

The live (X.Y) branch for the current version is used to build the 'live' version of the standard documentation.

The staging (X.Y-dev) branch is used to stage changes to the live branch.

Feature branches branch off the staging branch, with work merged into the staging branch before finally being merged into the live branch.

Branch protection rules are configured for the live and staging branches. The rules prevent commits being made directly by requiring pull requests before commits can be merged. They also require approvals and status checks to pass before merging.

Directory structure

• .github/: Issue templates and GitHub Actions workflows
• docs/:
  • *.md, */*.md: English documentation text
  • conf.py: Sphinx configuration
  • _static/: CSS and JavaScript for the documentation
  • _templates/: Jinja templates for the documentation
  • .tx/: Transifex configuration (not yet implemented)
  • img/: Images used in the documentation
  • locale/: Translations of the English documentation (not yet implemented)
• examples: Example JSON files and figures
• schema/: schema- and codelist-related files
• specs/: TBD
• SteeringCommittee/: Minutes of steering committee meetings

The following files are created by running a build and are not version controlled:

• .temp
• docs/_readthedocs: Built HTML documentation

For a full list of non-version controlled files, see .gitignore.

Sphinx

Sphinx is the documentation generator used to build the HTML documentation from Markdown source files. It uses the MyST - Markedly Structured Text - Parser to parse the Markdown source files.

Configuration

The Sphinx configuration for this project is based on the Open Data Services Sphinx Base and is defined in docs/conf.py. As part of the documentation build process, conf.py processes the schema and codelists for inclusion in the published documentation:

Schema processing

The source schema is structured according to the principle of "Don't repeat yourself" (DRY). In practice, this means use of reusable subschemas (the $defs keyword), pointers (the $ref keyword) and inheritance (the allOf keyword).

Adhering to the DRY principle eases maintenance through avoiding repetition of information that is likely to change and minimising the length of the schema. However, the resulting schema might be difficult for end users to follow, and some features are not fully supported by elements of the tech stack.

Therefore, during the build process (defined in docs/conf.py), the source schema is processed to produce the following schema files in docs/_readthedocs/html:

• rdls_schema.json - a copy of the schema/rdls_schema.json with the following changes:
  • $defs/conditional_hazard_type_to_process populated with conditional validation logic according to the hazard type / process mapping documented in process_type.csv
  • $defs/conditional_hazard_type_to_intensity_measure populated with conditional validation logic according to the hazard type / intensity measure mapping documented in imt.csv
• rdls_schema_processed.json - the above file with the following additional changes:
  • References to definitions in the schema are dereferenced according to the JSON Schema 2020-12 specification
  • Inherited schemas defined under the allOf keyword are merged with the parent schema.
• rdls_schema_processed_browser.json - the above file with the following additional changes:
  • Any remaining allOf and anyOf keywords, typically used to implement either/or validation of required fields, are removed for compatibility with the schema browser.

In all cases, {{version}} placeholders are replaced with the current branch name / version number.

Codelist processing

conf.py outputs the following codelist files in docs/_readthedocs/html/codelists:

• Individual process_type_<hazard_type>.csv codelists for each hazard type, e.g. process_type_earthquake.csv
• Individual imt_<hazard_type>.csv codelists for each hazard type, e.g. imt_earthquake.csv

Read the Docs

Read the Docs builds and hosts the standard documentation site.

Whenever a commit is pushed to a branch in the GitHub repository, Read the Docs automatically builds the version associated with the branch and hosts it at https://rdl-standard.readthedocs.io/en/.

Configuration

https://rdl-standard.readthedocs.io/en/latest redrirects to https://rdl-standard.readthedocs.io/en/main.

Automation rules are configured to:

• Activate, build and hide a new version when a commit is pushed to a new branch in the GitHub repository.
• Delete the associated version when a branch is deleted in the GitHub repository.

Pull request builds are also enabled.

Other than the main branch, all branches are hidden from the flyout menu.

Credentials

You can find credentials for Read the Docs in the Open Data Services password database.

manage.py

The standard repository includes a command-line utility for administrative tasks. For information on the available commands, run ./manage.py --help.

Python tests

pytest and JSCC are used to run tests on the standard to mitigate the risk of updates introducing errors. The tests are stored in the tests/ directory and include the following checks:

test_csv.py

Ensures all CSV files are valid: no empty rows or columns, no leading or trailing whitespace in cells, same number of cells in each row, and unique values in the Code column for codelists.

test_examples.py

Validates JSON examples stored in the examples/ directory against the RDLS schema.

test_json.py

Ensures:

• JSON and other files are not empty.
• JSON files are indented properly. Note this test can often fail on problems that are not to do with indents.
• JSON files can be parsed.

test_schema.py

Checks that:

• The RDLS schema is valid against the JSON Schema 2020-12 specification.
• Fields whose type keyword includes array must set the items keyword.
• The codelist, openCodelist and enum keywords are used correctly.
• Properties listed in required are defined in properties or patternProperties, including those inherited via allOf.
• $ref'erences are resolvable.
• Objects in arrays have an id field.

pre-commit hooks

A pre-commit hook formats Markdown files in the docs directory using mdformat-myst. The configuration for the pre-commit hook is stored in .pre-commit-config.yaml.

Metadata Editor Examples

The docs/guides/metadata/examples directory contains step-by-step guidance examples for using the RDL Standard metadata editor. These examples help users understand what values to select when describing different types of risk datasets.

Purpose

Unlike the complete schema examples in the parent examples/ directory, these files provide:

1. Quick reference guidance for metadata entry
2. Step-by-step instructions on what to select in the editor
3. Practical examples of data structures
4. Key considerations for each dataset type

These examples are designed to be:

• Discoverable: Easy to find and reference in documentation
• Maintainable: Separate from normative schema content
• Reusable: Can be loaded by external tools and documentation sites

Structure

Examples are organized by risk data component:

Hazard (hazard/)

• earthquake_catalog.md - Historical earthquake catalog with empirical analysis
• tropical_cyclone.md - Probabilistic tropical cyclone wind hazard using GEV analysis
• flood_inundation.md - Flood hazard maps showing inundation extent

Exposure (exposure/)

• building_inventory.md - Building inventory database with footprints and attributes
• population_admin.md - Population dataset by administrative boundaries from surveys
• service_accessibility.md - Service accessibility analysis over road networks

Vulnerability (vulnerability/)

• earthquake_fragility.md - Earthquake fragility curves for building structures
• flood_damage_curves.md - Flood depth-damage functions from statistical analysis
• wealth_index.md - Relative wealth index as socio-economic vulnerability indicator

Loss (loss/)

• earthquake_loss.md - Earthquake loss database from historical event
• flood_risk.md - Flood risk model with expected annual damages

Using these examples

Each example file follows a consistent structure:

1. Overview: Brief description of the example dataset type
2. Step-by-step guidance: Detailed instructions organized by metadata section
3. Example data structure: Sample data formats and field descriptions
4. Key considerations: Important notes and best practices

Integration with documentation

These examples are intended to be:

1. Linked from schema descriptions: Referenced in the main documentation rather than embedded
2. Loaded by metadata editors: Can be parsed by tools to provide contextual help
3. Version controlled: Tracked separately from normative schema content
4. Multilingual ready: Structured for potential translation

Related resources

• Complete schema examples: /examples/hazard/, /examples/exposure/, etc.
• Schema reference documentation: /docs/reference/schema/
• RDLS guidance: /docs/guides/

Contributing

When adding new examples:

1. Follow the existing template structure
2. Use clear, concise language
3. Provide practical, realistic scenarios
4. Include data structure examples with sample values
5. Document key considerations and common pitfalls
6. Link to relevant codelists and taxonomies

Source

These examples were created based on the requirements in Issue #417, which identified the need for practical guidance that is:

• Available and discoverable in the documentation site
• Separated from normative schema content for better version control
• Easy to maintain without complex markdown escaping in JSON