# jsonschema-markdown
[](https://pypi.org/project/jsonschema-markdown/)
[](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)
[](https://calver.org)
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.
> **Note:** This project follows [CalVer](https://calver.org) (YYYY.MM.MICRO) versioning and maintains backward compatibility whenever possible. New features and enhancements are always encouraged!
## 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]
--examples-format [text|yaml|json]
Format of the examples in the output.
[default: text]
--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`
- Nested objects with dot notation (e.g., `parent.child[].property`)
- Basic `oneOf`, `anyOf`, `allOf` functionality
- Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecated fields (using the `deprecated` option, additionally searches for case-insensitive `deprecated` in the field description)
- Supports optional YAML and JSON formatting for examples
## Caveats
- 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.
---
## Examples
### Example 1 Input
Given the following JSON Schema:
```json
{
"$id": "https://example.com/movie.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "A representation of a movie",
"type": "object",
"required": ["title", "director", "releaseDate"],
"properties": {
"title": {
"type": "string"
},
"director": {
"type": "string"
},
"releaseDate": {
"type": "string",
"format": "date"
},
"genre": {
"type": "string",
"enum": ["Action", "Comedy", "Drama", "Science Fiction"]
},
"duration": {
"type": "string"
},
"cast": {
"type": "array",
"items": {
"type": "string"
},
"additionalItems": false
}
}
}
```
### Example 1 Output
The following markdown will be generated:
---
# jsonschema-markdown
A representation of a movie
### Type: `object`
| Property | Type | Required | Possible values | Deprecated | Default | Description | Examples |
| -------- | ---- | -------- | --------------- | ---------- | ------- | ----------- | -------- |
| title | `string` | ✅ | string | | | | |
| director | `string` | ✅ | string | | | | |
| releaseDate | `string` | ✅ | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | | |
| genre | `string` | | `Action` `Comedy` `Drama` `Science Fiction` | | | | |
| duration | `string` | | string | | | | |
| cast | `array` | | string | | | | |
---
Markdown generated with [jsonschema-markdown](https://github.com/elisiariocouto/jsonschema-markdown).
---
### Example 2
In [tests/model.py](tests/model.py) you can see a more complex example of a model that is exported as a JSON Schema.
The output can be seen in [tests/model.md](tests/model.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonschema-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "docs, documentation, json, jsonschema, markdown",
"author": null,
"author_email": "Elisi\u00e1rio Couto <elisiario@couto.io>",
"download_url": "https://files.pythonhosted.org/packages/97/1c/1c8f72aeacacc6e08ddfdf0b70b2bf98c3fece693af89d0692e277e045ca/jsonschema_markdown-2025.7.0.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[](https://calver.org)\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> **Note:** This project follows [CalVer](https://calver.org) (YYYY.MM.MICRO) versioning and maintains backward compatibility whenever possible. New features and enhancements are always encouraged!\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 --examples-format [text|yaml|json]\n Format of the examples in the output.\n [default: text]\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 - Nested objects with dot notation (e.g., `parent.child[].property`)\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, additionally searches for case-insensitive `deprecated` in the field description)\n - Supports optional YAML and JSON formatting for examples\n\n## Caveats\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---\n\n## Examples\n\n### Example 1 Input\n\nGiven the following JSON Schema:\n```json\n{\n \"$id\": \"https://example.com/movie.schema.json\",\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"description\": \"A representation of a movie\",\n \"type\": \"object\",\n \"required\": [\"title\", \"director\", \"releaseDate\"],\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"director\": {\n \"type\": \"string\"\n },\n \"releaseDate\": {\n \"type\": \"string\",\n \"format\": \"date\"\n },\n \"genre\": {\n \"type\": \"string\",\n \"enum\": [\"Action\", \"Comedy\", \"Drama\", \"Science Fiction\"]\n },\n \"duration\": {\n \"type\": \"string\"\n },\n \"cast\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"additionalItems\": false\n }\n }\n}\n```\n\n### Example 1 Output\nThe following markdown will be generated:\n\n---\n\n# jsonschema-markdown\n\nA representation of a movie\n\n### Type: `object`\n\n| Property | Type | Required | Possible values | Deprecated | Default | Description | Examples |\n| -------- | ---- | -------- | --------------- | ---------- | ------- | ----------- | -------- |\n| title | `string` | \u2705 | string | | | | |\n| director | `string` | \u2705 | string | | | | |\n| releaseDate | `string` | \u2705 | Format: [`date`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | | |\n| genre | `string` | | `Action` `Comedy` `Drama` `Science Fiction` | | | | |\n| duration | `string` | | string | | | | |\n| cast | `array` | | string | | | | |\n\n\n---\n\nMarkdown generated with [jsonschema-markdown](https://github.com/elisiariocouto/jsonschema-markdown).\n\n---\n\n### Example 2\n\nIn [tests/model.py](tests/model.py) you can see a more complex example of a model that is exported as a JSON Schema.\n\nThe output can be seen in [tests/model.md](tests/model.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "Export a JSON Schema document to Markdown documentation.",
"version": "2025.7.0",
"project_urls": {
"Repository": "https://github.com/elisiariocouto/jsonschema-markdown"
},
"split_keywords": [
"docs",
" documentation",
" json",
" jsonschema",
" markdown"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a60131ae02467fbccbf08007d4200b491d09ca01ea73cc37304a3df1dc7072ec",
"md5": "2aaef66d655702c5cbfc74a11096e42a",
"sha256": "18561bbb5cb098263e64f38e93d5081c5307e8ba1cd5b840bbd5407e3ac0690a"
},
"downloads": -1,
"filename": "jsonschema_markdown-2025.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2aaef66d655702c5cbfc74a11096e42a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11432,
"upload_time": "2025-07-15T13:53:05",
"upload_time_iso_8601": "2025-07-15T13:53:05.818189Z",
"url": "https://files.pythonhosted.org/packages/a6/01/31ae02467fbccbf08007d4200b491d09ca01ea73cc37304a3df1dc7072ec/jsonschema_markdown-2025.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "971c1c8f72aeacacc6e08ddfdf0b70b2bf98c3fece693af89d0692e277e045ca",
"md5": "1968db6e598521d2102ab8fbd918f24d",
"sha256": "59fb1c2343e091af252130251ddee262119f4497125d51235ccc05c02dad7f5a"
},
"downloads": -1,
"filename": "jsonschema_markdown-2025.7.0.tar.gz",
"has_sig": false,
"md5_digest": "1968db6e598521d2102ab8fbd918f24d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10800,
"upload_time": "2025-07-15T13:53:06",
"upload_time_iso_8601": "2025-07-15T13:53:06.723296Z",
"url": "https://files.pythonhosted.org/packages/97/1c/1c8f72aeacacc6e08ddfdf0b70b2bf98c3fece693af89d0692e277e045ca/jsonschema_markdown-2025.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 13:53:06",
"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
