schema-markdown

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:

from schema_markdown import parse_schema_markdown

model_types = 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:

from schema_markdown import validate_type

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:

from schema_markdown import ValidationError

try:
    validate_type(model_types, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]})
except 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:
    validate_type(model_types, 'Aggregation', {'numbers': []})
except ValidationError as exc:
    str(exc)

"Invalid value [] (type 'list') for member 'numbers', expected type 'array' [len > 0]"

Schema Documentation

You can document a schema with BareScript’s schemaDoc application running on the MarkdownUp application.

If your type model JSON file or Schema Markdown file is publicly visible, you can use the BareScript model application with the var.vURL query argument:

https://craigahobbs.github.io/bare-script-py/model/#var.vURL=’https://craigahobbs.github.io/bare-script-py/library/model.json’

Note: Schema Markdown files use the .smd file extension.

Self-Hosting Schema Documentation

You can host the schemaDoc application yourself by downloading the MarkdownUp Application HTML stub.

curl -O https://craigahobbs.github.io/markdown-up/extra/index.html

Replace the MarkdownUp application creation line:

        const app = new MarkdownUp(window);

With the following:

        const app = new MarkdownUp(window, {
            'markdownText': `\
~~~markdown-script
include <schemaDoc.bare>

schemaDocMain('model.json', 'My Model')
~~~
`
        });

To view 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 'craigahobbs@gmail.com' -k github 'craigahobbs' -k nomain 1