# jsonschema2md
[](https://pypi.org/project/jsonschema2md)
[](https://github.com/sbrunner/jsonschema2md/releases)
[](https://github.com/sbrunner/jsonschema2md/actions)
_Convert JSON Schemas to simple, human-readable Markdown documentation._
---
For example:
```json
{
"$id": "https://example.com/person.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"description": "JSON Schema for a person object.",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The person's first name."
},
"lastName": {
"type": "string",
"description": "The person's last name."
}
}
}
```
will be converted to:
> # Person
>
> _JSON Schema for a person object._
>
> ## Properties
>
> - **`firstName`** _(string)_: The person's first name.
> - **`lastName`** _(string)_: The person's last name.
There's also the possibility to translate it to another language. For example, the same schema in French would result in:
> # Person
>
> _JSON Schema for a person object._
>
> ## Propriétés
>
> - **`firstName`** _(chaîne de caractères)_: The person's first name.
> - **`lastName`** _(chaîne de caractères)_: The person's last name.
See the [examples](https://github.com/sbrunner/jsonschema2md/tree/master/examples)
directory for more elaborate examples.
---
## Installation
Install with pip
```sh
pip install jsonschema2md
```
## Usage
### From the CLI
```sh
jsonschema2md [OPTIONS] <input.json> <output.md>
```
### From Python
```python
import json
import jsonschema2md
parser = jsonschema2md.Parser(
examples_as_yaml=False,
show_examples="all",
)
with open("./examples/food.json", "r") as json_file:
md_lines = parser.parse_schema(json.load(json_file))
print(''.join(md_lines))
```
### Options
- `examples_as_yaml`: Parse examples in YAML-format instead of JSON. (`bool`, default:
`False`)
- `show_examples`: Parse examples for only the main object, only properties, or all.
(`str`, default `all`, options: `object`, `properties`, `all`)
- `show_deprecated`: Show deprecated properties. (`bool`, default: `True`)
- `collapse_children`: Collapse object children into a `<details>` element (`bool`, default:
`False`)
- `header_level`: Base header level for the generated markdown. (`int`, default: `0`)
- `ignore_patterns`: List of regex patterns to ignore when parsing the schema. (`list of
str`, default: `None`)
## pre-commit hook
You can use the pre-commit hook with:
```yaml
repos:
- repo: https://github.com/sbrunner/jsonschema2md
rev: <version> # Use the ref you want to point at
hooks:
- id: jsonschema2md
files: schema.json
args:
- --pre-commit
- schema.json
- schema.md
```
## Contributing
Bugs, questions or suggestions? Feel free to post an issue in the
[issue tracker](https://github.com/sbrunner/jsonschema2md/issues/) or to make a pull
request! See
[Contributing.md](https://github.com/sbrunner/jsonschema2md/blob/master/CONTRIBUTING.md)
for more info.
Install the pre-commit hooks:
```bash
pip install pre-commit
pre-commit install --allow-missing-config
```
## Showcase
- [PrairieLearn's `infoCourse.json`](https://prairielearn.readthedocs.io/en/latest/schemas/infoCourse/), [source code](https://github.com/PrairieLearn/PrairieLearn/blob/ab1e0f1fc837a8da9cde3448eb785958ac42e309/docs/scripts/gen_jsonschemas.py).
## Related projects:
- [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans)
- [jsonschema-markdown](https://github.com/elisiariocouto/jsonschema-markdown)
- [adobe/jsonschema2md](https://github.com/adobe/jsonschema2md)
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonschema2md",
"maintainer": "St\u00e9phane Brunner",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "stephane.brunner@gmail.com",
"keywords": "JSON Schema, Markdown, Converter, Parser, Documentation",
"author": "Ralf Gabriels",
"author_email": "ralfg@hotmail.be",
"download_url": "https://files.pythonhosted.org/packages/2a/94/4dc247dfe01f46124a98398e025506c8cf6c931f431ec24c4a9f5d1f35bc/jsonschema2md-1.6.0.tar.gz",
"platform": null,
"description": "# jsonschema2md\n\n[](https://pypi.org/project/jsonschema2md)\n[](https://github.com/sbrunner/jsonschema2md/releases)\n[](https://github.com/sbrunner/jsonschema2md/actions)\n\n\n\n_Convert JSON Schemas to simple, human-readable Markdown documentation._\n\n---\n\nFor example:\n\n```json\n{\n \"$id\": \"https://example.com/person.schema.json\",\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"title\": \"Person\",\n \"description\": \"JSON Schema for a person object.\",\n \"type\": \"object\",\n \"properties\": {\n \"firstName\": {\n \"type\": \"string\",\n \"description\": \"The person's first name.\"\n },\n \"lastName\": {\n \"type\": \"string\",\n \"description\": \"The person's last name.\"\n }\n }\n}\n```\n\nwill be converted to:\n\n> # Person\n>\n> _JSON Schema for a person object._\n>\n> ## Properties\n>\n> - **`firstName`** _(string)_: The person's first name.\n> - **`lastName`** _(string)_: The person's last name.\n\nThere's also the possibility to translate it to another language. For example, the same schema in French would result in:\n\n> # Person\n>\n> _JSON Schema for a person object._\n>\n> ## Propri\u00e9t\u00e9s\n>\n> - **`firstName`** _(cha\u00eene de caract\u00e8res)_: The person's first name.\n> - **`lastName`** _(cha\u00eene de caract\u00e8res)_: The person's last name.\n\nSee the [examples](https://github.com/sbrunner/jsonschema2md/tree/master/examples)\ndirectory for more elaborate examples.\n\n---\n\n## Installation\n\nInstall with pip\n\n```sh\npip install jsonschema2md\n```\n\n## Usage\n\n### From the CLI\n\n```sh\njsonschema2md [OPTIONS] <input.json> <output.md>\n```\n\n### From Python\n\n```python\nimport json\nimport jsonschema2md\n\nparser = jsonschema2md.Parser(\n examples_as_yaml=False,\n show_examples=\"all\",\n)\nwith open(\"./examples/food.json\", \"r\") as json_file:\n md_lines = parser.parse_schema(json.load(json_file))\nprint(''.join(md_lines))\n```\n\n### Options\n\n- `examples_as_yaml`: Parse examples in YAML-format instead of JSON. (`bool`, default:\n `False`)\n- `show_examples`: Parse examples for only the main object, only properties, or all.\n (`str`, default `all`, options: `object`, `properties`, `all`)\n- `show_deprecated`: Show deprecated properties. (`bool`, default: `True`)\n- `collapse_children`: Collapse object children into a `<details>` element (`bool`, default:\n `False`)\n- `header_level`: Base header level for the generated markdown. (`int`, default: `0`)\n- `ignore_patterns`: List of regex patterns to ignore when parsing the schema. (`list of\nstr`, default: `None`)\n\n## pre-commit hook\n\nYou can use the pre-commit hook with:\n\n```yaml\nrepos:\n - repo: https://github.com/sbrunner/jsonschema2md\n rev: <version> # Use the ref you want to point at\n hooks:\n - id: jsonschema2md\n files: schema.json\n args:\n - --pre-commit\n - schema.json\n - schema.md\n```\n\n## Contributing\n\nBugs, questions or suggestions? Feel free to post an issue in the\n[issue tracker](https://github.com/sbrunner/jsonschema2md/issues/) or to make a pull\nrequest! See\n[Contributing.md](https://github.com/sbrunner/jsonschema2md/blob/master/CONTRIBUTING.md)\nfor more info.\n\nInstall the pre-commit hooks:\n\n```bash\npip install pre-commit\npre-commit install --allow-missing-config\n```\n\n## Showcase\n\n- [PrairieLearn's `infoCourse.json`](https://prairielearn.readthedocs.io/en/latest/schemas/infoCourse/), [source code](https://github.com/PrairieLearn/PrairieLearn/blob/ab1e0f1fc837a8da9cde3448eb785958ac42e309/docs/scripts/gen_jsonschemas.py).\n\n## Related projects:\n\n- [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans)\n- [jsonschema-markdown](https://github.com/elisiariocouto/jsonschema-markdown)\n- [adobe/jsonschema2md](https://github.com/adobe/jsonschema2md)\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Convert JSON Schema to human-readable Markdown documentation",
"version": "1.6.0",
"project_urls": {
"Bug Tracker": "https://github.com/sbrunner/jsonschema2md/issues",
"Repository": "https://github.com/sbrunner/jsonschema2md"
},
"split_keywords": [
"json schema",
" markdown",
" converter",
" parser",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e65325068e0ce9182958f76f9731c2ae619bd67027d68459aa42c86b0482d6ee",
"md5": "5f8c181966f761244935c9b4dff0e6f0",
"sha256": "b88f579d148175d628e16deeaf830335fc8f80e803899bac2fcd8b7b421d1d61"
},
"downloads": -1,
"filename": "jsonschema2md-1.6.0-cp313-cp313-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "5f8c181966f761244935c9b4dff0e6f0",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.9",
"size": 14691,
"upload_time": "2025-07-15T15:33:48",
"upload_time_iso_8601": "2025-07-15T15:33:48.586768Z",
"url": "https://files.pythonhosted.org/packages/e6/53/25068e0ce9182958f76f9731c2ae619bd67027d68459aa42c86b0482d6ee/jsonschema2md-1.6.0-cp313-cp313-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2a944dc247dfe01f46124a98398e025506c8cf6c931f431ec24c4a9f5d1f35bc",
"md5": "8dbb3c1ec3a49ebaf463e0d85ed71964",
"sha256": "449996b85d82e2792f79613bd7f8d3ed2bb245606b10f8d59f44a9e3a4d3e7ea"
},
"downloads": -1,
"filename": "jsonschema2md-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "8dbb3c1ec3a49ebaf463e0d85ed71964",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15854,
"upload_time": "2025-07-15T15:33:49",
"upload_time_iso_8601": "2025-07-15T15:33:49.635688Z",
"url": "https://files.pythonhosted.org/packages/2a/94/4dc247dfe01f46124a98398e025506c8cf6c931f431ec24c4a9f5d1f35bc/jsonschema2md-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 15:33:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sbrunner",
"github_project": "jsonschema2md",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsonschema2md"
}
JSON
