We live in a data-driven world where managing and providing access to data has become key for any kind of business. However, data management can easily turn into a very hard task as companies usually have to deal with a huge amount of heterogeneous data sources in a variety of data formats like XML, RDF or JSON Schema. Btw, this is one of the main challenges of open data initiatives.

Among these formats, JSONSchema is becoming more and more popular. JSONSchema is a specification to annotate and validate JSON documents (for instance as part of an OpenAPI specification). JSONSchema annotations allow describing the format of JSON data elements in a human- and machine-readable way, thus promoting data documentation and automated data testing. Despite the popularity of JSONSchema, very few tools target the visualization and understanding of JSONSchema definitions.

In this post, we present our tool JSONSchema-to-UML, a tool to generate UML models from JSON schema documents. JSONSchema-to-UML has been developed as part of a collaborative project with Cmind.

JSONSchema-to-UML automatically creates UML class diagrams out of JSONSchema specifications Click To Tweet

The tool analyzes JSON Schema definitions and generates a UML Class Diagram including the data elements as concepts, attributes, and relationships. By providing a graphical representation, developers can easily visualize the data model behind a set of JSON Schema definitions, thus promoting understanding and maintainability. The tool is available as an open source Eclipse plugin. All the instructions on how to install and use the tool are available in the Github repository.

Generating UML Class diagrams from JSON Schema definitions

The generation process applied by the tool follows this (non-exhaustive) list of mappings:

  • Each JSON Schema element is represented by a UML Class
  • Properties in JSON Schema elements represent the properties of a UML Class
    • If the property is of primitive type it will become an attribute in the UML Class
    • If the property is of type enum, an Enumeration will be created and an attribute in the UML Class will be added
    • If the property is of type object or refers to another element (using $ref), an association is created in the UML Class. The type of the association corresponds to the UML Class element created from the object (or the referred object)
  • Hierarchies are created from allOf, oneOf, anyOf
  • The elements defined in definitions are considered as a library of JSON Schema elements and therefore they generate new UML Classes
  • The folder structure is used to created UML Packages containing the UML Classes coming from the JSON Schema files

JSONSchema to UML example

We show an example in the next figures. Figure 1 shows an excerpt of a JSON Schema definition (extracted from FIWARE JSON Schema data models) while Figure 2 shows a part of the UML Class Diagram extracted with our tool.


Fiware JSON Schema definition

Figure 1 – Fiware JSON Schema definition

Figure 2. Part of the UML Class diagram obtained from the JSON Schema

Figure 2. Excerpt of the UML Class diagram obtained from the JSON Schema

With JSONSchema-to-UML you could, for instance, create nice UML visualizations to help you understand the data provided by @Fiware sensors Click To Tweet

Challenges of a JSONSchema to UML transformation

The mapping between JSON Schema and UML Class diagram elements is not trivial and some of them may depend on the domain where the tools is applied. Some of the domain-specific challenges we identified while developing the tool were the following:

  • How to properly deal with allOf, oneOf, anyOf and the generated hierarchy
  • How to deal with constraints in the number of properties of a concept
  • How to support regular expressions in JSON Schema elements
  • Incorporate full support for $ref
  • When a Class, Enumeration or Datatype should be created

We believe that extra information to customize the generation process for particular domains could improve the precision and quality of the resulting UML Class diagrams. We would like to explore how to parameterize our tool to inject this domain-specific information.

This tool complements our other tools in this same “data-understanding” domain: OpenAPItoUML (to generate UML models from OpenAPI definitions) and JSON Discoverer (to get a possible schema out of a set of plain JSON documents).

Want to build better software faster?

Want to build better software faster?

Read about the latest trends on software modeling and low-code development

You have Successfully Subscribed!

Pin It on Pinterest

Share This