# JSON Schema for FireWorks
This package provides a [JSON schema](https://json-schema.org/) for
the [FireWorks](https://github.com/materialsproject/fireworks) package.
## Why should I use JSON schema?
The input for FireWorks is often provided in JSON or YAML formats 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.
The *fireworks_schema* package 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.
## Installing *fireworks_schema*
The recommended way to install this package into your virtual environment is
using ``pip`` (in any folder):
```
python -m pip install fireworks-schema
```
Alternatively you can download a release from the GitHub
[repository](https://github.com/ikondov/fireworks_schema), unpack the archive,
change into the top-level folder containing ``setup.cfg`` and run:
```
python -m pip install .[test]
```
After the installation you can run the tests (from the top-level folder):
```
cd fireworks_schema/tests && pytest
```
## Using *fireworks_schema* to validate input for FireWorks
There are two ways to perform JSON schema validation:
* Call the schema validator explicitly
* Activate automatic schema 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:
```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:
```yaml
JSON_SCHEMA_VALIDATE: true
```
in your FWConfig file. For more details about managing your FWConfig file see the
[FW Config tutorial](https://materialsproject.github.io/fireworks/config_tutorial.html).
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 the classes specified in the list
``JSON_SCHEMA_VALIDATE_LIST``, whenever an object of these
classes is loaded from file or from string.
There is no default for ``JSON_SCHEMA_VALIDATE_LIST``
and therefore you must set ``JSON_SCHEMA_VALIDATE_LIST`` in your FWConfig file.
For example, to turn on automatic validation for serialized ``Firework`` and
``Workflow`` objects these two lines must be added to the FWConfig file:
```yaml
JSON_SCHEMA_VALIDATE: true
JSON_SCHEMA_VALIDATE_LIST: [Firework, Workflow]
```
FireWorks performs automatic validation only when `from_file()` or `from_format()` methods
of the listed classes are called, i.e. only on reading from files and strings. This implies
that the utility function `load_object_from_file` also performs validation. Otherwise FireWorks
will not perform validation in scenarios such as dealing with documents from/to a database
or from/to a URI. To validate after having read a document from a database / URI and before
deserializing one should use `fw_schema_deserialize` to decorate the `from_dict()` method.
To validate after serialization and before writing to a database / URI one should decorate
the `to_dict()` method with `fw_schema_serialize`, e.g.:
```python
from fireworks_schema import fw_schema_deserialize, fw_schema_serialize
class MyClass(FWSerializable):
...
@classmethod
@fw_schema_deserialize
def from_dict(cls, dct):
...
return cls(...)
@fw_schema_serialize
def to_dict(self):
dct = ...
return dct
```
Note that the decorators honor the `JSON_SCHEMA_VALIDATE` setting, which is `False`
(default) or `True`, but not the `JSON_SCHEMA_VALIDATE_LIST`.
### Exception handling
When a custom schema is not valid then `SchemaError` is raised. When an instance
does not validate against a (valid) schema then `ValidationError` is raised. The
local schema and instance are displayed after the error description. Nevertheless,
the schema and the instance with which the validator has been called are not
displayed. These are known if the schema validator is called explicitly, i.e. by
calling `fireworks_schema.validate(instance, schema_name)`. But when automatic
validation is activated (either by the `JSON_SCHEMA_VALIDATE_LIST` or the decorator
approaches outlined above) then these are hard to detect. For this purpose, the
decorator accepts an optional `debug` parameter (`False` by default). By setting it
to `True` the schema name and the instance are concatenated to the original message
of the raised `ValidationError`.
Example:
```python
class MyClass(FWSerializable):
...
@classmethod
@fw_schema_deserialize(debug=True)
def from_dict(cls, dct):
...
```
### Register external schemas
Schemas for all relevant classes in FireWorks are provided with this package and
they work "out of the box". It is possible to use custom schemas for further classes,
that are sub-classes of `fireworks.utilities.fw_serializers.FWSerializable`, provided
by other packages but not FireWorks. For this, every schema has to be registered
like this:
```python
import fireworks_schema
fireworks_schema.register_schema('/absolute/path/to/the/schema.json')
```
After that, the schema can be used for both explicit and automatic validation as
described in the previous sections.
Currently, these restrictions/conventions apply:
* The filename, e.g. `schema.json` as in the example, must be different from
the file names of already registered schemas. This restriction comes about because
the `$id` schema property is currently not used.
* With `jsonschema < 4.18.0` all referenced schemas must be installed in the
same directory. This implies that the default schemas provided with `fireworks_schema`
cannot be used from custom schemas if `jsonschema < 4.18.0`.
* The schema filename is lower case of the schema name which in turn is the class name.
* Only JSON schema [draft-07](https://json-schema.org/draft-07) must be used.
Here an example for a custom schema with filename `fwintegerarray.json`:
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$ref": "#/FWIntegerArray",
"FWIntegerArray": {
"type": "object",
"additionalProperties": false,
"properties": {
"_fw_name": {
"const": "{{FWIntegerArray}}"
},
"data": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"required": [
"_fw_name"
]
}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "fireworks-schema",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "workflow system, json schema, fireworks",
"author": "Ivan Kondov",
"author_email": "ivan.kondov@kit.edu",
"download_url": "https://files.pythonhosted.org/packages/c1/95/c82e0a9aab8f32e702beb474936e3075dc3ea178c95a4527efb1f6f3e7f6/fireworks_schema-1.4.2.tar.gz",
"platform": null,
"description": "# JSON Schema for FireWorks\nThis package provides a [JSON schema](https://json-schema.org/) for\nthe [FireWorks](https://github.com/materialsproject/fireworks) package.\n\n## Why should I use JSON schema?\n\nThe input for FireWorks is often provided in JSON or YAML formats and generated by\nthird-party software that is unaware of the valid data types in FireWorks. Latent\nmismatches of data types may produce run-time errors, such as missing keywords\nor wrong data types, that are more difficult to handle than a validation of the\ninitial input.\n\nThe *fireworks_schema* package provides a formal human- and machine-readable description of\nthe data types used in classes in FireWorks. Additionally, a function is provided\nthat checks the validity of JSON and YAML inputs immediately before deserialization.\n\n\n## Installing *fireworks_schema*\n\nThe recommended way to install this package into your virtual environment is\nusing ``pip`` (in any folder):\n\n```\npython -m pip install fireworks-schema\n```\n\nAlternatively you can download a release from the GitHub\n[repository](https://github.com/ikondov/fireworks_schema), unpack the archive,\nchange into the top-level folder containing ``setup.cfg`` and run:\n\n```\npython -m pip install .[test]\n```\n\nAfter the installation you can run the tests (from the top-level folder):\n\n```\ncd fireworks_schema/tests && pytest\n```\n\n\n## Using *fireworks_schema* to validate input for FireWorks\n\nThere are two ways to perform JSON schema validation:\n\n* Call the schema validator explicitly\n* Activate automatic schema validation\n\n\n### Call the schema validator explicitly\n\nThis is the case when you use Python but read JSON/YAML serialized objects\nprovided externally. In the following example, a serialized workflow object is\nloaded from a YAML file and validated against the Workflow schema:\n\n```python\n import yaml\n import fireworks_schema\n from fireworks import Workflow\n\n with open('empty_fws.yaml', 'rt') as yf:\n dct = yaml.safe_load(yf)\n fireworks_schema.validate(dct, 'Workflow')\n wf = Workflow.from_dict(dct)\n```\n\n### Activate automatic schema validation\n\nTo activate automatic schema validation you must specify:\n\n```yaml\n JSON_SCHEMA_VALIDATE: true\n```\n\nin your FWConfig file. For more details about managing your FWConfig file see the\n[FW Config tutorial](https://materialsproject.github.io/fireworks/config_tutorial.html).\n\nThe default value of ``JSON_SCHEMA_VALIDATE`` is ``false``.\n\nIf automatic validation is turned on, i.e. ``JSON_SCHEMA_VALIDATE`` is ``true``,\nthen validation is performed only for the classes specified in the list\n``JSON_SCHEMA_VALIDATE_LIST``, whenever an object of these\nclasses is loaded from file or from string.\nThere is no default for ``JSON_SCHEMA_VALIDATE_LIST``\nand therefore you must set ``JSON_SCHEMA_VALIDATE_LIST`` in your FWConfig file.\nFor example, to turn on automatic validation for serialized ``Firework`` and\n``Workflow`` objects these two lines must be added to the FWConfig file:\n\n```yaml\n JSON_SCHEMA_VALIDATE: true\n JSON_SCHEMA_VALIDATE_LIST: [Firework, Workflow]\n```\n\nFireWorks performs automatic validation only when `from_file()` or `from_format()` methods\nof the listed classes are called, i.e. only on reading from files and strings. This implies\nthat the utility function `load_object_from_file` also performs validation. Otherwise FireWorks\nwill not perform validation in scenarios such as dealing with documents from/to a database\nor from/to a URI. To validate after having read a document from a database / URI and before\ndeserializing one should use `fw_schema_deserialize` to decorate the `from_dict()` method.\nTo validate after serialization and before writing to a database / URI one should decorate\nthe `to_dict()` method with `fw_schema_serialize`, e.g.:\n\n```python\nfrom fireworks_schema import fw_schema_deserialize, fw_schema_serialize\n\nclass MyClass(FWSerializable):\n ...\n\n @classmethod\n @fw_schema_deserialize\n def from_dict(cls, dct):\n ...\n return cls(...)\n\n @fw_schema_serialize\n def to_dict(self):\n dct = ...\n return dct\n```\n\nNote that the decorators honor the `JSON_SCHEMA_VALIDATE` setting, which is `False`\n(default) or `True`, but not the `JSON_SCHEMA_VALIDATE_LIST`.\n\n\n### Exception handling\n\nWhen a custom schema is not valid then `SchemaError` is raised. When an instance\ndoes not validate against a (valid) schema then `ValidationError` is raised. The\nlocal schema and instance are displayed after the error description. Nevertheless,\nthe schema and the instance with which the validator has been called are not\ndisplayed. These are known if the schema validator is called explicitly, i.e. by\ncalling `fireworks_schema.validate(instance, schema_name)`. But when automatic\nvalidation is activated (either by the `JSON_SCHEMA_VALIDATE_LIST` or the decorator\napproaches outlined above) then these are hard to detect. For this purpose, the\ndecorator accepts an optional `debug` parameter (`False` by default). By setting it\nto `True` the schema name and the instance are concatenated to the original message\nof the raised `ValidationError`.\n\nExample:\n\n```python\nclass MyClass(FWSerializable):\n ...\n\n @classmethod\n @fw_schema_deserialize(debug=True)\n def from_dict(cls, dct):\n ...\n```\n\n\n### Register external schemas\n\nSchemas for all relevant classes in FireWorks are provided with this package and\nthey work \"out of the box\". It is possible to use custom schemas for further classes,\nthat are sub-classes of `fireworks.utilities.fw_serializers.FWSerializable`, provided\nby other packages but not FireWorks. For this, every schema has to be registered\nlike this:\n\n```python\n import fireworks_schema\n fireworks_schema.register_schema('/absolute/path/to/the/schema.json')\n```\n\nAfter that, the schema can be used for both explicit and automatic validation as\ndescribed in the previous sections.\n\nCurrently, these restrictions/conventions apply:\n* The filename, e.g. `schema.json` as in the example, must be different from\nthe file names of already registered schemas. This restriction comes about because\nthe `$id` schema property is currently not used.\n* With `jsonschema < 4.18.0` all referenced schemas must be installed in the\nsame directory. This implies that the default schemas provided with `fireworks_schema`\ncannot be used from custom schemas if `jsonschema < 4.18.0`.\n* The schema filename is lower case of the schema name which in turn is the class name.\n* Only JSON schema [draft-07](https://json-schema.org/draft-07) must be used.\n\nHere an example for a custom schema with filename `fwintegerarray.json`:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"$ref\": \"#/FWIntegerArray\",\n \"FWIntegerArray\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"_fw_name\": {\n \"const\": \"{{FWIntegerArray}}\"\n },\n \"data\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\"\n }\n }\n },\n \"required\": [\n \"_fw_name\"\n ]\n }\n}\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "JSON Schema for FireWorks",
"version": "1.4.2",
"project_urls": {
"Bug Reports": "https://github.com/ikondov/fireworks_schema/issues",
"Download": "https://pypi.org/project/fireworks-schema/#files",
"Homepage": "https://github.com/ikondov/fireworks_schema",
"Source Code": "https://github.com/ikondov/fireworks_schema"
},
"split_keywords": [
"workflow system",
" json schema",
" fireworks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a3483d1a411d9e8ad2f5328758792672edd7ad88887c7ef926b3c6942e064b5",
"md5": "c25da5a5e10b75f9eb76752973510f8a",
"sha256": "946f592286202608b08d6700ea0c758389ac22495c6b696fae4b3f1e3a0cedaa"
},
"downloads": -1,
"filename": "fireworks_schema-1.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c25da5a5e10b75f9eb76752973510f8a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 25945,
"upload_time": "2025-07-11T15:39:01",
"upload_time_iso_8601": "2025-07-11T15:39:01.571772Z",
"url": "https://files.pythonhosted.org/packages/2a/34/83d1a411d9e8ad2f5328758792672edd7ad88887c7ef926b3c6942e064b5/fireworks_schema-1.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c195c82e0a9aab8f32e702beb474936e3075dc3ea178c95a4527efb1f6f3e7f6",
"md5": "3ce980beb2e4655cc0ecc3aa5808f6a6",
"sha256": "b714eaef5684e731aee452b602b70130527be5e3a33772dc4ef3c225ca2c6ec5"
},
"downloads": -1,
"filename": "fireworks_schema-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "3ce980beb2e4655cc0ecc3aa5808f6a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 17187,
"upload_time": "2025-07-11T15:39:02",
"upload_time_iso_8601": "2025-07-11T15:39:02.601937Z",
"url": "https://files.pythonhosted.org/packages/c1/95/c82e0a9aab8f32e702beb474936e3075dc3ea178c95a4527efb1f6f3e7f6/fireworks_schema-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 15:39:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ikondov",
"github_project": "fireworks_schema",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "jsonschema",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "fireworks",
"specs": [
[
">=",
"2.0.2"
]
]
},
{
"name": "pymongo",
"specs": [
[
">=",
"3.9.0"
]
]
},
{
"name": "semantic-version",
"specs": []
}
],
"lcname": "fireworks-schema"
}
JSON
