1EdTech TECH TALK
Contributed by Dr. Colin Smythe, 1EdTech Chief Architect
Make the Best Use of 1EdTech Technical Artifacts to Get the Most from Your 1EdTech 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, 1EdTech Contributing Member (CM) organizations identify the scope of a new spec and when we need to create a new version. 1EdTech 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 1EdTech 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 1EdTech publishes a specification as a Final Release, there must be a minimum number of certified implementations by the early adopters identified in the Charter.
1EdTech 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 1EdTech 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
1EdTech 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 1EdTech website, the Conformance Test Systems and Reference Implementations are restricted to 1EdTech members.
The 1EdTech 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 1EdTech 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 1EdTech undertakes its activities.
Document control for all work-in-progress and “issue tracking” is done through 1EdTech GitHub. At present, we have nearly 200 GitHub repositories. Access to the 1EdTech GitHub is limited to 1EdTech members only. Finally, we have an 1EdTech 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 1EdTech 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 1EdTech PURL server. Access to draft versions of these artifacts is essential for 1EdTech members when they become early adopters.
Conformance Test Systems
Another benefit of 1EdTech membership is your listing in the 1EdTech Product Directory of certified products. Certification requires the use of the 1EdTech Conformance Testing Systems. In the case of data model specification, this includes the use of the 1EdTech 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 1EdTech 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, 1EdTech provides certification of the actual content being exchanged. In most cases, this is XML-based content, and we use our XSDs for validation. The 1EdTech 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 1EdTech PURL server).
Reference Implementations
The most recent additions to the set of specification artifacts are the 1EdTech 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 1EdTech members only, and experience shows that using an 1EdTech Reference Implementation can significantly reduce the time and effort for producing a working solution.
We're Here to Help
1EdTech Contributing Members take the lead in creating an 1EdTech specification. The conformance test systems, the reference implementations, etc., are developed by the 1EdTech technical team. Before using one of these artifacts, we encourage you to have a discussion with the appropriate 1EdTech 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 1EdTech 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 1EdTech staff or reach out to me directly at csmythe@imsglobal.org.
