Documentation

share/openPMD/json_schema/check.py

@@ -1,20 +1,70 @@
 #!/usr/bin/env python
 
+import argparse
 import json
 import os
 from pathlib import Path
+import sys
 
 import jsonschema.validators
 
-path = Path(os.path.dirname(os.path.realpath(__file__)))
+
+def parse_args(program_name):
+    script_path = Path(os.path.dirname(os.path.realpath(sys.argv[0])))
+    parser = argparse.ArgumentParser(
+        # we need this for line breaks
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="""
+Check JSON files against the openPMD JSON schema.
+
+This tool validates an openPMD-formatted JSON file against the openPMD JSON
+schema, using the jsonschema Python library as a backend.
+Please use this script instead of the jsonschema directly since the openPMD
+schema consists of several JSON files and this script ensures that
+cross-referencing is set up correctly.
+
+Note that the JSON schema is shipped in form of .toml files for ease of reading,
+maintenance and documentation.
+In order to perform a check, the .toml files need to be converted to .json
+first.
+The openPMD-api install a tool openpmd-convert-json-toml for this purpose.
+Additionally, there is a shell script ./generate_schema.sh shipped in the same
+folder as this Python script which can be directly applied to generate the
+JSON schema.
+
+
+Examples:
+    {0} --help
+    {0} --schema_root={1} <path/to/simData_000100.json>
+""".format(os.path.basename(program_name), script_path / "series.json"))
+
+    parser.add_argument(
+        '--schema_root',
+        default='./series.json',
+        help=
+        'The .json file describing the root file of the schema to validate against.'
+    )
+    parser.add_argument('openpmd_file',
+                        metavar='file',
+                        nargs=1,
+                        help="The file which to validate.")
+
+    return parser.parse_args()
+
+
+args = parse_args(sys.argv[0])
+
+path = Path(os.path.dirname(os.path.realpath(args.schema_root)))
 resolver = jsonschema.validators.RefResolver(
     base_uri=f"{path.as_uri()}/",
     referrer=True,
 )
 
-with open(path / "sample_datasets/pic_long.json", "r") as instance:
+with open(args.openpmd_file[0], "r") as instance:
     jsonschema.validate(
         instance=json.load(instance),
         schema={"$ref": "./series.json"},
         resolver=resolver,
     )
+    print("File {} was validated successfully against schema {}.".format(
+        instance.name, args.schema_root))

share/openPMD/json_schema/generate_schema.sh

@@ -1,5 +1,25 @@
-#!/usr/bin/env bash
-for toml_file in ./*.toml; do
+#!/usr/bin/env sh
+if (( $# < 1 )); then
+    cat << EOF
+Usage: $0 <path_to_toml_file.toml>+
+Will convert all .toml files passed as a command line argument to .json.
+Binary 'openpmd-convert-json-toml' must be in the PATH.
+The target filename will be determined from the input .toml filename, replacing
+.toml with .json.
+If 'jq' is found in the PATH, it will be used for formatting.
+EOF
+    exit
+fi
+
+for toml_file in "$@"; do
+    if [ "${toml_file%.toml}" = "$toml_file" ]; then
+        echo "Skipping $toml_file as it has no suffix .toml." >&2
+        continue
+    fi
     dest_name="${toml_file%.toml}.json"
-    openpmd-convert-json-toml "@$toml_file" | jq . > "$dest_name"
+    if command -v jq &> /dev/null; then
+        openpmd-convert-json-toml "@$toml_file" | jq . > "$dest_name"
+    else
+        openpmd-convert-json-toml "@$toml_file" > "$dest_name"
+    fi
 done