# jsonschema-markdown
Generate markdown documentation from JSON Schema files. The main goal is to generate
documentation that is easy to read and understand.
Can be used as a command line tool or as a library.
## Installation
```bash
pipx install jsonschema-markdown
```
## Usage
To use `jsonschema-markdown` as a CLI, just pass the filename as an argument and redirect
the output to a file.
```bash
$ jsonschema-markdown --help
Usage: jsonschema-markdown [OPTIONS] FILENAME
Load FILENAME and output a markdown version.
Use '-' as FILENAME to read from stdin.
Options:
-t, --title TEXT Do not use the title from the schema, use
this title instead.
--footer / --no-footer Add a footer with a link to the project.
[default: footer]
--empty-columns / --no-empty-columns
Remove empty columns from the output, useful
when deprecated or examples are not used.
[default: empty-columns]
--resolve / --no-resolve [Experimental] Resolve $ref pointers.
[default: no-resolve]
--debug / --no-debug Enable debug output. [default: no-debug]
--version Show the version and exit.
--help Show this message and exit.
# Example
$ jsonschema-markdown schema.json > schema.md
```
## Usage with Docker
The `jsonschema-markdown` command is also available as a Docker image. To use it, you can mount the schema file as a volume.
```bash
cat my-schema.json | docker run --rm -i elisiariocouto/jsonschema-markdown - > schema.md
```
⚠️ **Warning**: Do not pass the `-t` flag.
The Docker image is available at:
- [elisiariocouto/jsonschema-markdown](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)
- [ghcr.io/elisiariocouto/jsonschema-markdown](https://ghcr.io/elisiariocouto/jsonschema-markdown)
## Usage as a library
To use it as a library, load your JSON schema file as Python `dict` and pass it to generate.
The function will return a string with the markdown.
```python
import jsonschema_markdown
with open('schema.json') as f:
schema = json.load(f)
markdown = jsonschema_markdown.generate(schema)
```
## Features
Partially inspired by [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans),
this project does not currently support all features of JSON Schema, but it should support:
- Required fields
- String patterns
- Enumerations
- Default values
- Descriptions and titles
- Nested objects
- Basic OneOf, AnyOf, AllOf functionality
- Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecation notices (searches for case-insensitive `deprecated` in the field description)
## Caveats
- This project is still in early development, and the output may change in the future.
- Custom definitions are expected to be in the same file as the schema that uses them,
in the `definitions` or `$defs` parameter at the root of the document.
Raw data
{
"_id": null,
"home_page": "https://github.com/elisiariocouto/jsonschema-markdown",
"name": "jsonschema-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "jsonschema, markdown, documentation, docs, json",
"author": "Elisi\u00e1rio Couto",
"author_email": "elisiario@couto.io",
"download_url": "https://files.pythonhosted.org/packages/a2/e7/6530e6041902924010c24136df69c72cc6c17d6efbda80d32a174e41a82c/jsonschema_markdown-0.3.6.tar.gz",
"platform": null,
"description": "# jsonschema-markdown\n\nGenerate markdown documentation from JSON Schema files. The main goal is to generate\ndocumentation that is easy to read and understand.\n\nCan be used as a command line tool or as a library.\n\n## Installation\n\n```bash\npipx install jsonschema-markdown\n```\n\n## Usage\n\nTo use `jsonschema-markdown` as a CLI, just pass the filename as an argument and redirect\nthe output to a file.\n\n```bash\n$ jsonschema-markdown --help\nUsage: jsonschema-markdown [OPTIONS] FILENAME\n\n Load FILENAME and output a markdown version.\n\n Use '-' as FILENAME to read from stdin.\n\nOptions:\n -t, --title TEXT Do not use the title from the schema, use\n this title instead.\n --footer / --no-footer Add a footer with a link to the project.\n [default: footer]\n --empty-columns / --no-empty-columns\n Remove empty columns from the output, useful\n when deprecated or examples are not used.\n [default: empty-columns]\n --resolve / --no-resolve [Experimental] Resolve $ref pointers.\n [default: no-resolve]\n --debug / --no-debug Enable debug output. [default: no-debug]\n --version Show the version and exit.\n --help Show this message and exit.\n\n# Example\n$ jsonschema-markdown schema.json > schema.md\n```\n\n## Usage with Docker\nThe `jsonschema-markdown` command is also available as a Docker image. To use it, you can mount the schema file as a volume.\n\n```bash\ncat my-schema.json | docker run --rm -i elisiariocouto/jsonschema-markdown - > schema.md\n```\n\u26a0\ufe0f **Warning**: Do not pass the `-t` flag.\n\nThe Docker image is available at:\n - [elisiariocouto/jsonschema-markdown](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)\n - [ghcr.io/elisiariocouto/jsonschema-markdown](https://ghcr.io/elisiariocouto/jsonschema-markdown)\n\n## Usage as a library\n\nTo use it as a library, load your JSON schema file as Python `dict` and pass it to generate.\nThe function will return a string with the markdown.\n\n```python\nimport jsonschema_markdown\n\nwith open('schema.json') as f:\n schema = json.load(f)\n\nmarkdown = jsonschema_markdown.generate(schema)\n```\n\n## Features\n\nPartially inspired by [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans),\nthis project does not currently support all features of JSON Schema, but it should support:\n\n - Required fields\n - String patterns\n - Enumerations\n - Default values\n - Descriptions and titles\n - Nested objects\n - Basic OneOf, AnyOf, AllOf functionality\n - Arrays\n - Integers with minimum, maximum values and exclusives\n - Boolean values\n - Deprecation notices (searches for case-insensitive `deprecated` in the field description)\n\n## Caveats\n - This project is still in early development, and the output may change in the future.\n - Custom definitions are expected to be in the same file as the schema that uses them,\n in the `definitions` or `$defs` parameter at the root of the document.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export a JSON Schema document to Markdown documentation.",
"version": "0.3.6",
"project_urls": {
"Homepage": "https://github.com/elisiariocouto/jsonschema-markdown",
"Repository": "https://github.com/elisiariocouto/jsonschema-markdown"
},
"split_keywords": [
"jsonschema",
" markdown",
" documentation",
" docs",
" json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1efdc96af7628a5f329e8135684aa3881c6b27dda518d614685b9d807d68be4c",
"md5": "e8bf78e49f4b5ccd39ef6468ce9be1f3",
"sha256": "db0dae62f7a7788c70538054abd3d538ceb3c68cb776896cf099963be12d9647"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8bf78e49f4b5ccd39ef6468ce9be1f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9641,
"upload_time": "2024-04-16T00:37:48",
"upload_time_iso_8601": "2024-04-16T00:37:48.646355Z",
"url": "https://files.pythonhosted.org/packages/1e/fd/c96af7628a5f329e8135684aa3881c6b27dda518d614685b9d807d68be4c/jsonschema_markdown-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a2e76530e6041902924010c24136df69c72cc6c17d6efbda80d32a174e41a82c",
"md5": "85095e4db99eb66922e220aad16d11f8",
"sha256": "6ea02f2e02b9e05d700af82e872acb5cb450de633d2f8c4cab9f4e6dcc48ed55"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "85095e4db99eb66922e220aad16d11f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8866,
"upload_time": "2024-04-16T00:37:50",
"upload_time_iso_8601": "2024-04-16T00:37:50.335555Z",
"url": "https://files.pythonhosted.org/packages/a2/e7/6530e6041902924010c24136df69c72cc6c17d6efbda80d32a174e41a82c/jsonschema_markdown-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-16 00:37:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elisiariocouto",
"github_project": "jsonschema-markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsonschema-markdown"
}
JSON
