+ +
+

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]
+
+
+
+
+ + +
+