Developers guide

Contributions and reporting issues

We welcome reporting of issues on our GitHub page. Please provide a minimum working example so we are able to reproduce the issue. Furthermore, we welcome contributions. We follow the ColPrac guide for collaborative practices. New contributors should make sure to read that guide.

To get started with local development, install Julia and pre-commit by running the command below.

pixi run install

Parameter and variable metadata JSON export

Wflow maintains an internal standard name system (STANDARD_NAME_MAPS) that serves as the single source of truth for all parameter and variable metadata — including units, defaults, descriptions, and input handling flags. A utility script exports this metadata to machine-readable JSON files, making it accessible for external tools, documentation generation, and validation.

Output files

The export produces four JSON files in utils/export_parameter_data/:

File Contents
sbm_metadata.json Land hydrology (SBM) parameters and variables
routing_metadata.json Routing parameters and variables
sediment_metadata.json Soil erosion and sediment transport parameters and variables
domain_metadata.json Domain grid parameters (LDD, river mask, subbasins)

JSON structure

Each file is a flat JSON object keyed by CSDMS-style standard names. The output is validated against a JSON Schema (metadata_schema.json in the same directory). Internal-only fields (lens, dimname, tags) from ParameterMetadata are intentionally excluded from the JSON output. The full field descriptions are documented on the struct:

Code 
using Wflow
@doc Wflow.ParameterMetadata

Metadata associated with parameters and variables.

Arguments

  • lens: The path in the model data structure to the parameter/variable if it exists

  • unit: The unit of the parameter/variable in the Wflow input

  • default: The default (initial) value of the parameter/variable if it exists

  • fill: Missing input values are replaced by this value if allow_missing == false

  • type: The output type of the data. Assumed to be Float64 if it is not provided and cannot be derived from default or fill

  • description: The description of the parameter/variable provided in the Wflow docs

  • allow_missing: Whether the parameter/variable is allowed to have missing entries

  • allow_dynamic_input: Allow updating this parameter from input via cyclic/forcing

  • dimname: The name of the third dimension of the parameter/variable if it exists

  • tags: Identifiers to filter parameters/variables for specific tables in the docs

Running the export

Use the pixi task:

pixi run parameter_metadata_json_gen

CI guardrail

A GitHub Actions workflow (parameter_metadata_json_gen.yml) runs automatically on pushes to master and on PRs that modify files under Wflow/src/standard_name/. It re-generates the JSON files and runs git diff --exit-code to ensure the committed JSON stays in sync with the source standard name maps. If you update any standard name metadata, re-run the export and commit the updated JSON files.

Style/decisions

  • For improved code readability, we decided to avoid non-ASCII characters for naming variables, structs, functions and macros. Using the non-ASCII character for built-in operators is still allowed. This change in naming convention is now in effect and all invalid uses of non-ASCII characters have been replaced by ASCII equivalents.
Back to top