{"id":13565493,"url":"https://github.com/adobe/jsonschema2md","last_synced_at":"2026-01-06T00:14:33.361Z","repository":{"id":27304454,"uuid":"113048559","full_name":"adobe/jsonschema2md","owner":"adobe","description":"Convert Complex JSON Schemas into Markdown Documentation","archived":false,"fork":false,"pushed_at":"2025-05-12T18:24:35.000Z","size":5996,"stargazers_count":671,"open_issues_count":48,"forks_count":150,"subscribers_count":42,"default_branch":"main","last_synced_at":"2025-05-13T21:06:17.416Z","etag":null,"topics":["json-schema","markdown"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adobe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"Contributing.md","funding":null,"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,"zenodo":null}},"created_at":"2017-12-04T13:51:19.000Z","updated_at":"2025-05-12T18:24:03.000Z","dependencies_parsed_at":"2023-09-24T21:02:22.124Z","dependency_job_id":"208f5afe-20c7-4416-bb07-194c136b0773","html_url":"https://github.com/adobe/jsonschema2md","commit_stats":{"total_commits":1030,"total_committers":54,"mean_commits":"19.074074074074073","dds":0.625242718446602,"last_synced_commit":"cdcffd7940352551bf3f94b6325cf1adc450bc62"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fjsonschema2md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fjsonschema2md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fjsonschema2md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fjsonschema2md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adobe","download_url":"https://codeload.github.com/adobe/jsonschema2md/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059521,"owners_count":22007771,"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":["json-schema","markdown"],"created_at":"2024-08-01T13:01:48.342Z","updated_at":"2026-01-06T00:14:33.320Z","avatar_url":"https://github.com/adobe.png","language":"JavaScript","readme":"# JSON Schema Markdown Tools\n\n[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/adobe/jsonschema2md/main.yaml)](https://github.com/adobe/jsonschema2md/actions/workflows/main.yaml)\n\nDocumenting and validating complex JSON Schemas can be hard. This tool makes it easier by providing a number of scripts that can turn JSON Schema files into readable Markdown documentation that is ready for consumption on GitHub or processed using Jekyll or other static site generators.\n\nThese tools have been introduced by Adobe to document Adobe's Experience Data Models (XDM), but can be used for other JSON Schema documents, too.\n\n## JSON Schema Support\n\n`jsonschema2md` is developed against JSON Schema `2019-09`, but not the full vocabulary is supported. Please check the [detailed list of JSON Schema keywords supported by `jsonschema2md`](schemasupport.md). This list is updated by our tests.\n\n## Requirements\n\n- `npm` version 3.10.8 or up\n- `node` v18 or v20 or up\n\n## Example Output\n\nUsing the schemas in [`examples/schemas`](examples/schemas) (note the `*.schema.json` extension), the output in [`examples/docs`](examples/docs) has been generated.\n\n## Installing and running\n\n```bash\n$ npm install -g @adobe/jsonschema2md\n\n# show usage information\n$ jsonschema2md\n\n# run task\n$ jsonschema2md -d examples/schemas -o examples/docs\n# generated output for whole folder is written to ./examples/docs\n```\n\nBy default, `jsonschema2md` looks for schema files ending in `*.schema.json`. You can specify another extension by using the `--schema-extension` or `-e` command line argument.\n\n## Internationalization\n\nThe generated documentation can be internationalized. Select the language you want to use for the output using the `-l` parameter.\n\nSupported languages are:\n- English\n- German\n\nIf you want to provide a translation of your own, [please use GitLocalize](https://gitlocalize.com/repo/3622)\n\n## Display custom attributes in the property description\n`jsonschema2md` displays only the attributes of an property which are defined by the JSON Schema standard. If you want to display additional attributes in the property description you could provide these with the `--properties` (or `-p`) parameter.\n\n```bash\n# include both the `version` and the `test` attribute\n$ jsonschema2md -d examples/schemas -o examples/docs -p version -p test\n```\n\n## Disable header template\nIn some cases you do not need a header because it does not provide any useful information. With the `--header` (or `-h`) parameter you can disable the inclusion of headers.\n\n```bash\n# run against JSON Schema Draft 06\n$ jsonschema2md -d examples/schemas -o examples/docs -v 06 -h false\n```\n\n## Examples as YAML\n\nIf you are using JSON Schema to validate YAML documents, for instance configuration files, you might wish for examples to be formatted as YAML, not JSON. Using the command line option `-f yaml` or `--example-format yaml` achieves this goal.\n\n## Using JSON Schema Markdown Tools from `npm`\n\nYou can conveniently use the JSON Schema Markdown Tools from `npm`. This makes it possible to set up a conversion toolchain for your JSON Schema project that is driven entirely by `npm`. To do so, first define the dependency by adding this to your `\"devDependencies\"` section of `package.json`\n\n```json\n  \"devDependencies\": {\n    \"@adobe/jsonschema2md\": \"^6.0.0\"\n  }\n```\n\n### With script\n\nThen add the following to the `\"scripts\"` section of your `package.json` and adapt accordingly:\n\n```json\n\"scripts\": {\n  \"prepare\": \"mkdir -p docs/reference \u0026\u0026 jsonschema2md -o docs/reference -d schemas/draft-04\"\n}\n```\n\nIf you run `npm install` before running `npm run prepare`, `npm` will install the `@adobe/jsonschema2md` in a `node_modules/.bin` path, even if you did not install the JSON Schema Markdown beforehand.\n\n\n### With API for Node.js\n\n```javascript\nconst {jsonschema2md} = require('@adobe/jsonschema2md');\nconst schema = require('examples/schemas/example.schema.json');\n\nconst markdown = jsonschema2md(schema, {\n  includeReadme: true,\n});\n````\n\n## Tests\n\nEnsure you have all the dependencies installed via `npm install`, then run:\n\n```bash\nnpm test\n```\n\nThis will run our Jasmine test suite as well as lint the JavaScript according to our style guide (see below).\n\n### CI\n\nContinuous integration runs on Github Actions.\nAll pull requests automatically trigger a job that runs the [tests](#tests) by executing the [`main.yml`](.github/workflows/main.yaml). \n\n### Code Coverage\n\n`npm run test` will generate a code coverage report at the end of the test run. Anything below 100% coverage counts as a test failure.\n\n## Style Guide / Linting\n\nThis project uses [eslint](https://eslint.org) to enforce JavaScript coding style. To run the linter:\n\n```bash\nnpm run lint\n```\n\n## TODOs\n\nAdd support for [missing keywords](schemasupport.md)\n\n## Contributing\n\nPlease see [Contributing.md](Contributing.md) for details. Pull requests are welcome.\n\n## License/Copyright\n\nCopyright 2017 Adobe Systems Incorporated. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n","funding_links":[],"categories":["JavaScript","markdown"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fjsonschema2md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadobe%2Fjsonschema2md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fjsonschema2md/lists"}