schema-markdown

schema-markdown is a schema definition and validation library.

Define a Schema

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

import {parseSchemaMarkdown} from 'schema-markdown/lib/parser.js';

export const modelTypes = parseSchemaMarkdown(`\
# 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 validateType function. For example:

import {validateType} from 'schema-markdown/lib/schema.js';

const obj = validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, '3', 4]});
console.assert(obj.numbers[2] === 3);

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 {
    validateType(modelTypes, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]});
} catch ({message}) {
    console.assert(message === "Invalid value \"asdf\" (type 'string') for member 'numbers.2', expected type 'int'", message);
}

Validation also fails if a member constraint is violated:

try {
    validateType(modelTypes, 'Aggregation', {'numbers': []});
} catch ({message}) {
    console.assert(message === "Invalid value [] (type 'object') for member 'numbers', expected type 'array' [len > 0]", message);
}

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/model/#var.vURL='https://craigahobbs.github.io/bare-script/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 javascript-build. It was started using javascript-template as follows:

template-specialize javascript-template/template/ schema-markdown-js/ -k package schema-markdown -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapp 1