{"id":5271,"library":"jsonschema2md","title":"jsonschema2md","description":"jsonschema2md is a Python library designed to convert JSON Schema definitions into human-readable Markdown documentation. It is actively maintained, with frequent updates that introduce new features and improvements, currently at version 1.7.0. It simplifies the process of generating clear and structured documentation directly from your JSON Schema files.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/sbrunner/jsonschema2md","tags":["JSON Schema","Markdown","documentation","converter","parser","schema"],"install":[{"cmd":"pip install jsonschema2md","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required runtime environment","package":"python","version":">=3.9","optional":false}],"imports":[{"note":"The main functionality is encapsulated within the Parser class, which is imported directly from the top-level package.","symbol":"Parser","correct":"import jsonschema2md\nparser = jsonschema2md.Parser()"}],"quickstart":{"code":"import json\nimport jsonschema2md\n\n# Example JSON Schema\nschema = {\n    \"$id\": \"https://example.com/person.schema.json\",\n    \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n    \"title\": \"Person\",\n    \"description\": \"JSON Schema for a person object.\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"firstName\": {\n            \"type\": \"string\",\n            \"description\": \"The person's first name.\"\n        },\n        \"lastName\": {\n            \"type\": \"string\",\n            \"description\": \"The person's last name.\"\n        }\n    }\n}\n\n# Initialize the parser with desired options\nparser = jsonschema2md.Parser(\n    examples_as_yaml=False,\n    show_examples=\"all\",\n    # Add other options as needed, e.g., show_deprecated=False\n)\n\n# Parse the schema and get markdown lines\nmd_lines = parser.parse_schema(schema)\n\n# Join and print the markdown output\nprint(''.join(md_lines))","lang":"python","description":"This quickstart demonstrates how to instantiate the Parser with basic options, load a JSON Schema, and convert it into Markdown string output. The resulting Markdown can then be written to a file or displayed."},"warnings":[{"fix":"Always verify installation method (`pip`) and import statements for the Python package.","message":"There is a similarly named and purposed JavaScript/Node.js package (`@adobe/jsonschema2md`). Ensure you are installing the Python `jsonschema2md` package via `pip` (from PyPI) and importing `jsonschema2md`, to avoid confusion with the Node.js ecosystem tool.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the library's GitHub repository or documentation for a list of supported JSON Schema keywords if encountering unexpected output for specific schema features.","message":"While `jsonschema2md` supports JSON Schema 2019-09, it does not implement the full vocabulary. Certain less common keywords might not be processed or rendered as expected. Always check the official documentation or test suite for a precise list of supported JSON Schema keywords.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 1.7.0 or newer to ensure robust handling of external references.","message":"Prior to version 1.7.0, support for external references (`$ref` pointing to external files or URLs) was limited or non-existent. Schemas relying heavily on external references might not have been correctly processed.","severity":"breaking","affected_versions":"<1.7.0"},{"fix":"Initialize the parser with `parser = jsonschema2md.Parser(show_deprecated=False, ...)` to hide deprecated fields.","message":"By default, deprecated fields within your JSON Schema are included in the generated Markdown. If you wish to suppress these, you must explicitly pass `show_deprecated=False` to the `jsonschema2md.Parser` constructor.","severity":"gotcha","affected_versions":">=1.5.2"},{"fix":"Upgrade to version 1.6.0 or newer and use the appropriate configuration for localization.","message":"Localization support for generating Markdown in languages other than English was introduced in version 1.6.0. Users requiring localized output (e.g., French or Portuguese) must use version 1.6.0 or later and specify the desired locale.","severity":"gotcha","affected_versions":"<1.6.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}