{"id":15012977,"url":"https://github.com/elisiariocouto/jsonschema-markdown","last_synced_at":"2026-02-22T01:34:47.212Z","repository":{"id":182144721,"uuid":"668017222","full_name":"elisiariocouto/jsonschema-markdown","owner":"elisiariocouto","description":"📖 Generate markdown documentation based on a JSON Schema document","archived":false,"fork":false,"pushed_at":"2025-02-26T00:00:49.000Z","size":294,"stargazers_count":19,"open_issues_count":1,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T19:43:55.736Z","etag":null,"topics":["documentation","documentation-generator","jsonschema","jsonschema-markdown","markdown"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/jsonschema-markdown/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elisiariocouto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["elisiariocouto"]}},"created_at":"2023-07-18T20:32:02.000Z","updated_at":"2025-03-12T16:50:19.000Z","dependencies_parsed_at":"2024-04-02T17:27:18.120Z","dependency_job_id":"b4949050-6c9b-4c86-94f0-127f52b2c549","html_url":"https://github.com/elisiariocouto/jsonschema-markdown","commit_stats":{"total_commits":91,"total_committers":6,"mean_commits":"15.166666666666666","dds":0.07692307692307687,"last_synced_commit":"5d3377b1d066e0ea00d2c1f4c5f18cb25787e41f"},"previous_names":["elisiariocouto/jsonschema-markdown"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elisiariocouto%2Fjsonschema-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elisiariocouto%2Fjsonschema-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elisiariocouto%2Fjsonschema-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elisiariocouto%2Fjsonschema-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elisiariocouto","download_url":"https://codeload.github.com/elisiariocouto/jsonschema-markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767239,"owners_count":20992548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-generator","jsonschema","jsonschema-markdown","markdown"],"created_at":"2024-09-24T19:43:33.083Z","updated_at":"2026-02-22T01:34:47.200Z","avatar_url":"https://github.com/elisiariocouto.png","language":"Python","funding_links":["https://github.com/sponsors/elisiariocouto"],"categories":[],"sub_categories":[],"readme":"# jsonschema-markdown\n\n[![PyPI](https://img.shields.io/pypi/v/jsonschema-markdown)](https://pypi.org/project/jsonschema-markdown/)\n[![Docker](https://img.shields.io/docker/v/elisiariocouto/jsonschema-markdown)](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)\n[![CalVer](https://img.shields.io/badge/CalVer-YYYY.MM.MICRO-22bfda.svg)](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\u003e **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\nuv tool 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  --sort-yaml-keys / --no-sort-yaml-keys\n                                  Sort keys in YAML examples. Only applies\n                                  when --examples-format is yaml.  [default:\n                                  no-sort-yaml-keys]\n  --version                       Show the version and exit.\n  --help                          Show this message and exit.\n\n# Example\n$ jsonschema-markdown schema.json \u003e 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 - \u003e schema.md\n```\n⚠️ **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  - Conditional schemas with `if`/`then`/`else`\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  - Configurable key ordering in YAML examples (preserves insertion order by default, optional sorting)\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` | ✅ | string |  |  |  |  |\n| director | `string` | ✅ | string |  |  |  |  |\n| releaseDate | `string` | ✅ | 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felisiariocouto%2Fjsonschema-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felisiariocouto%2Fjsonschema-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felisiariocouto%2Fjsonschema-markdown/lists"}