API documentation for the schema module

The schema module provides tools for handling the JSON schemas used to validate model configuration documents. The load_schema() and merge_schemas() functions are used to load schema documents and then build a single JSONSchema across the models used in a simulation.

The resulting merged schema is then used with the ValidatorWithDefaults JSON schema validator. This has been extended using the set_defaults() iterator to provide a global JSONSchema validator instance that fills in missing entries in configuration documents from default values provided in the schemas.

When a new model module is created, the JSONSchema file should be saved in the module directory as module_schema.json. This document should define the expected configuration tags, their expected types, and any constraints on their values (e.g. the number of soil layers being strictly positive). Additionally, where sensible default values exist (e.g. 1 week for the model time step) they should also be included in the schema.

The JSONSchema documents for a module should be loaded when a model is imported into the MODULE_REGISTRY. See the registry module for details.

Functions:

load_schema(module_name, schema_file_path)

Function to load the JSON schema for a module.

merge_schemas(schemas)

Merge the validation schemas for desired modules.

set_defaults(validator, properties, ...)

Generate an iterator to populate schema defaults.
virtual_ecosystem.core.schema.ValidatorWithDefaults

A JSONSchema validator that sets defaults where required.

virtual_ecosystem.core.schema.load_schema(module_name: str, schema_file_path: Path) → dict

Function to load the JSON schema for a module.

This function tries to load a JSON schema file and then - if the JSON loaded correctly - checks that the JSON provides a valid JSON Schema.

Parameters:

  • module_name – The name to register the schema under

  • schema_file_path – The file path to the JSON Schema file

Raises:
virtual_ecosystem.core.schema.merge_schemas(schemas: dict[str, dict[str, Any]]) → dict[str, Any]

Merge the validation schemas for desired modules.

The method merges a set of schemas for a set of desired modules into a single integrated schema that can then be used to validate a merged configuration for those modules. The merge also updates the resulting schema to enforce that only properties explicity listed in the schema can be included.

Parameters:

schemas – A dictionary of schemas keyed by module name

Returns:

An integrated schema combining the modules.

virtual_ecosystem.core.schema.set_defaults(validator: type[Draft202012Validator], properties: dict[str, Any], instance: dict[str, Any], schema: dict[str, Any]) → Iterator

Generate an iterator to populate schema defaults.

This function is used to extend the Draft202012Validator to include automatic insertion of default values from a schema where values are not specified. The function signature follows the required JSON schema pattern:

https://python-jsonschema.readthedocs.io/en/latest/creating/

Parameters:

  • validator – a validator instance,

  • properties – the value of the property being validated within the instance

  • instance – the instance

  • schema – the schema

Returns:

An iterator to be applied to JSON schema entries.