Package: yschema
YSchema is a terse and simple schema format with a reference validator
implementation for YAML, JSON and other dictionary based data structures.YSchema is quite minimal (in terms of lines of code) and is continuously tested
against a set of of valid and invalid example data (see theexamplesdirectory). The code works nicely for its intended purpose, but may not be the
most powerful or popular, even if it does what it was intended for very well.
The main assumption (at least for now) is that all keys are strings without
whitespace.YSchema is written in Python (v. 3) and validates dictionaries containing basic
datatypes like strings, ints, floats, lists and nested dictionaries. The schema
is also a dictionary, so both the data and the schema can be written in Python,
JSON, YAML, TOML, … formats. YSchema cannot validate all possible YAML / JSON
data, in fact it cannot even validate its own schema files since those use
significant white space in dictionary keys to describe expected data types and
whether the data is required or not.To install the YSchema Python library along with theyschemacommand line
program run:python3-mpipinstall-UyschemaConsider using a virtual environment or adding--userto thepipcommand
if you do not want to install into the system’s site-packages directory. PS: You
may also want to look at older and more established schema and validators such
asYamaleorjson-schemain case those serve your needs better.ContentsIntroduction to YSchemaMore advanced featuresReleasesVersion 1.0.1 - June 7. 2018Copyright and licenseIntroduction to YSchemaA simple example schema:# There must be a key "name" that maps to a stringrequired name:str# There can be an integer age, but it is not requiredoptional age:int# The optional height must be above 0optional height:float(min_val=0)To validate this, first load the schema above into a dictionary, then load the
data to validate into another dictionary, and finally run:importyschema# possibly loaded from json or yaml or just a plain old dictschema=my_load_schema_function()data_dict={'name':'Tormod'}yschema.validate(data_dict,schema_dict)If the function does not raiseyschema.ValidationErrorthen the data is
valid according to the given schema. You can also use theyschemacommand
to validate YAML files from the command line.A more complicated example, showing constants and nested dictionaries:# Example of a constant that can be used in validation functionsconstant minimum_string_length:5# A sub-dictionarytype Whale:# The name is a string of a given minimum lengthrequired name:str(min_len=minimum_string_length)# The length must be between 0 and 500 metersoptional length:float(min_val=0, max_val=500.0)required whales:list(type=Whale)The above schema validates data like this:whales:-name:Unknown Whale-name:Enormous Whalelength:200.0Note that when working with aliases and types the order of the keys in the
dictionary starts to matter. Either use a Python 3.6 or later, or load your
schema into an OrderedDict. YSchema contains a helper function for ordered safe
loading of YAML files:withopen(schema_file_name,'rt')asyml:schema=yschema.yaml_ordered_load(yml)More advanced featuresBuilt in types: the following types are implemented. Optional parameters
are listed below each type:Anyboolstrmin_lenmax_lenequals - e.g.str(equals='Hi!')or matching one of several
pissibilities withstr(equals=('a','b','c'))prefixintmin_valmax_valequals - e.g.int(equals=3)orint(equals=(2,4, 6))floatmin_valmax_valequals - e.g.float(equals=3.2)orfloat(equals=(2.1,4.4))listmin_lenmax_lentype - e.g.list(type=int)orlist(type=Whale)one_oftypes - e.g.one_of(types=(int,str))orone_of(types=(str(prefix='Moby'),Whale))any_oftypes - seeone_of(any_ofmatches if any of the types match,one_ofrequires exactly one match)Alias: you can give an alias to avoid typing the same type definition over
and over again:alias Cat:one_of(types=(HouseCat, Tiger, Lynx))alias Cats:list(type=Cat)Glob: you can allow undefined keys by using a glob. The following will
validate OK for all documentsoptional *:AnyInherit: a sub-schema introduced bytypecan contain a keyinheritwith the name of a previously defined sub-schema to avoid repeating
definitions that are shared among several types:type MeshBase:optional move:list(type=str)optional sort_order:list(type=int)optional mesh_file:strtype MeshDolfinFile:inherit:MeshBaserequired type:str(equals=('XML', 'XDMF', 'HDF5'))required mesh_file:stroptional facet_region_file:strtype MeshMeshio:inherit:MeshBaserequired type:str(equals='meshio')required mesh_file:stroptional meshio_type:strrequired mesh:one_of(types=(MeshMeshio, MeshDolfinFile))ReleasesVersion 1.0.2 - June 11. 2018Improve error messages and add convinience function to safe-load YAML into an
OrderedDictVersion 1.0.1 - June 7. 2018Completed v 1.0 implementation goals. The YSchema language is powerful enough to
express most of what I wanted for validatingOcellarisinput files. The code
base is decently tested (using the fantastic CircleCI service) and a command
line tool is also included for validating YAML files from the shell.There may not be a large number of additional releases if no more features are
found to be necessary for the author’s uses. It is relatively easy to add new
type validators from user code, but feel free to submit a pull request if you
are finding YSchema useful and have implemented some general purpose validators.
YSchema does not intend to compete with complex and more fully featured schema
languages likejson-schema.Copyright and licenseYSchema is copyright Tormod Landet, 2018. YSchema is licensed under the Apache
2.0 license, a permissive free software license compatible with version 3 of
the GNU GPL. See the file LICENSE for the details.