Using JSON Schema — FireWorks 2.0.2 documentation

# Using JSON Schema

Note

If you only use FireWorks with Python and provide your fireworks and workflows in Python only (not in YAML or JSON) you might want to skip this topic.

## Why should I use JSON schema?

The input for FireWorks is often provided in JSON and YAML and generated by third-party software that is unaware of the valid data types in FireWorks. Latent mismatches of data types may produce run-time errors, such as missing keywords or wrong data types, that are more difficult to handle than a validation of the initial input.

JSON schema provides a formal human- and machine-readable description of the data types used in classes in FireWorks. Additionally, a function is provided that checks the validity of JSON and YAML inputs immediately before deserialization.

To use the schema the fireworks_schema package must be installed.

There are three ways to activate JSON schema validation:

- Call the schema validator explicitly

- Activate automatic schema validation

- Modify the list of classes for automatic validation

## Call the schema validator explicitly

This is the case when you use Python but read JSON/YAML serialized objects provided externally. In the following example, a serialized workflow object is loaded from a YAML file and validated against the Workflow schema:

    import yaml
    import fireworks_schema
    from fireworks import Workflow

    with open('empty_fws.yaml', 'rt') as yf:
        dct = yaml.safe_load(yf)
    fireworks_schema.validate(dct, 'Workflow')
    wf = Workflow.from_dict(dct)

## Activate automatic schema validation

To activate automatic schema validation you must specify:

    JSON_SCHEMA_VALIDATE: true

in your FWConfig file. For more details about managing your FWConfig file see the FW Config tutorial.

The default value of `JSON_SCHEMA_VALIDATE` is `false`.

If automatic validation is turned on, i.e. `JSON_SCHEMA_VALIDATE` is `true`, then validation is performed only for built-in classes specified in the list `JSON_SCHEMA_VALIDATE_LIST`, whenever an object of these classes is loaded from file. You can find the default `JSON_SCHEMA_VALIDATE_LIST` in `fw_config.py` file in the FireWorks source.

## Modify the list of classes for automatic validation

You can modify the default `JSON_SCHEMA_VALIDATE_LIST` in your FWConfig file. For example, to turn on automatic validation for serialized `Firework` and `Workflow` objects only:

    JSON_SCHEMA_VALIDATE: true
    JSON_SCHEMA_VALIDATE_LIST: [Firework, Workflow]