npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@digidem/jsonschema2md

v3.1.0

Published

Validate and document complex JSON Schemas the easy way.

Downloads

296

Readme

JSON Schema Markdown Tools

CircleCI Greenkeeper badge

Documenting 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.

These tools have been introduced by Adobe to document Adobe's Experience Data Models (XDM), but can be used for other JSON Schema documents, too.

Requirements

  • npm version 3.10.8 or up
  • node v8 or up

Example Output

Using the schemas in examples/schemas, the output in examples/docs has been generated.

Installing and running

# clone this project
$ npm install -g @adobe/jsonschema2md

# show usage information
$ jsonschema2md

# run task
# leave out the -v "06", when you have draft-07 schemas
$ jsonschema2md -d examples/schemas -o examples/docs -v "06"
# generated output for whole folder is written to ./examples/docs

JSON Schema Draft Versions

jsonschema2md assumes draft-07 by default. If your schemas are not on draft-07, you can specify the draft version using the -v or --draft flag.

# run against JSON Schema Draft 04
$ jsonschema2md -d examples/schemas -o examples/docs -v 04
# run against JSON Schema Draft 06
$ jsonschema2md -d examples/schemas -o examples/docs -v 06

Using JSON Schema Markdown Tools from npm

You 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

  "devDependencies": {
    "@adobe/jsonschema2md": "^1.0.6"
  }

Then add the following to the "scripts" section of your package.json and adapt accordingly:

"scripts": {
  "prepare": "mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas/draft-04
}

If 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.

Tests

Ensure you have all the dependencies installed via npm install, then run:

npm test

This will run our Jasmine test suite as well as lint the JavaScript according to our style guide (see below).

CI

Continuous integration runs on CircleCI. All pull requests automatically trigger a job that runs the tests by executing the config.yml.

Code Coverage

You can run npm run cover to get a code coverage report, that is, a sense of how much of the project's code is "covered" by the test suite.

Style Guide / Linting

This project uses eslint to enforce JavaScript coding style. To run the linter:

npm run lint

TODOs

  • JSON Schema validation:
    • property naming convention
    • vocabulary spellchecking

Contributing

Please see Contributing.md for details. Pull requests are welcome.

License/Copyright

Copyright 2017 Adobe Systems Incorporated. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0