Learning Objectives
- Understand the pros and cons of three different tools available for generating schemas (e.g. RDFS, XSD, JSON) from the CIM UML
- Learn how to generate schema or API definitions from the CIM UML
Going Beyond the XSD
Section 8 lists several free, open-source, and commercial tools available to automate the mapping of CIM profiles to XML. As the industry continues to move toward RESTful web services using JSON, however, tools that can support both XML and JSON schema formats will see more use from CIM developers. Analogous to the IEC 62361-100 standard for XSDs, the draft standard IEC 62361-104 is currently in development for JSON schema. Unlike the WSDL and XSD formats that have remained largely the same over the past decade, JSON Schema standards are still evolving, with new updates being released frequently with no guarantee of backwards compatibility.50
Three common tools for generating XML and JSON schemas are discussed in detail in this section:
- Schema Composer by Sparx Systems Pty Ltd.
- CIMConteXtor by Zamiren, Paris
- CIMTool by CIM Users’ Group
While this list is only a subset of the tools available for generating schemas from the CIM UML, an overview of these will provide a foundation for learning the intricacies of similar software. Each segment below lists the pros and cons of a tool and provides a short walkthrough on how to use it to generate whichever type of schema or other documentation is desired. The section on CIMTool will have a minimal walkthrough of its use since this was mostly covered in Section 8.
Due to the regularity of JSON schema version updates, having tools that stay up-to-date to address fixes or updates can be a deciding factor for many developers. Schema Composer updates will occur on a fixed schedule alongside other Enterprise Architect updates. CIMConteXtor and CIMTool, due to their open-source nature, may receive updates as quickly as possible or never at all.
Footnotes
50 See “Use of the draft designation in https://json-schema.org/. For more information about the specifications themselves, see https://json-schema.org/specification.html.
Schema Composer
Schema Composer is a tool built into the Corporate, Unified and Ultimate editions of Enterprise Architect from Sparx Systems. Unlike the other tools mentioned below, Schema Composer is not open-source. Schema Composer is also not specific to the CIM. The Sparx documentation lists other standards that it also supports. Because Schema Composer is built into Enterprise Architect, it does not require steps that other tools do, such as the exporting of XMI files, or installing additional plug-ins from third-party resources. This tool would also be ideal for those working in the other standards that Schema Composer supports.
Unfortunately, the schemas that Schema Composer generates do not follow every rule according to the IEC 62361-100 specification. For example, the IEC 62361-100 states that elements should be ordered with the mRID first, then other simple properties in alphabetical order, and then object and compound properties in alphabetical order. Although Schema Composer follows the first rule, it does not adhere to the others. As a result, Schema Composer in its current form requires some hand-editing of each schema after it has been generated to properly adhere to the IEC standards. However, the convenience of being able to use a built-in tool backed by professional support may potentially outweigh these shortcomings for some profile creators.
Schema Composer also supports JSON Schema and RDF Schema, although its support of JSON Schema as of July 2021 is Draft-04, four versions behind the most recent version listed at https://json-schema.org/specification.html.
How-To: Schema Composer
A class can be drag and dropped directly from the model’s project browser into Schema Composer. Upon doing so, it will automatically populate a full list of its associations, attributes, and inherited classes.
Checking each associated class or complex object will automatically add that class to the table view so that its appropriate attributes can be checked.
Schema Composer allows the user to right-click and set cardinality and other constraints.
When generating a profile, options include RDFS, JSON Schema, and XSD. Currently this only supports Draft 04 of JSON Schema.
Schema Composer Summary
Although the schemas created with Schema Composer are not perfect, this tool has great potential if it continues to see support by Sparx and the IEC community. Presently, however, the schemas it creates are not 100% IEC compliant and would need to be hand-edited to ensure proper interoperability. This may or may not be a concern depending on the target application. For those who want to do everything within Enterprise Architect, Schema Composer conveniently allows for the creation and saving of profiles within Enterprise Architect.
CIMConteXtor
CIMConteXtor by Zamiren is a free, open-source plug-in for Enterprise Architect. It comes in two parts: CIMConteXtor which allows the creation and management of UML profiles, and CIMSyntaxGen, which generates the schema from those models according to IEC standards such as IEC 61970-501. The developers of CIMConteXtor have been working together with the developers of CIMTool to add JSON Schema support, following the draft standard IEC 62361-104. Unlike both Schema Composer and CIMTool, CIMConteXtor profile generation results in a graphical view like that of the UML model instead of the table view of the former two. This makes it easier to see the schema structure at a quick glance.
The free, open-source nature of CIMConteXtor means it must be downloaded from a site not affiliated with Enterprise Architect. It also requires the installation of Python and specific libraries used for the plug-in. For people with strict security policies in place at their workplace, this may result in a barrier to getting started.
How-To: CIMConteXtor
After going through this short walkthrough, consider reading the software manuals provided directly on the CIMConteXtor website. These manuals discuss every nuance of the tools and modeling in Enterprise Architect itself. This how-to guide is meant to serve as a starting point for those who wish to use the tool for their own profile generation. For additional details on installing, manuals are provided on the downloads page of CIMConteXtor’s website. To start, create a new package at the project level in Enterprise Architect, right-click, select CimConteXtor, and CreateProfilePackage.
For this example, an extension to the CIM has been made that incorporates parts of IEC 61970 and IEC 61968, so in the next dialogue, those will be selected in addition to the new extensions package.
Like Schema Composer, classes can be dragged and dropped directly from the project browser. This time, instead of dropping them into a table, it is dropped onto the new empty diagram that was generated upon completing the last step. A message will pop up from CIMConteXtor. Click “Yes.”
The next box that opens will have checkboxes for selecting desired attributes. This does not list any of the class associations which are set in a different step. If this is going to be the root of the XSD or JSON Schema, check the box on the right that says “is root (active).” Click “Execute IsBasedOn” to finish generating the class in the profile.
After this class has been created, repeat the previous steps and drag another class that is associated to the root onto the diagram. Once it has been placed, right-click the class that was just added and select “Edit hierarchical connectors” to establish the association.
Pick the correct class to associate it with from the box that appears. Use the end role name to know for sure which version of the class should be picked.
With that row highlighted, select “Modify selected association.” This is where a decision must be made about whether the profile will be used to generate RDF Schema, or XSD/JSON Schema. If the former is going to be used, no change is necessary here. However, if XSD or JSON Schema is the desired end result, then check the box labeled “Containment” under the parent class to define a unidirectional association between the classes.
From this point on, the process repeats until all classes for the desired profile have been added. The final result will be a view not unlike that of the profiles in the information model packages themselves.
For the next step of generating a schema, the CimSyntaxGen plug-in must be used. Like CIMConteXtor, this also has its own manual to goes into deeper detail. To generate a schema, right-click the profile package and select CimSyntaxGen, then pick your schema of choice.
The next dialogue will look slightly different depending on the format chosen, but in all cases there are text fields that must be filled out with information such as the root node name, the file name and where to save it, which version of JSON Schema should be used, and what the namespace and namespace prefix should be.
The last thing the tool will ask is about the cardinality of the root node. Provide that and the schema will be complete.
CIMConteXtor Summary
CIMConteXtor is a good alternative to CIMTool for those who don’t want to leave Enterprise Architect while creating their profiles. The schemas it creates conform to the IEC standards for XSDs and the IEC draft standard for JSON Schema. The developers of CIMConteXtor have been working together with the CIMTool team to ensure both tools remain in lockstep with the draft standard for JSON Schema. Its graphical profile view can be appealing to those who prefer a visual representation of the schema.
CIMConteXtor may not be a viable option if security policies prevent the installation of a third-party program that writes its data to the AppData folder in Windows. It also currently requires administrator access to generate XSDs so that it can access XSDexample.xsd within the Enterprise Architect directory in Program Files.
Like Schema Composer, CIMConteXtor allows for the creation and saving of profiles directly within Enterprise Architect, making it ideal for those who want to keep to one environment when creating CIM schemas.
CIMTool
Although CIMTool was discussed in detail in Section 8, it is worth mentioning again here due to recent changes. As of May 2020, a new version of CIMTool51 was released that supports the IEC 62361-104 draft standard for JSON Schema. Development of CIMTool has moved from its original developer of Langdale Consultants to the CIM Users’ Group.
CIMTool and Schema Composer share some similarities when it comes to the design of the schema using table views. The main difference is in the final form of the schema that is produced, with the one from CIMTool currently adhering to the IEC specification for all schema formats. Unlike Schema Composer where the schema is designed within Enterprise Architect and saved in its own package, CIMTool requires the export of the model so that CIMTool can be used to develop the schema, either in the form of an XMI file or as a duplicated version of the Enterprise Architect file itself. This could be inconvenient for those who prefer developing schemas in the same environment as the information model.
Footnotes
51 The latest version of CIMTool can be accessed on GitHub at https://cimug-org.github.io/CIMTool/, while the original version and documentation is still accessible at https://wiki.cimtool.org/.
Summary
Each tool used to generate schema from the CIM UML can work depending on its intended use. Below is a table summarizing the capabilities of each to help determine which tool might work best.
Table 14-1: A comparison of tools used to generate schemas in the CIM
| Capability | Schema Composer | CIMConteXtor | CIMTool |
|---|---|---|---|
| Generates XSD | Yes | Yes | Yes |
| Generates JSON Schema | Yes (limited) | Yes | Yes |
| Generates RDFS | Yes | Yes | Yes |
| View | Table | Graphical | Table |
| Open-Source | No | Yes | Yes |
| IEC 62361 Compliant | No | Yes | Yes |
| Supports Other Standards | Yes | No | No |
| Profile Configuration Export | No | No | Yes |
| Profiles Saved to EA | Yes | Yes | No |
Case Study
Jeff Kimble’s enterprise application team has begun making the transition from SOAP to REST for many of their services. Jeff has just learned that many of the tools used to generate schema from the CIM information model now support JSON Schema. He was also happy to learn that these tools have added support for generating HTML documentation of their services, so that their public-facing webpage can provide details on the API.
As Jeff’s team continues to extend the CIM for their own internal needs, he feels confident that they can do so for other formats besides XSD in a way that adheres to the IEC specifications.
IEC 61970 covers the definition for:
A
IEC specification 62361-100
B
IEC draft specification 62361-104
C
The CIM
D
XML
A. IEC specification 62361-100
All schemas generated from the CIM UML are correct as long as the classes and attributes come from the CIM.
A
True
B
False
B. False
All schemas generated from the CIM UML are correct as long as the classes and attributes come from the CIM.
A
True
B
False
B. False
Of the three tools described in this section, which one requires a separate profile definition for RDFS (in other words, you can't use the same profile to make both an XSD and RDFS)?
A
Schema Composer
B
CIMConteXtor
C
CIMTool
D
None of the above
B. CIMConteXtor
Of the three tools described in this section, which one requires an export of the information model from Enterprise Architect?
A
Schema Composer
B
CIMConteXtor
C
CIMTool
D
None of the above
C. CIMTool
Only official CIM classes can be used with these tools, not extensions.
A
True
B
False
B. False