# 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.
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`)
## 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
```
## Changelog
See [Changelog.md](https://github.com/sbrunner/jsonschema2md/blob/master/CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/sbrunner/jsonschema2md",
"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/67/bd/6c6d5c48a269c13212d1c7aa294e0d1a3948c97e91ee01ce5e4218e4567d/jsonschema2md-1.3.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\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\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## Changelog\n\nSee [Changelog.md](https://github.com/sbrunner/jsonschema2md/blob/master/CHANGELOG.md).\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Convert JSON Schema to human-readable Markdown documentation",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/sbrunner/jsonschema2md",
"Repository": "https://github.com/sbrunner/jsonschema2md"
},
"split_keywords": [
"json schema",
" markdown",
" converter",
" parser",
" documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a298dc9f7a2d8d1f0625fa19eb65a613e40bbff43d102d92c6802e28f213bb0e",
"md5": "337cbfc9a74217bb7137a54148db80d6",
"sha256": "ba089d46a3ac6f43b10caeaf8cd1b3978c7bd15c8e287de78d247666cb8857c0"
},
"downloads": -1,
"filename": "jsonschema2md-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "337cbfc9a74217bb7137a54148db80d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10261,
"upload_time": "2024-08-07T10:10:31",
"upload_time_iso_8601": "2024-08-07T10:10:31.801944Z",
"url": "https://files.pythonhosted.org/packages/a2/98/dc9f7a2d8d1f0625fa19eb65a613e40bbff43d102d92c6802e28f213bb0e/jsonschema2md-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "67bd6c6d5c48a269c13212d1c7aa294e0d1a3948c97e91ee01ce5e4218e4567d",
"md5": "5899953159cd16e9384818da9bbd762b",
"sha256": "5ee8f6674c9fec7303daa24c79023805caf2f2fefb99834813bd746227d146ea"
},
"downloads": -1,
"filename": "jsonschema2md-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "5899953159cd16e9384818da9bbd762b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9767,
"upload_time": "2024-08-07T10:10:33",
"upload_time_iso_8601": "2024-08-07T10:10:33.374738Z",
"url": "https://files.pythonhosted.org/packages/67/bd/6c6d5c48a269c13212d1c7aa294e0d1a3948c97e91ee01ce5e4218e4567d/jsonschema2md-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-07 10:10:33",
"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
