Sharebar?

Make the Best Use of IMS Technical Artifacts

 

IMS Chief Architect Dr. Colin SmytheIMS TECH TALK

Contributed by Dr. Colin Smythe, IMS Chief Architect

 

Make the Best Use of IMS Technical Artifacts to Get the Most from Your IMS Membership

One advantage of having created many edtech specifications over many years is that we have learned from many, many mistakes. This is significant for the continual improvement of our development process.

In the main, IMS Contributing Member (CM) organizations identify the scope of a new spec and when we need to create a new version. IMS staff facilitate the process. The creation of a specification starts with its “Charter” document. The Charter defines the scope and names the CMs committed to early adoption. Both the Charter and the final set of spec documents and supporting artifacts undergo formal vote by the IMS Technical Advisory Board. All CMs have the option to vote, with each CM having only one vote. During the development of a specification, only CMs have access to the documents and other artifacts. Before IMS publishes a specification as a Final Release, there must be a minimum number of certified implementations by the early adopters identified in the Charter.

IMS Contributing Members determine the edtech specifications we create, gain the first-to-market opportunity, and drive the pace at which we develop new versions.

Every IMS specification consists of a set of HTML documents. Apart from the detailed definition of the spec itself (the Information Models and the Technology Binding documents), we provide two special documents:

 → Implementation Guide

  • Contains detailed descriptions of how to use the specification best

 → Conformance & Certification

  • Defines the criteria by which a product will be certified as correctly implementing the specification

IMS also provides several other artifacts to ease implementation of a specification, including:

 → Machine-Readable Forms of the Specification

 → Conformance Test Systems

 → Reference Implementations

While the specification documents are available to everyone through the IMS website, the Conformance Test Systems and Reference Implementations are restricted to IMS members.

The IMS website contains hundreds of thousands of web pages. Fortunately, there are a few simple guidelines to follow to make it easier to navigate. There are strict rules on where we place various types of information. Everyone has free access to the IMS specifications and a wide range of support information. Members also get access to restricted information and support tools. Public and member-only Forums are available—we use these as the formal record of information dissemination. For example, we release all completed draft versions of the specification documentation for review through the forums.

The set of forums reflect how IMS undertakes its activities.

Document control for all work-in-progress and “issue tracking” is done through IMS GitHub. At present, we have nearly 200 GitHub repositories. Access to the IMS GitHub is limited to IMS members only. Finally, we have an IMS Slack channel used by our specification development Working Groups to facilitate real-time discussions (but not for any part of our formal processes).

Machine-Readable Forms of the Specification
Whenever possible, we produce machine-readable files of an IMS specification. Developers use these to enable rapid prototyping of an implementation. The machine-readable formats we use are XML Schema Definition (XSD), Web Service Description Language (WSDL), JSON Schema, JSON-LD Context, and OpenAPI files. Several other formats are also under evaluation, including GraphQL and AsyncAPI. All of these files are made available through the IMS PURL server. Access to draft versions of these artifacts is essential for IMS members when they become early adopters.

Conformance Test Systems
Another benefit of IMS membership is your listing in the IMS Product Directory of certified products. Certification requires the use of the IMS Conformance Testing Systems. In the case of data model specification, this includes the use of the IMS Online Validator. For service-based specifications, e.g., OneRoster, etc., we create unique conformance test systems. We provide tests for both ends of the service, i.e., one for systems providing the API (Providers) and another for systems using the API (Consumers). We have made a substantial investment in developing and maintaining the conformance test systems, and IMS members get unlimited usage of these systems. Experience has shown that our testing systems catch a wide range of implementation bugs. Some members also use our test systems as part of their product development process.

For some specs, such as Common Cartridge, IMS provides certification of the actual content being exchanged. In most cases, this is XML-based content, and we use our XSDs for validation. The IMS Online Validator hosts all of the separate content validators. New validators are deployed easily (the XSDs used by the validator are those hosted on the IMS PURL server).

Reference Implementations
The most recent additions to the set of specification artifacts are the IMS Reference Implementations, with the one for LTI Advantage being the most notable success. Our goal for every reference implementation is to support all aspects of a specification. More importantly, we produce the reference implementations in a framework that makes it easy for developers to use them as part of their in-house test and development process. Reference implementations are available to IMS members only, and experience shows that using an IMS Reference Implementation can significantly reduce the time and effort for producing a working solution.

We're Here to Help

IMS Contributing Members take the lead in creating an IMS specification. The conformance test systems, the reference implementations, etc., are developed by the IMS technical team.  Before using one of these artifacts, we encourage you to have a discussion with the appropriate IMS technical staff. A thirty-minute call will avoid a lot of wasted time and effort. We also run a Support Portal. This provides logging of issues about the conformance test systems, reference implementations, and any of the other tools that we provide. Finally, it is important to stress that IMS staff are available to provide guidance on what information is relevant, how to get the relevant information, and how to avoid many of the most common problems.

Need help getting started? Contact IMS staff or reach out to me directly at csmythe@imsglobal.org