# jsonschema-markdown
[](https://pypi.org/project/jsonschema-markdown/)
[](https://hub.docker.com/r/elisiariocouto/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.
Easy to use in CI/CD pipelines, as a Docker image is available.
## 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
The goal is to support the latest JSON Schema specification, `2020-12`. However,
this project does not currently support all features, but it should support:
- Required fields
- String patterns
- Enumerations
- Default values
- Descriptions and titles
- Nested objects using `$defs` or `definitions`
- Basic `oneOf`, `anyOf`, `allOf` functionality
- Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecated fields (using the `deprecated` option, additionaly 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/4c/d8/ec54dd2629aa81889e4264cd83efddba73166617526582504dfc025ebf20/jsonschema_markdown-0.3.10.tar.gz",
"platform": null,
"description": "# jsonschema-markdown\n\n[](https://pypi.org/project/jsonschema-markdown/)\n[](https://hub.docker.com/r/elisiariocouto/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\nEasy to use in CI/CD pipelines, as a Docker image is available.\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\nThe goal is to support the latest JSON Schema specification, `2020-12`. However,\nthis project does not currently support all features, but it should support:\n\n - Required fields\n - String patterns\n - Enumerations\n - Default values\n - Descriptions and titles\n - Nested objects using `$defs` or `definitions`\n - Basic `oneOf`, `anyOf`, `allOf` functionality\n - Arrays\n - Integers with minimum, maximum values and exclusives\n - Boolean values\n - Deprecated fields (using the `deprecated` option, additionaly 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\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export a JSON Schema document to Markdown documentation.",
"version": "0.3.10",
"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": "562ae045857b0670743202fbe5f054c511ba23bd377d6e4d2d4c8f5e5d838e94",
"md5": "af65907d3c8324997efd1fef601af073",
"sha256": "65d3c7f147a8f02f54030d617bad89ddbe6d6ba1b83954713ea666bc324b0f71"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af65907d3c8324997efd1fef601af073",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9793,
"upload_time": "2024-09-18T19:42:50",
"upload_time_iso_8601": "2024-09-18T19:42:50.325958Z",
"url": "https://files.pythonhosted.org/packages/56/2a/e045857b0670743202fbe5f054c511ba23bd377d6e4d2d4c8f5e5d838e94/jsonschema_markdown-0.3.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cd8ec54dd2629aa81889e4264cd83efddba73166617526582504dfc025ebf20",
"md5": "4ae5590ad8fa56cc9665b9925cf0900d",
"sha256": "232466430dcf2be505f20e9caa8e3f5da946ae06f78941855d13c8706d2aa67c"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.10.tar.gz",
"has_sig": false,
"md5_digest": "4ae5590ad8fa56cc9665b9925cf0900d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 9071,
"upload_time": "2024-09-18T19:42:51",
"upload_time_iso_8601": "2024-09-18T19:42:51.737976Z",
"url": "https://files.pythonhosted.org/packages/4c/d8/ec54dd2629aa81889e4264cd83efddba73166617526582504dfc025ebf20/jsonschema_markdown-0.3.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 19:42:51",
"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
