Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
json-schema-for-humans
Advanced tools
Quickly generate a beautiful static HTML or Markdown page documenting a JSON schema
Documentation (with visual examples)
pip install json-schema-for-humans
Options for generation of the doc are documented using the library itself: HTML version - Markdown version
They can be supplied in various ways:
--config-file
--config
ConfigurationOption
object from codeMore details are available in the appropriate sections below.
generate-schema-doc [OPTIONS] SCHEMA_FILES_OR_DIR [RESULT_FILE_OR_DIR]
SCHEMA_FILES_OR_DIR
can be:
All schemas provided must be a valid JSON Schema (in JSON or YAML format)
Examples:
my_schema.json
my_folder
my_folder/my_schema.yaml,another_schema.json
**/*.yaml.*
The default value for RESULT_FILE_OR_DIR
depends on the context:
schema_doc.html
if rendering a single schema as HTMLschema_doc.md
if rendering a single schema as MarkdownIn a case where more than one schema is provided as input, RESULT_FILE_OR_DIR
must be a directory. The output documentation will have the same name as the input schema, but with a different extension (html
or md
).
To choose a template on the CLI, use --config template_name=[TEMPLATE_NAME]
.
For example --config template_name=js
(HTML) or --config template_name=md
(Markdown).
The list of available templates is documented here
Supply generation config parameters. The parameters are documented in the JSON schema config_schema.json
at the root of the repo or see the generated doc: HTML version - Markdown version.
Each parameter is in the format --config parameter_name=parameter_value
. Example: --config expand_buttons=true
. The parameter value must be valid JSON.
For flags, you can also omit the value for true
or prefix the parameter name with no_
for false
. Example: --config expand_buttons
or --config no_expand_buttons
.
Path to a JSON or YAML configuration file respecting the schema config_schema.json
.
Example: --config-file jsfh-conf.yaml
where jsfh-conf.yaml
is in the current directory and contains the following:
description_is_markdown: false
expand_buttons: true
copy_js: false
The following methods are available to import from json_schema_for_humans.generate
Method Name | Schema input | Output | CSS and JS copied? |
---|---|---|---|
generate_from_schema | schema_file as str or pathlib.Path | Rendered doc as a str | No |
generate_from_filename | schema_file_name as str or pathlib.Path | Rendered doc written to the file at path result_file_name | Yes |
generate_from_file_object | schema_file as an open file object (read mode) | Rendered doc written to the file at result_file , which must be an open file object (in write mode) | Yes |
Notes:
To reduce the number of parameters to pass from function to function in the code, there is a GenerationConfiguration
object that should be used for providing options.
Example:
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration
config = GenerationConfiguration(copy_css=False, expand_buttons=True)
generate_from_filename("my_schema.json", "schema_doc.html", config=config)
# Your doc is now in a file named "schema_doc.html". Next to it, "schema_doc.min.js" was copied, but not "schema_doc.css"
# Your doc will contain a "Expand all" and a "Collapse all" button at the top
generate_from_schema
has a loaded_schemas
parameter that can be used to pre-load schemas. This must be a dict with the key being the real path of the schema file and the value being the result of loading the schema (with json.load
or yaml.safe_load
, for example).
This should not be necessary in normal scenarios.
See the excellent Understanding JSON Schema to understand what are those checks
The following are supported:
minItems
, maxItems
, uniqueItems
, items
, prefixItems
, additionalItems
, and contains
oneOf
, allOf
, anyOf
, and not
These are not supported at the moment (PRs welcome!):
References are supported:
{ $ref: "#/definitions/something" }
{"$ref": "references.json"}
, {"$ref": "references.json#/definitions/something"}
, {"$ref": "file:references.json"}
, {"$ref": "file:references.json#/definitions/something}
{"$ref": "http://example.com/schema.json"}
, {"$ref": "http://example.com/schema.json#/definitions/something"}
You can have a description
next to a $ref
, it will be displayed in priority to the description from the referenced element.
If you have several attributes using the same definition, the definition will only be rendered once.
All other usages of the same definition will be replaced with an anchor link to the first render of the definition.
This can be turned off using --config no_link_to_reused_ref
. See With references
in the examples.
Templates control the style of the generated documentation.
This is the default template. It uses Bootstrap along with minimal Javascript to allow for the following:
anyOf
, oneOf
, allOf
) are in tabbed sectionsWhen using this template, you need to include the Javascript file (schema_doc.min.js
) that is automatically copied next to the output HTML file (schema_doc.html
by default).
This schema is identical to the js template, but all CSS and JavaScript resources are bundled so that the generated documentation can be used in an offline setting.
Note: This template is a work in progress
It is sometimes not possible or desirable to include custom Javascript in documentation. This template addresses this issue by removing interactive elements in favor of simpler HTML.
At the moment, this means the whole documentation is generated without any collapsible sections, which may make it hard to understand the schema structure. Contributions are welcomed to improve it!
Note: This template is a work in progress
This template allows users to publish the generated documentation without hosting an HTTP server.
On GitHub, this format is rendered directly when browsing code.
A table of content is provided at the beginning of the file for easy navigation.
You can display some important information as badge using an option. See doc: HTML version - Markdown version
Contributions are welcomed to improve it!
FAQs
Generate static HTML documentation from JSON schemas
We found that json-schema-for-humans demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.