=================
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:

.. code-block:: python

  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:

.. code-block:: yaml

  JSON_SCHEMA_VALIDATE: true

in your FWConfig file. For more details about managing your FWConfig file see the
:doc:`FW Config tutorial <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:

.. code-block:: yaml

  JSON_SCHEMA_VALIDATE: true
  JSON_SCHEMA_VALIDATE_LIST: [Firework, Workflow]
