Using a Model-Driven Specification Approach

IMS Global TECH TALK

Contributed by Dr. Colin Smythe, IMS Chief Architect

Creating IMS Specifications Using a Model-Driven Specification Approach

Background

In 1999, IMS published its first two eLearning interoperability specifications: IMS Metadata and IMS Enterprise Data Model.

In 2000, IMS Content Packaging and IMS Question & Test Interoperability specifications followed.

These specifications were developed and documented as Microsoft Word documents with tabular-based descriptions of the data models. For all of them, the actual interoperability was based upon the exchange of XML files. Initially, we created Document Type Definition (DTD), then XML Schema Definition (XSDs) files to provide machine-enabled validation of the XML files. Eventually, the IMS specification development process was based on creating the relevant Information Model, XML Binding and the Best Practices and Implementation Guide documents, and the accompanying DTD/XSD files. The documents were created using Microsoft Word and published as PDF documents. The DTD/XSD files were created using early versions of XML authoring tools (we are still in the 2001-2003 period). Many other standardization organizations had similar approaches and used similar toolsets. In 2004, IMS started work on their first service-based specification (Enterprise Services). Once again, the interoperability technology was XML-based but now requires SOAP messages with Web Service Description Language (WSDL) files used to provide a machine-readable version of the API. Again, we created MS Word documents with lots of tables.

In early 2006 it became clear that our specification development approach had limitations:

• The information model and XML binding documents and the accompanying DTD/XSDs were being created through three separate manual processes and, no surprise, there were many discrepancies between them, many of which were trivial, but some were significant and caused a lot of confusion and implementation problems;
• The specifications were becoming increasingly complex, so the tabular-based descriptions were large and difficult to understand. Also, the number and significance of the discrepancies was increasingly problematic;
• The creation and maintenance of new versions were becoming difficult. The combination of increased complexity and maintaining consistency across the different, manually produced, and changing artifacts was resulting in unacceptably error-prone documentation;
• The inclusion of service-based specification development and the accompanying new set of binding technologies was proving difficult to define and describe with the required precision and accuracy using MS Word documents;
• There was increasing awareness that conformance testing and certification of products—with respect to the specification—would be essential so the corresponding conformance test systems had to be created and maintained.

Transition

In 2006, we decided to move to a Model-Driven Specification (MDS) approach. The primary objective was to create a process by which the definition and description of a specification were entered into a machine-readable format (the model) once, and from that model, ALL of the artifacts would be produced using auto-generation transformations. Therefore, in the worst case, any error would be consistently present in ALL of the artifacts. This has the benefit that any error identified in one artifact can be used to fix that same error in all of the artifacts. In 2005, the IMS Enterprise Service 1.0 and a new version of the IMS Content Package specifications developed using the IMS MDS approach were published. All of the required benefits were achieved, but we also confirmed some drawbacks:

• The design of the specification required a more abstract approach for the creation of the model and the actual implementation details only became evident once the binding information was autogenerated;
• The modeling was based upon the use of Unified Modeling Language (UML); the new transformation toolkit and the learning curve for these were difficult and time-consuming.

Summary

Many engineers from IMS Contributing Members did not have the time or skills to understand the details of this new approach or use the new toolkit. There was more significant dependence on the IMS technical staff to facilitate the development of the specifications. This made understanding the proposed specification and consensus-building more difficult.

Over the following decade, the IMS MDS approach underwent considerable evolution and refinement. The tooling remained based on UML using the Eclipse hosted open-source Papyrus tool, the corresponding IMS profile of UML to enable the IMS MDS approach, and the set of proprietary transformation tools. The currently supported artifacts include HTML documents, XSD and WSDL files, OpenAPI and JSON Schema files, JSON Linked Data files, and the set of PHP files used to support the conformance testing of the implementation of a service provider for the corresponding IMS service specification. The MDS approach also supports the definition of Profile of an IMS base specification: a Profile enables the adaptation of a specification to fit the specific requirements of a market, geographic, etc., communities.  

In 2018 we undertook an internal review of the specification development activities in the context of the next generation of MDS. That review identified several key objectives for that next generation:

• The use of combinations of specifications was becoming more common, so more effective visualization and interaction with the specification documentation sets were required. This leads to the Student Learning Data Model and the IMS Common Data Model;
• Reusability of data models was becoming important. Using the same data model improves integration between specifications, but this requires the definition of the data models to enable tailoring at the point of inclusion into a specification to avoid unnecessary bloating of a specification. This is accompanied by the application of a set of frameworks that define common patterns to be used across the IMS specifications (the IMS Security Framework is the first of these frameworks);
• Contributing Members required better integration of the materials without curtailing their types of input (currently supplied using Google docs, markdown, MS Word, etc.). A process by which CMs can amend and then review the changed model and artifacts needed to be introduced;
• The codebase for the XSLT was aging, and a complete rewrite was required. The range of target artifacts was still increasing, and so the full UML-based approach needed to be revised;
• More agile specification development requires the use of a Continuous Integration/Continuous Deployment (CI/CD) process to link the IMS GitHub repositories with the IMS Tech Forums, Website, and PURL server so that a single change to the underlying model can result in rapid update and deployment of all of the associated artifacts;
• The MDS approach must create a new set of common libraries that will be reused to develop the corresponding conformance tests systems, reference implementations and support the Compatibility Check.

Looking Ahead

For the past three years, the IMS technical staff have worked on all of the above objectives. In the past 12 months, several changes in the IMS specification development process have become evident. The EDU-API, Comprehensive Learner Record 2.0, and Open Badges 3.0 specifications are prototyping many revised MDS approaches. In the next 12 months the following changes will be delivered:

• The IMS Common Data Model visualization technique will be extended to include support for the wide range of IMS service operations and the realization as REST/JSON-based endpoints;
• All of the HTML-based documents will be rendered in the IMS profile of Respec. This includes those documents that are autogenerated from the MDS approach and those that are created manually;
• The Versioning, Extensions, and JSON API frameworks will be completed, and as new IMS specifications and new versions are produced, support of these frameworks will be included;
• The modeling approach will be extended to include support for the Publish/Subscribe-based service bindings;
• The set of specification documents and artifacts will be published through the new MDS-integrated CI/CD process.

The focus will move to the conformance and certification, reference implementations, and Compatibility Check aspects of the IMS specification development process in the longer term. Conformance & Certification are an essential part of the IMS process. We must continue to improve the quality and reduce the time taken to establish these for our specifications. This will reduce the effort and time taken to create conformance and certification of Profiles of the IMS specifications and make it even easier to create, manage and maintain IMS ecosystems.