Skip to main content

jsonschema-markdown

PyPI Docker CalVer

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 $defs or definitions
  • Nested objects with dot notation (e.g., parent.child[].property)
  • Basic oneOf, anyOf, allOf functionality
  • Conditional schemas with if/then/else
  • 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
  • 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 definitions or $defs parameter 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.

Metadata

Release files for jsonschema-markdown 2026.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jsonschema-markdown 2026.11.0
File Size Uploaded Provenance Actions
jsonschema_markdown-2026.11.0.tar.gz 15.0 kB Without provenance Details for jsonschema_markdown-2026.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jsonschema-markdown 2026.11.0
File Interpreter ABI Platform Actions
jsonschema_markdown-2026.11.0-py3-none-any.whl Python 3 none any Details for jsonschema_markdown-2026.11.0-py3-none-any.whl

Total release size: 30.4 kB

Release files / jsonschema_markdown-2026.11.0.tar.gz

Download URL jsonschema_markdown-2026.11.0.tar.gz
Size 15.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b21b1d0452533d7cbf80b1959c77d9fe6781d161f5c235f49acef08bceb003b3
BLAKE2b-256 checksum
How to use checksums
e2aea3f65a8d3ee451c5009776b3ba73192ac2294ab6493b61d261e5b29fb303
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.11.0-py3-none-any.whl

Download URL jsonschema_markdown-2026.11.0-py3-none-any.whl
Size 15.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
45d3b5973abf959cc5e0e3680a18379a0c5f719140667c27cd6ecdd9e79f50e7
BLAKE2b-256 checksum
How to use checksums
87197aa04b41128cf1b53ed56855b10f87075e6251f21b99653be3beaf7607d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.11.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.

Release history Release notifications | RSS feed

This release

2026.11.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page