JSON Schema – Data modeling

Quick start guide for JSON Schema data modeling in Perseid Modeler.

The following text describes how to design a new JSON schema structure. This article is divided into the following sections:

  1. Creating a new project
  2. Adding new objects to the JSON schema
  3. Making modifications
  4. Defining specifications
  5. Adding a subschema
  6. Generating scripts
  7. Importing existing structures
  8. Generating HTML reports & Export to PDF

1. Creating a new project

To create a new project in Perseid Modeler click the New item on the main toolbar. A new modal form opens. Select JSON schema project type, specify name, select JSON schema version and click Create a new project. A new project is created and you can start modeling your JSON schema structure.

JSON schema modeling - new project form.

2. Adding new objects to the JSON schema

In Perseid Modeler you can add new objects via the dropdown menu. After creating a new project, the main graphical element representing the JSON schema will be displayed. Right-click on the schema and select the item that corresponds to the desired node type.

Adding Properties, Pattern Properties, Additional Properties or Dependent Schema

Adding new object to JSON schema.

Newly added nodes:

  • properties
  • property0 (type Object)
New property added.

Adding a choice/operator

To add an element of type anyOf, allOf, oneOf or not, select the appropriate item from the choice/operator sub-menu.

Adding anyOf, allOf, oneOf or not.

Two items will be added after the anyOf node automatically.

Newly added anyOf node.

Adding conditions

To model if/then/else elements, select the Condition menu item.

If, Then, Else in JSON schema

This way you can add conditions and then you can right click any of the node and select either Add property or just Add and select an item from the sub-menu. The best option depends on the result you wish to achieve.


Note: Other menu items include Array Key and Object Key. You may find these useful, especially if you are using Perseid Modeler to model structures derived from JSON schema or otherwise extended.

You can create an entire JSON schema structure in a similar way.

Sample JSON schema - tree diagram.

3. Making modifications

You can change the item name directly in the diagram.

Changing name in diagram

To change name or other properties, you can also either open the modal form by clicking the Edit button on the main toolbar or make changes in the right sidebar. For example, change type from String to Number, define a description, set the element as required, select a sub-schema or define specifications in more detail.

4. Defining specifications

Define specifications using code or the Specification assistant. The same specification can be defined in two areas. Either directly in the field Specifications:


Or visually below the Specifications field, via user interface – input fields, dropdowns etc. The section below is called Specification assistant and it displays options relevant for selected type (Object, String, Number etc.)

Specification assistant

The assistant displays the predefined properties and allows you to fill in only the values.
After entering a value, the code in the Specifications field is automatically updated.

Specification and updated field and diagram.

5. Adding a subschema to the JSON schema design

You can insert a new subschema by right-clicking in the diagram and selecting New subschema. A new graphic item will appear in the diagram below the main Schema. Right-click on it and start modeling the subschema similarly to the main schema.

New subschema

To use a subschema in the main diagram, then select the element in the diagram and set the subschema name (in this example “person”) as the Type.

Subschema selection

If you have Display locally referenced mode enabled, the subchema structure will be displayed to the right of the original element.

Subschema selected

Another way to create a subschema is to select the element in the main diagram, right-click and select Convert to subschema. In this case, Perseid Modeler will create the subschema and use this subschema as the type of the element.

External refs – Similarly, you can add external refs to the diagram. External refs are selected in the same way as the subschema, in the Type dropdown.

6. Generating scripts for JSON schema

To generate a script for JSON Schema, click the Script icon on the main toolbar. This will open a modal window where you will see a preview of the script.

Generated JSON schema script

To save scripts to files, click Save script, define a location where the output should be stored and finish the action.

On the Generation settings tab, you have the option to choose whether the output will be JSON or YAML, and in the case of JSON format, whether it will be generated as Strict or not. You can also choose whether the definitions will be listed in the definitions node, defs, or according to the detected or selected schema version.

Json or Yaml

You can also preview the script in the right sidebar. Here, only the part of the script that corresponds to the selected element in the diagram will be displayed.

7. Importing existing JSON schema structures

On the Projects page, click the Import button. Select a file and Perseid Modeler will load the structure and create a project with a diagram representing your JSON schema.

Import from files

Note: Import works with JSON schema files, we plan to import and create schema from JSON data in future releases.

8. Generating HTML reports

To export to PDF or to generate an interactive HTML report, click the Report button on the main toolbar. To generate a report, select the style and click Generate report. Follow the instructions to easily create documentation for your JSON schema.

Generate HTML report of export to PDF


Quick links

Free Trial Buy Now!

Blog categories