Edit online

Generating JSON Schema Documentation

Oxygen JSON Editor includes a tool for generating documentation for a JSON Schema file in HTML format. To generate JSON Schema documentation, select JSON Schema Documentation from the Tools > Generate Documentation menu. You can also open the tool by using the Generate Documentation toolbar button. This opens a dialog box where you can specify the location of the JSON Schema file and HTML output file.

This tool requires an additional add-on to be installed, so the first time you invoke the action, Oxygen JSON Editor presents a dialog box asking if you want to install it. Once installed, you need to restart Oxygen JSON Editor and the JSON Schema Documentation action will invoke the tool.

Quick Installation

You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:

Install

Manual Installation

To manually install it the add-on, follow these instructions:
  1. Go to Help > Install new add-ons to open an add-on selection dialog box.
  2. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
    Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
  3. Select the JSON Schema Documentation add-on and click Next.
  4. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
  5. Restart the application.

Result: The JSON Schema Documentation dialog box is now available and can be selected from the Tools > Generate Documentation menu.

JSON Schema Documentation Dialog Box

Figure 1. JSON Schema Documentation Dialog Box
The JSON Schema Documentation dialog box includes the following fields and options:
JSON Schema URL
The URL of the JSON Schema file. You can specify the path by using the text field, the history drop-down menu, or the browsing actions in the Browse drop-down list. The tool supports schemas with versions Draft 04, 06, 07 and, starting with version 4.0.0 of the add-on, 2019-09 and 2020-12.
Output file
The path to the folder where the generated HTML file will be saved.
Split output into multiple files
If selected, the application splits the output into multiple files. You can choose between splitting them by component name or location.
Open in Browser/System Application
If selected, the generated result is opened in the system application associated with the output file type (HTML).
Included component details
This section can be used to specify whether or not the following components are shown in the generated documentation:
  • Annotations - Displays the annotations (title, description) for each component (property or definition).
  • Constraints - Displays the schema constraints for each component, according to its type.
  • Properties - Displays the properties of an Object Schema.
  • Pattern Properties - Displays the patternProperties of an Object Schema.
  • Enumerations - Displays the enumerated values, if specified in the schema.
  • Source - Displays the text schema source for each component.
  • Used By - Displays the list of all the components that reference the current definition.
  • Composition - Displays the oneOf, anyOf, and allOf compositors that are used for combining schemas.
  • Diagram - Displays the diagram image for each component. The diagrams are generated according to the options specified in the Schema Design preferences page. Diagrams are also generated for components within schemas from referenced files.
  • Image Map - Diagrams will include hyperlinks that navigate to each particular component.
  • Location - Displays the schema location for each component.

You can click Generate at any point to generate the JSON Schema documentation.

Generated JSON Schema Documentation in HTML Format

After generating the JSON Schema documentation, it is presented in a visual diagram style with various sections, hyperlinks, and options.

Figure 2. JSON Schema Documentation Example Opened in a Browser

The generated documentation includes a Table of Contents on the left pane with links to particular sections in the right pane. You can collapse or expand details by using the Showing options or the Collapse or Expand buttons.