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.
Note: This project follows CalVer (YYYY.MM.MICRO) versioning and maintains backward compatibility whenever possible. New features and enhancements are always encouraged!
Installation
uv tool 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.
$ 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]
--sort-yaml-keys / --no-sort-yaml-keys
Sort keys in YAML examples. Only applies
when --examples-format is yaml. [default:
no-sort-yaml-keys]
--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.
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:
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.
import jsonschema_markdown
with open('schema.json', 'r', encoding='utf-8') 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
$defsordefinitions - Nested objects with dot notation (e.g.,
parent.child[].property) - Basic
oneOf,anyOf,allOffunctionality - Conditional schemas with
if/then/else - Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecated fields (using the
deprecatedoption, additionally searches for case-insensitivedeprecatedin the field description) - Supports optional YAML and JSON formatting for examples
- Configurable key ordering in YAML examples (preserves insertion order by default, optional sorting)
Caveats
- Custom definitions are expected to be in the same file as the schema that uses them,
in the
definitionsor$defsparameter at the root of the document.
Examples
Example 1 Input
Given the following JSON Schema:
{
"$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 |
||||
| genre | string |
Action Comedy Drama Science Fiction |
|||||
| duration | string |
string | |||||
| cast | array |
string |
Markdown generated with jsonschema-markdown.
Example 2
In 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.
1 maintainer
Metadata
1 maintainer
Release files for jsonschema-markdown 2026.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| jsonschema_markdown-2026.8.0.tar.gz | 14.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jsonschema_markdown-2026.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 30.1 kB
Release files / jsonschema_markdown-2026.8.0.tar.gz
| Download URL | jsonschema_markdown-2026.8.0.tar.gz |
|---|---|
| Size | 14.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b286414d739f918fdff4213945a1e1b0d7ffab4f94f4d1d410545b8c9224d06a
|
|
BLAKE2b-256 checksum How to use checksums |
0f3763180ecca99a546aff73a0f2b7ccd392e173c94ba061d44a211b3f46e7da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / jsonschema_markdown-2026.8.0-py3-none-any.whl
| Download URL | jsonschema_markdown-2026.8.0-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e2e91634167fc5f4c8550b974661efb96f744abb02f08a9e2aaaa9f33271020
|
|
BLAKE2b-256 checksum How to use checksums |
a0b08afefa8ccca19b57cf5ebdd46d5766d3e3422feb725758f4392853c6ba04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for jsonschema-markdown 2026.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
