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 Share on XThe 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.
Figure 1 – Fiware JSON Schema definition
Figure 2. Excerpt of the UML Class diagram obtained from the JSON Schema
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).
I’m an Associate Professor at UOC and researcher at SOM Research Team, in Barcelona, Spain. My research interests are mainly focused on Model-Driven Engineering (MDE), Domain-Specific Languages and Collaborative Development.
What is the scope of the scale of the systems you aim to handle?
This probably affects the layouting algorithm you (can) use?
FYI – I am starting a project on layouting of reverse engineered UML diagrams….
Hi Michel, the current implementation generates UML models as XMI files which can later be imported in diagramming tools such as Papyrus to render UML Class Diagrams. This allows us to concentrate efforts on the discovery/mapping process as the layout algorithm is a research problem “per se”. Happy to know about your advances of the that project.
Hi Michel, I’ve been working on UML class and sequence diagram layout some time ago. May be our ideas can be useful for your project. You can have a look on Nikiforova O., Ahilcenoka D., Ungurs D., Gusarovs K., Kozacenko L. Several Issues on the Layout of the UML Sequence and Class Diagram (2014) here http://www.thinkmind.org/index.php?view=article&articleid=icsea_2014_2_30_10205
is it possible to convert the Json Schema to a PostgreSQL database structure
I used your json schema to uml tool in Papyrus, following all your directions on the GitHub site. It wasn’t able to correctly do the conversion. It came up with one class called “Unknown”. The JSON file in question is very large, however I validated it with an online JSON validator and it said it was “Valid JSON”. I’ve used your tool before with no problem. Do you have any idea what might be the problem?
Hi Jessie, thanks for using our tool! I guess that something is going wrong in the JSON Schema analysis and the tool cannot discover the type of some elements (and therefore the resulting UML class is Unknown). We should check what JSON element is the source of the problem. Maybe we can continue by email, can you contact me at [email protected]?
I am facing exactly similar problem – I have a JSON schema and am trying to generate the class diagram using the same tool. However, none of the generated classes are having any class attributes or even the relations. If you prefer, I can share the JSON schema. But I am not sure how I can do that with you.
Hi Tarak, yes, no problem, contact me at [email protected]
Hi, same issue. I was trying to create the UML from a fairly small JSON Schema (200 lines ~ 10Kb), and the only thing that appears in the Papyrus model is an “Unknown” class that seems to be empty.
I’ll be using another tools to create my diagrams from here onwards, but I still wanted to let you guys know, in case it helps someone else.
Hi MCB, thanks for the report. The tool has been archived. Unfortunately, we can no longer keep its development alive. We can provide some help on its maintenance/evolution, but currently we don’t have resources to develop it.
pls can you make a video tutorial because the instructions given in the github file is unclear. like how do i import a json file to eclipse and how what am i right clicking on after that. its not really clear
Hi Pam,
indications for importing and right-clicking can be found in the Eclipse manual:
https://help.eclipse.org/kepler/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2FgettingStarted%2Fqs-31a.htm
We have also improved the README.me to consider this, we hope it is clearer now.
Hi,
I have yet to try out the tool, I have a question in advance. Which schema version are you supporting? I have schemas with frequent use of conditional properties or content and those came in with version 0.7.
Thanks!
Hi Wolfgang,
The tool was developed for the JSON-Schema specification published on November 19, 2017. If I’m not wrong, version 0.7 was publisehd on March 2018.
Hi Javier,
thanks for the quick reply.
Yes, November 2017 was 0.6 and that did not have conditionals.
Any plan to support version 0.7 in the future? It is mainly a couple of keywords and the conditionals, which could be modeled by association constraints (eg. XOR), OCL or similar to modeling “oneOf”.
No plans in the short-term, but if you want to give it a try, I can point you where you have to touch at 🙂
Hi Javier!
I tried to convert a large Json schema to UML. Some troubles came up with one class called “Unknown” as Jessie (Jessie Jewitt on March 7, 2019 at 7:46 pm). There is any new update in order to solve it?
Thx in advance!
Hi Eneko, thanks for trying the tool. According to your indications, it may happen that the input JSON was too complex (or ad-hoc) and the discoverer just applies the fallback behavior (i.e., creating an “Unknown” class). Unfortunately, there are no plans to update the tool in the short-term. However, any help on keeping it alive is more than welcome 🙂
Hi Javier,
Is there any way we can do the reverse engineering from uml to json schema?
Hi Nividita,
curiously enough, I have been working on the contrary way, from jsonSchema to UML (https://github.com/SOM-Research/jsonSchema-to-uml).
Maybe the most nearest thing we have been doing to do the reverse engineering from UML to JsonSchema is our WAPIml approach, where UML models are used to generate OpenAPI definitions (which include a schema section using jsonSchema format). You can find the repo here: https://github.com/opendata-for-all/wapiml
Regards,
Hi Javier,
my name is Christoniki and I am currently a post doc. I would like to use your tool but basically eclipse doenst upload it. I am able to uplaod thw tool but I cant use it as a plugin afterwards. Could you please help me or if you have any demo it would be really nice if you can share it with me. Thank you in advance. Christoniki
Hi Christoniki,
thanks for giving a try to the tool. The easiest way is to clone the repo and import the projects (inside the “plugins” folder) in your Eclipse installation.
Cheers,
This article is kind of old .. but I wanted to thank the author and any other devs who helped to create this tool.
tl;dr: This works extremely well. So much so that it has influenced some of the stylistic details in how we write our schemas.
Some details: We have a full-stack product that was initially developed by small teams, using agile methods. Over time, the model has become more complex, original developers have moved on, etc. etc., and it has reached the point in its lifecycle where it needs proper documentation. So we have started the task of building formal metadata for our object model.
Like most modern, full-stack architectures, the objects in our application can exist in a variety of forms. We use MongoDB for persistent storage. It’s a full-stack app, so the hydrated objects in client or server memory are managed by JS (or TS) code .. and so forth.
Since MongoDB is effectively the “system of record”, we undertook our project by mining existing stores for various installations of our product for statistical schema, using mongodb-schema. Then we translated them to Swagger 2.0 yaml, using a mix of tools and manual intervention. While Swagger 2.0 is not the most expressive syntax, it’s expressive enough, and almost all transformation tools out there can digest it. As a result, it’s almost ideal as a central store for metadata. From that central store, we can automatically generate documentation, TS type declarations. MongoDB “linters” (using mongoDB $jsonSchema operator), and …
UML! Which is where WAPIml comes in. Any time that we change the central schema, we run a WAPIml import as one of the tests. That ensures that we can always generate a UML “library” that can be used for various purposes (internal documentation, new feature design, customer-facing documentation for customers who use our platform to support automated research, etc.)
In any case, thanks again! WAPIml is an important cornerstone of our metadata initiative, and we were glad it was created.
Dear Michael,
Thanks a lot for your nice words. It’s always encouraging to know somebody thinks our tools are useful
Hi Michael,
thanks for your kind words, happy to see that, even being old, the tool still addresses current problems 🙂
Cheers,