schema-markdown 1.2.0

A schema definition and validation library

schema-markdown is a schema definition and validation library.

Links

• The Schema Markdown Language

• API Documentation

• Source code

Define a Schema

Schemas are defined using the Schema Markdown language which is parsed by the parse_schema_markdown function. For example:

>>> import schema_markdown
...
>>> model_types = schema_markdown.parse_schema_markdown('''\
... # An aggregate numerical operation
... struct Aggregation
...
...     # The aggregation function - default is "Sum"
...     optional AggregationFunction aggregation
...
...     # The numbers to aggregate on
...     int[len > 0] numbers
...
... # An aggregation function
... enum AggregationFunction
...     Average
...     Sum
... ''')

Validate using a Schema

To validate an object using the schema, use the validate_type function. For example:

>>> schema_markdown.validate_type(model_types, 'Aggregation',
...     {'numbers': [1, 2, '3', 4]})
{'numbers': [1, 2, 3, 4]}

Notice that the numerical input ‘3’ above is type-massaged to the integer 3 by validation.

Validation fails if the object does not match the schema:

>>> try:
...     schema_markdown.validate_type(model_types, 'Aggregation',
...         {'numbers': [1, 2, 'asdf', 4]})
... except schema_markdown.ValidationError as exc:
...     str(exc)
"Invalid value 'asdf' (type 'str') for member 'numbers.2', expected type 'int'"

Validation also fails if a member constraint is violated:

>>> try:
...     schema_markdown.validate_type(model_types, 'Aggregation',
...         {'numbers': []})
... except schema_markdown.ValidationError as exc:
...     str(exc)
"Invalid value [] (type 'list') for member 'numbers', expected type 'array' [len > 0]"

Document a Schema

To document the schema, download the documentation application stub and save the type model as JSON:

curl -O https://craigahobbs.github.io/schema-markdown-doc/extra/index.html
python3 \
    -c 'from model import model_types; import json; print(json.dumps(model_types))' \
    > model.json

To host locally, start a local static web server:

python3 -m http.server

Development

This package is developed using python-build. It was started using python-template as follows:

template-specialize python-template/template/ schema-markdown/ -k package schema-markdown -k name 'Craig A. Hobbs' -k email '[e-mail]' -k github 'craigahobbs'