Skip to main content

Convert JSON Schema to human-readable Markdown documentation

Project description

jsonschema2md

Convert JSON Schemas to simple, human-readable Markdown documentation.


For example:

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "description": "JSON Schema for a person object.",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person's last name."
    }
  }
}

will be converted to:

Person

JSON Schema for a person object.

Properties

  • firstName (string): The person's first name.
  • lastName (string): The person's last name.

See the examples directory for more elaborate examples.


Installation

Install with pip

pip install jsonschema2md

Usage

From the CLI

jsonschema2md [OPTIONS] <input.json> <output.md>

From Python

import json
import jsonschema2md

parser = jsonschema2md.Parser(
    examples_as_yaml=False,
    show_examples="all",
)
with open("./examples/food.json", "r") as json_file:
    md_lines = parser.parse_schema(json.load(json_file))
print(''.join(md_lines))

Options

  • examples_as_yaml: Parse examples in YAML-format instead of JSON. (bool, default: False)
  • show_examples: Parse examples for only the main object, only properties, or all. (str, default all, options: object, properties, all)
  • show_deprecated: Show deprecated properties. (bool, default: True)
  • collapse_children: Collapse object children into a <details> element (bool, default: False)
  • header_level: Base header level for the generated markdown. (int, default: 0)
  • ignore_patterns: List of regex patterns to ignore when parsing the schema. (list of str, default: None)

pre-commit hook

You can use the pre-commit hook with:

repos:
  - repo: https://github.com/sbrunner/jsonschema2md
    rev: <version> # Use the ref you want to point at
    hooks:
      - id: jsonschema2md
        files: schema.json
        args:
          - --pre-commit
          - schema.json
          - schema.md

Contributing

Bugs, questions or suggestions? Feel free to post an issue in the issue tracker or to make a pull request! See Contributing.md for more info.

Install the pre-commit hooks:

pip install pre-commit
pre-commit install --allow-missing-config

Changelog

See Changelog.md.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonschema2md-1.5.2.tar.gz (11.4 kB view details)

Uploaded Source

Built Distribution

jsonschema2md-1.5.2-py3-none-any.whl (12.1 kB view details)

Uploaded Python 3

File details

Details for the file jsonschema2md-1.5.2.tar.gz.

File metadata

  • Download URL: jsonschema2md-1.5.2.tar.gz
  • Upload date:
  • Size: 11.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for jsonschema2md-1.5.2.tar.gz
Algorithm Hash digest
SHA256 338cc3909a25d1424b6823b13e17782d40f0faed97be42ba8abb22b96a1d82f9
MD5 a06c6792c3856110ab5503f0cccf0aaa
BLAKE2b-256 1c40fa685991204a0ae72e486720add480b8f21088e4a62c238c50fba506b9d6

See more details on using hashes here.

File details

Details for the file jsonschema2md-1.5.2-py3-none-any.whl.

File metadata

  • Download URL: jsonschema2md-1.5.2-py3-none-any.whl
  • Upload date:
  • Size: 12.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for jsonschema2md-1.5.2-py3-none-any.whl
Algorithm Hash digest
SHA256 50492b944514ceac69d979d410b1a8a865c6a05a9bbc65a6a277ce10a61a9cab
MD5 eaa28dd54f878741d777187b5ec73929
BLAKE2b-256 74417a4b0ae6bff4ca1938f51943a0b77804acf459357f570f72d78567dc9570

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page