Comprehensive Learner Record Implementation Guide 1.0 IMS (Candidate Final)

Comprehensive Learner Record Implementation Guide

IMS Candidate Final
Version 1.0
IMS Candidate Final
Date Issued: August 26, 2019
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/clr/v1p0/

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2019 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

© 2019 IMS Global Learning Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

The IMS Comprehensive Learner Record (CLR) specification has been designed to create, transmit, and render an individual's set of achievements, as issued by multiple learning providers, in a machine-readable format that can be curated into verifiable digital records of achievement.

  1. Introduction

The IMS CLR specification supports interoperability in that CLR providers and consumers can consistently send, receive, and verify records among conformant entities. The CLR specification describes an information model, service definition, and implementation guide to allow institutions, suppliers, and others to 'extend' the traditional transcript with records and types of information that are typically not found in a traditional transcript, such as competency attainment and co-curricular activities, and to define and facilitate an institution's learner achievements record store for collection of CLRs.

CLR data can be consumed by other schools, institutions, employers, and any other entities that are conformant as CLR consumers. In this machine readable format, CLR data enables granular and expansive discoverability of learning achievements that was not previously possible.

The purpose of this Implementation Guide is to provide the collected and collated best practice recommendations for the adoption of the IMS Comprehensive Learner Record specification. This information was produced during the development of the specification and from the feedback of the IMS members that have adopted CLR.

  1.1 Status of this Document

This document is the Candidate Final Release, meaning the technical specification is also in Candidate Final Status. IMS Members are currently working towards successful completion of conformance certification.

IMS strongly encourages its members and the community to provide feedback to continue the evolution and improvement of the CLR standard. To join the IMS developer and conformance certification community focused on CLR please visit the IMS Digital Credentials and Badging Alliance online here: https://www.imsglobal.org/digital-credentials-and-badging-alliance

  1.2 Specification Documents

CLR specification documents are available on the IMS website:

  1.3 Where Can I Get Help?

If you have questions or need help with implementing CLR or achieving conformance certification, here are some available resources:

  • Public Forum for all parties interested in CLR.
  • Affiliates Forum for IMS Digital Credentials and Badging Alliance Members, Affiliate, and Contributing Members.
  • Reference Implementation for @@@ TBD
  • IMS Contributing Members have access to private GitHub repositories and a Slack channel for CLR Project Group discussions and collaborations. Contact an IMS staff member to gain access.

Conformance Certification

IMS offers a process for testing the conformance of products using the IMS certification test suite. Certification designates passing a set of tests that verify the standard has been implemented correctly and guarantees a product’s interoperability across hundreds of other certified products. The CLR Conformance Certification Guide [CLR-CONF-10] provides details about the testing process, requirements, and how to get started.

Conformance certification is much better than claims of “compliance," since the only way IMS can guarantee interoperability is by obtaining certification for the latest version of the standard. Only products listed in the official IMS Certified Product Directory can claim conformance certification. IMS certification provides the assurance that a solution will integrate securely and seamlessly into an institution's digital learning ecosystem.

In order to become LTI certified a paid IMS membership is necessary. Here's why: while conformance certification provides a "seal" for passing prescribed tests it is much more than that. It is a commitment by a supplier to the IMS community for continuous support for achieving "plug and play" integration. Certification implies ongoing community commitment to resolve problems, revise implementations and retest as need. For that reason, only IMS Contributing Members, Affiliate Members and Learning Tools and Content Alliance members are eligible to apply for conformance certification. Details and benefits of membership are listed here: https://www.imsglobal.org/imsmembership.html.

This document is an informative resource in the Document Set of the Comprehensive Learner Record specification [CLR-OVER-10]. As such, it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance critera for implementors of this specification.

  1.4 Product Directory Listing

The IMS Certified Product Directory is the official listing of products that have passed IMS Global conformance certification testing. Products that are listed in this directory are guaranteed to meet the IMS standards for which they have passed testing. If you experience an integration issue with a product listed here, IMS will work with the supplier to resolve the problem. If a product is NOT listed here it has either not passed IMS testing or its certification has expired.

  1.5 Key Terms and Definitions

CLR
A document of structured data created by a Publisher containing one or more Assertions about one Learner.
Achievement
An accomplishment such as a degree, evidence of competency mastery, a course completion, or other accomplishment. An achievement may be asserted about one or more Learners (though a CLR contains records for only one Learner). Achievements may include a label (e.g. certificate, competency, course, degree, etc.) and type (e.g. CTDL credential, CASE competency, Open Badge, IMS assessment result, etc.).
Assertion
The attestation made by an Issuer about a Learner regarding an Achievement. The Assertion may also include associated evidence, results, or other metadata regarding a specific Achievement.
Association
A relationship (e.g. isChildOf, precedes, etc.) between multiple achievements.
Evidence
Information supporting the issuance of an assertion such as URL to an artifact produced by the Learner.
Issuer
The profile of an organization or entity that has made a particular Assertion about a Learner. The Issuer of an Assertion is the authoritative source for that specific Assertion.
Learner
The profile of the person who is the subject of the CLR and assertions contained in a CLR.
Publisher
The profile of the organization providing the CLR (typically the educational institution, a 3rd-party agent, or the learner). The Publisher is the official record keeper for Assertions in a CLR. In the majority of cases, the Publisher is also the Issuer of some or all of the Assertions in a CLR. Except in the case of a self-curated CLR, the publisher is either the issuer or has a trusted relationship with the issuer of all the Assertions in the CLR. In the case of a self-curated collection of Assertions, the Learner is the Publisher of the CLR.
Verification
Instructive information for third parties to verify Assertions.

  2. CLR User Stories and Use Cases

CLR has been designed to support the following User Stories as identified by IMS members:

  1. As an educational organization or other learning provider, I want to create a record of a learner’s achievement.
  2. As a learner, I want to curate records of my achievements from multiple issuers and control access to those curated records.
  3. As an educational organization, other learning provider, or employer, I want to access achievement records about a specific learner.
  4. As an educational institution, I want to provide a learner’s CLR in an offline or downloadable format to the learner. (Note: The CLR document contains personally identifiable information about the learner so appropriate data handling practices are warranted.)

  3. Relation to Other IMS Specifications

  3.1 CLR and Open Badges

  3.2 CLR and CASE

  3.3 CLR, QTI and OneRoster

CLR is a logical structure to define “achievements,” “assertions,” and their “associations”. This logical model provides an efficient structure to transform QTI results sets through OneRoster into a form in which granular achievement and other evidence can be curated into digital credentials and badges, each associated with CASE Network items.

  4. CLR Architecture

The Comprehensive Learner Record is a document containing a set of Assertions by an Issuer about a Learner. Generally, each Assertion is made by an Issuer in relationship to a described Achievement, which could be accomplished by more than one Learner. The Assertion can optionally include Evidence, a specific Result, and some type of Verification. The Publisher is the entity that produces the CLR document containing the Assertions, Achievements, etc. about the Learner.

  5. Best Practices

  5.1 Use of JSON-LD

  5.2 Security

  5.3 REST-based Exchanges

  5.4 Verification of CLRs

Verification is the process to ensure the Assertions and Endorsements within a CLR are trustworthy. (Verification is distinct from IMS conformance certification of applications and services that implement this IMS specification. (See Role of Certification in Data Validation section below.)

CLR 1.0 use cases fall into three general categories:

  1. Server to server data transfer
    • Each CLR comes from a single publisher
    • All issuers in the CLR are either the publisher OR a trusted delegate of the publisher
  2. Authorized user viewing published CLRs
    • Each CLR comes from a single publisher
    • All issuers in the CLR are either the publisher OR a trusted delegate of the publisher
  3. Authorized user viewing a curated collection of assertions from one or more CLRs
    • The publisher is the learner
    • May include self-assertions made by the learner
    • Self-assertions are not verifiable

Due to the trust relationship established between a publisher and an issuer, certification does not require verification for the first two use cases, though Consumers and Providers may implement a verification process. CLR verification is required to support the use cases in the third bucket.

  5.4.1 Verification Process

Verifiable Assertions are Assertions with both a Verification object and an Achievement. Verifiable Endorsements are Endorsements with a Verification object. The process of verification MUST include tests to ensure that:

  • Assertions and Endorsements were created by the appropriate issuer Profile according to rules declared in their Verification objects
  • Assertions are awarded to a valid property value of the expected recipient (for example, the Assertion is awarded to a known email address value for email type recipient Identity object)
  • The Assertion issuer is authorized to award Assertions of the declared Achievement type (typically by being the issuer of the Achievement)
  • The Assertion has not expired
  • The Assertion has not been revoked by the issuer

Additional checks MAY ensure that:

  • The issuer Profile awarding the Assertion is trusted to have declared accurate information about its identity (typically via Endorsement)

Issuers SHOULD make every effort to ensure their assertions are verifiable for the entire lifetime of a CLR.

There are two forms of verification supported in the CLR specification:

  • Signed Assertions
  • Hosted Assertions

  5.4.2 Signed Assertion Verification

Issuers can sign their Assertions and consumers can verify signed Assertions without relying on the availability of the issuer’s hosting services. Signed Assertions can be verified long after the Assertion was issued, even if the issuer has ceased operations. Signed Assertions are RECOMMENDED due to their ensured longevity.

A signed Assertion is published in the form of a JSON Web Signature (JWS) [RFC7515]. A JWS has three components separated by dots (.):

header.payload.signature
Figure 1 JWS Format

The complete (all linked data embedded) JSON-LD representation of the Assertion object MUST be used as the JWS payload. The RSA-SHA256 (RS256) signing algorithm MUST be used to sign the JWS.

The CryptographicKey with the public key corresponding to the private key used to sign the Assertion MUST be included in the issuer Profile and SHOULD be publicly accessible via HTTP(S).

  5.4.2.1 Steps to sign an Assertion

Only the issuer of an Assertion may sign the Assertion.

  1. Starting with a fully populated Assertion, serialize the Assertion to a JSON string.
  2. Create a JWS using the JSON string as the payload and the Issuer’s private key.
  5.4.2.2 Steps to verify a signed Assertion
  1. Base64url decode the JWS payload. This will be a JSON string representation of the Assertion.
  2. Parse the decoded JWS payload into an Assertion object. If the parsing operation fails, the Assertion MUST be treated as unverified.
  3. Get the trusted CryptographicKey from the issuer Profile and Assertion’s Verification object using these steps:
    1. Examine the issuer’s CryptographicKey available via the publicKey property of the issuer Profile. If the owner property of the CryptographicKey does not match the issuer Profile id, the CryptographicKey cannot be trusted.
    2. Examine the Assertion’s Verification object available via the verification property of the Assertion. Examine the Verification object’s CryptographicKey identifier available via the creator property. If the identifier is present but does not match the issuer’s CryptographicKey id, the CryptographicKey cannot be trusted.
    3. If the CryptographicKey cannot be trusted, the Assertion MUST be treated an unverified.
  4. Perform an HTTP GET request to the trusted CryptographicKey’s id property. If a CryptographicKey is returned in the response payload, use it as the trusted CryptographicKey. If the request fails, continue using the trusted CryptographicKey embedded in the Assertion object.
  5. Using the public key in the trusted CryptographicKey verify the JWS. If the JWS verification fails, the Assertion MUST be treated as unverified.
  6. Retrieve the revocation list from the issuer Profile if present. If a RevocationList is returned in the response payload, ensure the id of the Assertion does not appear in the RevocationList.
  7. If the above steps pass, the signed Assertion MAY be treated as verified.

Other signature suites may be included in this document later if they are investigated and approved.

  5.4.2.3 Revoking a signed Assertion

To identity an Assertion as revoked, add an entry to the resource pointed at by the Issuer Profile revocationList URL with the id of the Assertion and, optionally, a reason why the Assertion is being revoked.

  5.4.3 Hosted Assertion Verification

A hosted Assertion is a document containing an Assertion object in JSON-LD served with the content-type application/ld+json and/or application/json. This document should be available without requiring authentication to anyone who has the Assertion id (which MUST be a URL). When hosted verification is used, this URL is the source of truth for the Assertion, and any verification attempt will request it to make sure the Assertion exists and describes the expected Achievement. Redirects are permissible as long as appropriate Assertion content is eventually returned. The hosting application must properly set the content-type.

The Assertion id must be within the permitted scope for hosted verification declared in issuer Profile. This defaults to requiring the Assertion and the Achievement be hosted on the same origin as the issuer Profile id if there is no verification property declared in the issuer Profile. For domain origins that host multiple applications and websites, the startsWith path may be used, in which case, the verificationProperty (e.g. id) must start with the value found in the issuer Profile’s Verification object startsWith declaration.

  5.4.3.1 Steps to verify a hosted Assertion

Verification of hosted Assertions may be performed starting with the Assertion URL or with an Assertion instance in hand.

  1. If starting with a full Assertion that indicates Hosted verification, the input data should only be trusted to identify the URL of the hosted Assertion document.
  2. Perform an HTTP(S) GET request to the Assertion URL. If an Assertion is returned in the response payload, it MUST be used it as the trusted Assertion and MAY be treated as verified. If the request fails, the Assertion MUST be treated as unverified.
  5.4.3.2 Revoking hosted Assertions

To mark a hosted Assertion as revoked, hosts SHOULD respond with an HTTP Status of 410 Gone. The response MAY include an Assertion body containing some additional metadata, such as a revocationReason. For revoked Assertions, only id and revoked are required.

If either the 410 Gone status or a response body declaring revoked true is returned, the AssertionRecord SHOULD be treated as revoked and thus unverified.

  5.4.4 Endorsement Verification

Endorsements can also be verified. The process is similar to verifying Assertions.

  5.4.4.1 Steps to sign an Endorsement

Only the issuer of an Endorsement may sign the Endorsement.

  1. Starting with a fully populated Endorsement, serialize the Endorsement to a JSON string.
  2. Create a JWS using the JSON string as the payload and the Issuers private key.
  5.4.4.2 Steps to verify a signed Endorsement
  1. Base64url decode the JWS payload. This will be a JSON string representation of the Endorsement.
  2. Parse the decoded JWS payload into a JSON object. If the parsing operation fails, the Endorsement MUST be treated as unverified.
  3. Perform data validation on the Endorsement, issuer Profile, and any other relevant data present.
  4. Determine the trusted CryptographicKey from the issuer Profile and the Endorsement’s Verification object using these steps:
    1. Examine the issuer’s CryptographicKey available via the publicKey property of the issuer Profile. If the owner property of the CryptographicKey does not match the issuer Profile id, the CryptographicKey cannot be trusted.
    2. Examine the Endorsement’s Verification object available via the verification property of the Endorsement. Examine the Verification object’s CryptographicKey identifier available via the creator property. If the identifier is present but does not match the issuer’s CryptographicKey id, the CryptographicKey cannot be trusted.
    3. If the CryptographicKey cannot be trusted, the Endorsement MUST be treated an unverified.
  5. Perform an HTTP GET request to the trusted CryptographicKey’s id property. If a CryptographicKey is returned in the response payload, use it as the trusted CryptographicKey.
  6. Using the public key in the trusted CryptographicKey, perform a JWS signature verification on the JWS object. If the JWS verification fails, the Endorsement MUST be treated as unverified.
  7. If the above steps pass, the signed Endorsement MAY be treated as verified.
  5.4.4.3 Steps to verify a hosted Endorsement

Verification of hosted Endorsements may be performed starting with the EndorsementURL or with an Endorsement instance in hand.

  1. If starting with an Endorsement that indicates Hosted verification, the input data should only be trusted to identify the URL of the hosted Endorsement document.
  2. Perform an HTTP(S) GET request to the Endorsement URL. If an Endorsement is returned in the response payload, it MUST be used it as the trusted Endorsement and MAY be treated as verified. If the request fails, the Endorsement MUST be treated as unverified.

  5.4.5 Optional Data Validation

Certification is the process for ensuring Consumers and Providers conform to the requirements of the CLR specification. Certification ensures they are capable of exchanging CLR data with fidelity. Certification includes a number of data validation checks.

The certification process includes data validation to ensure all the objects within a CLR payload conform to the requirements for its class:

  • Each object in the CLR payload is a valid JSON-LD document
  • Each object conforms to the JSON Schema defined by the CLR specification, including:
    • Each object contains all required properties for its class
    • Each object contains values of the expected data type for all declared properties

Consumers MAY validate the CLR data they received from a certified Provider, but this is not required.

  5.5 Rendering CLR as Structured Data HTML Documents

  6. About this Document

  A. Revision History

This section is non-normative.

  A.1 Version History

Version No. Release Date Comments
Version 1.0 August 26, 2019 The first release.

  B. References

  B.1 Normative references

[CLR-CONF-10]
IMS Comprehensive Learner Record (CLR) Conformance and Certification Guide Version 1.0. IMS Global. August 26, 2019. IMS Candidate Final. URL: clr-conf_v1p0.html
[CLR-IMPL-10]
IMS Comprehensive Learner Record (CLR) Implementation Guide 1.0. IMS Global. August 26, 2019. IMS Candidate Final. URL: clr-impl_v1p0.html
[CLR-INFO-10]
IMS Comprehensive Learner Record (CLR) Information Model Version 1.0. IMS Global. August 26, 2019. IMS Candidate Final. URL: imsclr_v1p0_InfoModel.html
[CLR-JSON-10]
IMS Comprehensive Learner Record (CLR) JSON Schema. IMS Global. August 26, 2019. IMS Candidate Final. URL: https://purl.imsglobal.org/spec/clr/v1p0/schema/json/
[CLR-OPENAPI-10]
IMS Comprehensive Learner Profile (CLR) OpenAPI 3.0. IMS Global. August 26, 2019. IMS Candidate Final. URL: https://purl.imsglobal.org/spec/clr/v1p0/schema/openapi/
[CLR-REST-10]
IMS Comprehensive Learner Record (CLR) REST/JSON Binding Version 1.0. IMS Global. August 26, 2019. IMS Candidate Final. URL: imsclr_v1p0_RESTBind.html
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515

  C. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Tamer AbuelsaadIBM
Jeff BohrerIMS Global
Sherri BraxtonUniversity of Maryland, Baltimore County
Deb EverhartLearning Objects
Steve GraceWA Comm & Tech Colleges
Matthew HailstoneBrigham Young University
Chris HoustonCapella UniversityAuthor
Alex HripakCredly
Mark LeubaIMS Global
Jeff McNealState of Michigan Department of Education
Andy MillerIMS Global
Greg NadeauPublic Consulting GroupAuthor
Nate OttoConcentric Sky
Ozgur YogurtcuAEFIS

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: Comprehensive Learner Record Implementation Guide 1.0

Date: August 26, 2019