# schema-markdown
[](https://pypi.org/project/schema-markdown/)
[](https://pypi.org/project/schema-markdown/)
[](https://github.com/craigahobbs/schema-markdown/blob/main/LICENSE)
[](https://pypi.org/project/schema-markdown/)
schema-markdown is a schema definition and validation library.
## Links
- [The Schema Markdown Language](https://craigahobbs.github.io/schema-markdown-js/language/)
- [API Documentation](https://craigahobbs.github.io/schema-markdown/)
- [Source code](https://github.com/craigahobbs/schema-markdown)
## Define a Schema
Schemas are defined using the
[Schema Markdown language](https://craigahobbs.github.io/schema-markdown-js/language/),
which is parsed by the
[parse_schema_markdown](https://craigahobbs.github.io/schema-markdown/reference.html#parse-schema-markdown)
function. For example:
~~~ python
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](https://craigahobbs.github.io/schema-markdown/reference.html#validate-type)
function. For example:
~~~ python
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:
~~~ python
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:
~~~ python
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]"
~~~
## Document a Schema
To document the schema, download the
[documentation application](https://github.com/craigahobbs/schema-markdown-doc#the-schema-markdown-documentation-viewer)
stub and save the type model as JSON:
~~~ sh
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:
~~~ sh
python3 -m http.server
~~~
## Development
This package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).
It was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:
~~~ sh
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
~~~
Raw data
{
"_id": null,
"home_page": "https://github.com/craigahobbs/schema-markdown",
"name": "schema-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "schema, validate, json",
"author": "Craig A. Hobbs",
"author_email": "craigahobbs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bb/9d/ffba9e4ac721bd7b07335fa28035a2f65f212d930ebc24dba4bc37c6413e/schema_markdown-1.2.10.tar.gz",
"platform": null,
"description": "# schema-markdown\n\n[](https://pypi.org/project/schema-markdown/)\n[](https://pypi.org/project/schema-markdown/)\n[](https://github.com/craigahobbs/schema-markdown/blob/main/LICENSE)\n[](https://pypi.org/project/schema-markdown/)\n\nschema-markdown is a schema definition and validation library.\n\n\n## Links\n\n- [The Schema Markdown Language](https://craigahobbs.github.io/schema-markdown-js/language/)\n- [API Documentation](https://craigahobbs.github.io/schema-markdown/)\n- [Source code](https://github.com/craigahobbs/schema-markdown)\n\n\n## Define a Schema\n\nSchemas are defined using the\n[Schema Markdown language](https://craigahobbs.github.io/schema-markdown-js/language/),\nwhich is parsed by the\n[parse_schema_markdown](https://craigahobbs.github.io/schema-markdown/reference.html#parse-schema-markdown)\nfunction. For example:\n\n~~~ python\nfrom schema_markdown import parse_schema_markdown\n\nmodel_types = parse_schema_markdown('''\\\n# An aggregate numerical operation\nstruct Aggregation\n\n # The aggregation function - default is \"Sum\"\n optional AggregationFunction aggregation\n\n # The numbers to aggregate on\n int[len > 0] numbers\n\n# An aggregation function\nenum AggregationFunction\n Average\n Sum\n''')\n~~~\n\n\n## Validate using a Schema\n\nTo validate an object using the schema, use the\n[validate_type](https://craigahobbs.github.io/schema-markdown/reference.html#validate-type)\nfunction. For example:\n\n~~~ python\nfrom schema_markdown import validate_type\n\nvalidate_type(model_types, 'Aggregation', {'numbers': [1, 2, '3', 4]})\n\n{'numbers': [1, 2, 3, 4]}\n~~~\n\nNotice that the numerical input '3' above is *type-massaged* to the integer 3 by validation.\n\nValidation fails if the object does not match the schema:\n\n~~~ python\nfrom schema_markdown import ValidationError\n\ntry:\n validate_type(model_types, 'Aggregation', {'numbers': [1, 2, 'asdf', 4]})\nexcept ValidationError as exc:\n str(exc)\n\n\"Invalid value 'asdf' (type 'str') for member 'numbers.2', expected type 'int'\"\n~~~\n\nValidation also fails if a member constraint is violated:\n\n~~~ python\ntry:\n validate_type(model_types, 'Aggregation', {'numbers': []})\nexcept ValidationError as exc:\n str(exc)\n\n\"Invalid value [] (type 'list') for member 'numbers', expected type 'array' [len > 0]\"\n~~~\n\n\n## Document a Schema\n\nTo document the schema, download the\n[documentation application](https://github.com/craigahobbs/schema-markdown-doc#the-schema-markdown-documentation-viewer)\nstub and save the type model as JSON:\n\n~~~ sh\ncurl -O https://craigahobbs.github.io/schema-markdown-doc/extra/index.html\npython3 \\\n -c 'from model import model_types; import json; print(json.dumps(model_types))' \\\n > model.json\n~~~\n\nTo host locally, start a local static web server:\n\n~~~ sh\npython3 -m http.server\n~~~\n\n\n## Development\n\nThis package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).\nIt was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:\n\n~~~ sh\ntemplate-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\n~~~\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A schema definition and validation library",
"version": "1.2.10",
"project_urls": {
"Homepage": "https://github.com/craigahobbs/schema-markdown"
},
"split_keywords": [
"schema",
" validate",
" json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "066997549aaa80484fb5cb188a1e99706e45dbd27aa32ca951c83c53bdb5ea7b",
"md5": "3764f12785c6eace43d65f2e4a0c9209",
"sha256": "c7cca8ceb5bc370e4c2c86b916b75522a884c3a4b693af01b6c6a36d0381e1db"
},
"downloads": -1,
"filename": "schema_markdown-1.2.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3764f12785c6eace43d65f2e4a0c9209",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17626,
"upload_time": "2024-11-08T19:01:16",
"upload_time_iso_8601": "2024-11-08T19:01:16.307294Z",
"url": "https://files.pythonhosted.org/packages/06/69/97549aaa80484fb5cb188a1e99706e45dbd27aa32ca951c83c53bdb5ea7b/schema_markdown-1.2.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb9dffba9e4ac721bd7b07335fa28035a2f65f212d930ebc24dba4bc37c6413e",
"md5": "e3b18ebe9b5c934d9bd945e4ab1485f9",
"sha256": "15c2816f8853926fe0b1b15552de358e090b9ef656dbda28950cd71c62ee9487"
},
"downloads": -1,
"filename": "schema_markdown-1.2.10.tar.gz",
"has_sig": false,
"md5_digest": "e3b18ebe9b5c934d9bd945e4ab1485f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16228,
"upload_time": "2024-11-08T19:01:17",
"upload_time_iso_8601": "2024-11-08T19:01:17.945269Z",
"url": "https://files.pythonhosted.org/packages/bb/9d/ffba9e4ac721bd7b07335fa28035a2f65f212d930ebc24dba4bc37c6413e/schema_markdown-1.2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-08 19:01:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "craigahobbs",
"github_project": "schema-markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "schema-markdown"
}
JSON
