Skip to main content

schema-markdown

PyPI - Status PyPI GitHub PyPI - Python Version

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 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]'

validate_type validates JSON-like values. In this Python implementation, date values are datetime.date, datetime values are datetime.datetime, and uuid strings remain strings. datetime.date, datetime.datetime, and uuid.UUID inputs are left unchanged. See The Schema Markdown Language - Built-in Types for accepted JSON input formats and host-runtime behavior.

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 adding a schemaDoc HTML stub:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>MarkdownUp</title>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" href="https://craigahobbs.github.io/markdown-up/app.css">
        <link rel="preload" href="https://craigahobbs.github.io/markdown-up/bare-script/static/markdown.css" as="style">
        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/appImports.js" as="script">
    </head>
    <script type="module">
        import {MarkdownUp} from 'https://craigahobbs.github.io/markdown-up/lib/appImports.js';
        const app = new MarkdownUp(window, {
            'markdownText': `\
~~~markdown-script
include <schemaDoc.bare>

schemaDocMain('model.json', 'My Model')
~~~
`
        });
        app.run();
    </script>
</html>

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

Metadata

Release files for schema-markdown 1.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for schema-markdown 1.3.4
File Size Uploaded Provenance Actions
schema_markdown-1.3.4.tar.gz 19.1 kB Without provenance Details for schema_markdown-1.3.4.tar.gz

Release files / schema_markdown-1.3.4.tar.gz

Download URL schema_markdown-1.3.4.tar.gz
Size 19.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2286c9d84d40b153a0798e9c221dcd65dcb105bdb1db7cc95d704547ff29adef
BLAKE2b-256 checksum
How to use checksums
7414af9e91258910710eff72cda647aaec1bae510d106e8730b5f73377dae847
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for schema-markdown 1.3.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.4 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page