# jsonschema-markdown
[](https://pypi.org/project/jsonschema-markdown/)
[](https://hub.docker.com/r/elisiariocouto/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.
## Installation
```bash
pipx 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.
```bash
$ 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]
--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.
```bash
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:
- [elisiariocouto/jsonschema-markdown](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)
- [ghcr.io/elisiariocouto/jsonschema-markdown](https://ghcr.io/elisiariocouto/jsonschema-markdown)
## 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.
```python
import jsonschema_markdown
with open('schema.json') 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`
- Basic `oneOf`, `anyOf`, `allOf` functionality
- Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecated fields (using the `deprecated` option, additionaly searches for case-insensitive `deprecated` in the field description)
- Supports optional YAML and JSON formatting for examples
## Caveats
- This project is still in early development, and the output may change in the future.
- 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.
- Inline nested definitions are not represented in the output yet. See #18.
---
## Examples
### Example 1 Input
Given the following JSON Schema:
```json
{
"$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 Ouput
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`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | | | | |
| genre | `string` | | `Action` `Comedy` `Drama` `Science Fiction` | | | | |
| duration | `string` | | string | | | | |
| cast | `array` | | string | | | | |
---
Markdown generated with [jsonschema-markdown](https://github.com/elisiariocouto/jsonschema-markdown).
---
### Example 2
In [tests/model.py](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](tests/model.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/elisiariocouto/jsonschema-markdown",
"name": "jsonschema-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "jsonschema, markdown, documentation, docs, json",
"author": "Elisi\u00e1rio Couto",
"author_email": "elisiario@couto.io",
"download_url": "https://files.pythonhosted.org/packages/54/2b/2df90582d252dbac925fb28b2b973ecb17aa325f1e2df77c31704c99e177/jsonschema_markdown-0.3.13.tar.gz",
"platform": null,
"description": "# jsonschema-markdown\n\n[](https://pypi.org/project/jsonschema-markdown/)\n[](https://hub.docker.com/r/elisiariocouto/jsonschema-markdown)\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## Installation\n\n```bash\npipx 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 --version Show the version and exit.\n --help Show this message and exit.\n\n# Example\n$ jsonschema-markdown schema.json > 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 - > schema.md\n```\n\u26a0\ufe0f **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 - Basic `oneOf`, `anyOf`, `allOf` functionality\n - Arrays\n - Integers with minimum, maximum values and exclusives\n - Boolean values\n - Deprecated fields (using the `deprecated` option, additionaly searches for case-insensitive `deprecated` in the field description)\n - Supports optional YAML and JSON formatting for examples\n\n## Caveats\n - This project is still in early development, and the output may change in the future.\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 - Inline nested definitions are not represented in the output yet. See #18.\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 Ouput\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` | \u2705 | string | | | | |\n| director | `string` | \u2705 | string | | | | |\n| releaseDate | `string` | \u2705 | 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\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export a JSON Schema document to Markdown documentation.",
"version": "0.3.13",
"project_urls": {
"Homepage": "https://github.com/elisiariocouto/jsonschema-markdown",
"Repository": "https://github.com/elisiariocouto/jsonschema-markdown"
},
"split_keywords": [
"jsonschema",
" markdown",
" documentation",
" docs",
" json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca836f0f9bfe1c0bd63e5df4fb06843e5c0a5ebb5eaa2fb5cad10b589aa696e1",
"md5": "aa6ce905c878a4a9d9b937620bacb4a9",
"sha256": "184a6b8d65324bbe7a185f9f746feb5a3ed503296c2860f661e75fe3366f82b6"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa6ce905c878a4a9d9b937620bacb4a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 10843,
"upload_time": "2024-10-24T20:27:51",
"upload_time_iso_8601": "2024-10-24T20:27:51.204099Z",
"url": "https://files.pythonhosted.org/packages/ca/83/6f0f9bfe1c0bd63e5df4fb06843e5c0a5ebb5eaa2fb5cad10b589aa696e1/jsonschema_markdown-0.3.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "542b2df90582d252dbac925fb28b2b973ecb17aa325f1e2df77c31704c99e177",
"md5": "1c0c667413eeabd9056010d0df0d9e44",
"sha256": "983d1ac74e8c5a24234b646fb30a0aff62183acd44cb88b2afda29bfd158ddae"
},
"downloads": -1,
"filename": "jsonschema_markdown-0.3.13.tar.gz",
"has_sig": false,
"md5_digest": "1c0c667413eeabd9056010d0df0d9e44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10633,
"upload_time": "2024-10-24T20:27:53",
"upload_time_iso_8601": "2024-10-24T20:27:53.560302Z",
"url": "https://files.pythonhosted.org/packages/54/2b/2df90582d252dbac925fb28b2b973ecb17aa325f1e2df77c31704c99e177/jsonschema_markdown-0.3.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 20:27:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elisiariocouto",
"github_project": "jsonschema-markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsonschema-markdown"
}
JSON
