Introduction

This page provides an introduction for new maintainers of the Risk Data Library Standard (RDLS).

The tech stack

The standard is built using a "Docs as Code" approach, ensuring that the schema, codelists and documentation remain synchronized.

• Schema: JSON Schema 2020-12 with the Open Data Services JSON Schema Extension
• Codelists: CSV files structured according to the Open Data Services Codelist Schema
• Documentation: Sphinx using MyST-Parser for Markdown support.
• Language: Python 3.12+ (for build scripts, testing, and CLI utilities).
• Hosting: Read the Docs for automated versioned deployments.
• Quality Assurance: pytest for logic/schema validation, mdformat for Markdown formatting, GitHub Actions for continuous integration.

How the documentation is built

The following diagram illustrates how the source files in the repository are transformed into the final published standard.

For more information on the processing that occurs during the build process, see schema processing and codelist processing.

    graph LR
        subgraph Source["Source Files (Git Repo)"]
            direction LR
            S1[JSON Schema]
            S2[Codelist CSVs]
            S3[Markdown Docs]
        end

        subgraph Build["Build Process (Sphinx + conf.py)"]
            direction LR
            B1[Process Schema]
            B2[Process Codelists]
            B3[Build HTML files]
        end

        subgraph Output["Documentation site (Read the Docs)"]
            direction LR
            O1[Processed JSON Schemas]
            O2[Processed Codelist CSVs]
            O3[HTML Website]
        end

        Source --> Build
        Build --> Output

Loading

Contribution workflow

The following diagram illustrates the workflow for making changes to the schema, codelists and documentation.

Tip

For a practical lesson in editing the standard, check out the contribution workflow tutorial.

    flowchart LR

        1[Set Up]
        2[Branch]
        3[Edit]
        4{Build}
        5{Test}
        6[Commit]
        7[Merge]

        1 --> 2
        2 --> 3
        3 --> 4
        4 -->|Fail| 3

        4 -->|Succeed| 5
        5 -->|Fail| 3
        5 -->|Pass| 6
        6 --> 7

Loading

The key steps in the workflow are:

1. Set up your development environment: Install the tools you need to edit, test and build the standard. The recommended approach is to use GitHub Codespaces, a pre-configured and hosted development environment.
2. Create a branch: Create a branches from the current staging branch, to develop features, fix bugs, or safely experiment with new ideas in a contained area of the repository.
3. Edit files: Edit the schema, codelists and/or Markdown files in the repository's directory structure.
4. Build the documentation:** Check that the build succeeds, correct any errors, and preview your changes locally.
5. Test the schema and codelists: Run tests to identify common issues and resolve any failures.
6. Commit your changes: Once the docs build succeeds, the tests pass, and you are happy with your changes, commit them to your branch.
7. Merge your changes: Create a pull request to merge your changes into the current staging branch for inclusion in a future release.