There are two functions that perform this task. For streams there is DocumentIO.load(), for simple strings there is DocumentIO.loads().
If you use this API there is no need to double-check the contents of the document you’ve got. It’s going to match the description of the schema.
Example of reading something from a file:
with open("bundle.json", "rt") as stream:
format, bundle = DocumentIO.load(stream)
print "Loaded document type: %s" % format
The error path is a little more complex. Loading can fail at the following levels:
There is just one function for saving a document DocumentIO.dump(). It will always validate the document before saving it so there is little chance of producing invalid files this way.
Currently this function uses a hardcoded human-readable profile. If you care about representation efficiency use a compressed storage such as gzip.GzipFile.
Example of writing a bundle to a file:
with open("bundle.json", "wt") as stream:
bundle = {"format": "Dashboard Bundle Format 1.0"}
DocumentIO.dump(stream, bundle)
To validate document for correctness you can use DocumentIO.check().
Note
Most of the time you don’t need to validate a document explicitly. It is automatically validated when loading and saving.
To convert a document to the most recent format you can use DocumentEvolution.evolve_document(). It is safe to call this method on any valid document. If you just need to check if the document is using the most recent format call DocumentEvolution.is_latest().