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:
- Creating a new project
- Adding new objects to the JSON schema
- Making modifications
- Defining specifications
- Adding a subschema
- Generating scripts
- Importing existing structures
- 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.
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
Newly added nodes:
- property0 (type Object)
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.
Two items will be added after the anyOf node automatically.
To model if/then/else elements, select the Condition menu item.
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.
3. Making modifications
You can change the item name directly in the 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.)
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.
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.
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.
If you have Display locally referenced mode enabled, the subchema structure will be displayed to the right of the original element.
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.
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.
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.
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.