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: February 7, 2020
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/clr/v1p0/

IPR and Distribution Notice

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.

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.

© 2020 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 Comprehensive Learner Record (CLR) specification supports interoperability in that CLR publishers and consumers can consistently send, receive, and verify records among conformant systems. 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, co-curricular activities, Open Badges, 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 and competencies that was not previously possible.

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 Implementations for a CLR Client Application, a Resource Server, and an Authentication Server.
  • 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-CERT-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 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 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-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.
Consumer
A REST API actor that makes requests to CLR endpoints on a Provider.
Evidence
Information supporting the issuance of an assertion such as URL to an artifact produced by the Learner.
Inspector
A Consumer that inspects a CLR to verify or validate the data.
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.
Protected Information
In the United States, the Family Educational Rights and Privacy Act (FERPA) is a Federal Law that protects personally identifiable information (PII) from students' educational records from unauthorized disclosure. CLRs fall within the definition of educational records; and the CLR Learner Profile contains PII. Therefore FERPA may apply to some uses of the CLR spec.
Provider
A REST API actor that responds to requests to CLR endpoints from a Consumer.
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. Getting Started

2.1 Audience

This guide is for technical professionals who work with educational data, including business analysts, database administrators, and software developers. The primary audience is developers of CLR platforms, but developers of client applications may find this information useful.

2.2 How to Create a CLR

This section describes how to use the CLR data model in several different scenarios. The examples are truncated to show just enough information to represent the concept. Please refer to IMS Comprehensive Learner Record (CLR) Specification Version 1.0 for detailed data model requirements.

2.2.1 As a publisher I want to publish a "complete" or "whole" CLR

A complete or whole Comprehensive Learning Record (CLR) must contain all the achievement assertions known by the publisher for the learner at the time the CLR is issued. The publisher must include their own publisher profile, the learner profile, all the assertions, the issuedOn timestamp, and partial must be false or ommitted. If an assertion does not appear in a later CLR from the same publisher and for the same leaner, the consumer can assume the assertion has been revoked.

2.2.2 As a learner I want to self-publish a custom CLR

Learners may want to send a custom CLR to a potential employer or others. In this case the publisher and learner profiles should be the same. The assertions may come from different issuers and the recipient may be identified with different identity values. A self-published CLR may not contain all of the leaner's assertions even if partial is false or omitted. Consumers should assume a CLR is self-published if the learner profile has the same id as the publisher profile id.

2.2.3 As a learner I want to self-issue an Assertion

Learners may want to include a custom assertion in their custom CLR. In this case the assertion issuer and learner profiles should be the same. Consumers should assume an assertion is self-issued if the learner profile has the same id as the issuer profile id.

2.2.4 As an issuer I want to issue a single achievement assertion

Either IMS Comprehensive Learner Record (CLR) Specification Version 1.0 or Open Badges Specification v2.1 can be used to send a single achievement assertion from one system to another. If the system receiving the assertion primarily processes CLRs, the sender should use a CLR operation to send a single achievement assertion with partial set to true. When partial is true, receivers of the CLR cannot determine if previous assertions have been revoked.

2.2.5 As an issuer I want to assert an achievement and override the achievement issuer

In some organizational hierarchies, achievements may be issued by one organization within the hierarchy but asserted by a different organization within the hierarchy. For example, a school district may be the official issuer of achievements, but schools within the district are responsible for issuing the assertion of the achievement. In this scenario, the assertion should include the issuer profile of the organization making the assertion, and the achievement should include the issuer profile of the organization that officially issues the achievement.

2.2.6 As an issuer I want to make an assertion with evidence and without an achievement

An issuer may want to include evidence in a CLR without linking it to a specific achievement. In this case the assertion should include the issuer profile, and the evidence should include the artifacts that constitute the evidence.

2.2.7 As an issuer I want to assert the achievement of one or more compentencies without alignment to a competency framework

If you wish to assert a level of mastery, the achievement resultDescriptions should contain a description for each level.

The assertion results should contain the level of mastery achieved.

The criteria for achievement each level of mastery can be described in the Achievement requirement. The reason why a particular result was achieved can be described in the Assertion narrative. And the evidence used in determining a particular result can be cited in the Assertion evidence.

2.2.8 As an issuer I want to assert the achievement of one competency defined in a competency framework

If the achievement represents exactly one compentency in a competency framework, and the fetched framework competency data meets the CLR validation requirements in addition to the competency framework requirements, then the CLR achievement id can be set to the framework competency id. If the framework competency data does not meet the validation requirements, then an alignment to the framework competency should be added to the CLR achievement.

Competencies and Academic Standards Exchange (CASE) Service Version 1.0 CFItems do not meet the validation requirements for a CLR achievement, therefore an achievement that represents a CASE CFItem must have an alignment to the CFItem.

2.2.9 As an issuer I want to assert achievements of one or more competencies defined in a CASE framework

When the achievement description represents one or more CASE compentencies or academic standards, the achievement should contain one or more alignments. Each alignment should have a type of CFItem and targetUrl should should be the uri of the CFItem.

To interpret the meaning of the competency statement, services should GET the CFItem document using the targetUrl.

2.2.10 As an issuer I want to assert achievements of one or more criterion levels from a CASE Rubric

If the learner has made an achievement corresponding to a specific criterion level of a CASE Rubric, the assertion results should contain a "RubricScore" result with an alignment to the CFRubricCriterionLevel and a value of the CFRubricCriterionLevel score. And the achievement resultDescriptions should contain an alignment to the CASE Rubric.

2.2.11 As a publisher I want to associate achievements in the CLR

CLR Achievements can be associated with each other to represent relationships within a CLR and relationships between the achievements asserted in the CLR and achievements within a larger curriculum. An Association describes a relationship between a source Achievement and a target Achievement. Some association types, for example exactMatchOf and isRelatedTo, are transitive and represent the same meaning regardless of source or target. Some association types have an implicit reverse association when the source and target are switched; two such examples include A isChildOf B having an implicit “B isParentOf A” and A is replacedBy B having an implicit “B replaces A”. CLR does not explicitly specify these reverse associations -- the interpretation and use of these are at the discretion of the implementation.

The source and target of any association does not need to be part of the CLR.

As noted in the CFItem example, achievements can be aligned to CFItems which can also be associated to other CFItems. Publishers and issuers may use CLR Associations and/or CASE Associations to describe the relationships between achievements in a CLR. CLR Associations only associate CLR Achievements. CASE Associations only associate CASE Documents.

2.3 How to use the API

This section describes how to use the CLR API in several different scenarios.

2.3.1 As a consumer system I want to get all the CLRs I'm authorized to access from a provider system

A Consumer organization's system reads (GETs) one or more learners' Comprehensive Learner Records from an Provider organization's system. This use case supports systems interoperability uses such as transferring CLR data from one system to another. It can also be used to get data to populate collections or repositories of Comprehensive Learner Records.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System; and Authorization Server.

Preconditions: The Consumer knows the Provider's 'getClrs' endpoint URL. The Consumer has an authorization code or client credentials which can be used to request an access token that grants access to the CLRs on the Provider system.

Primary Flow:

  1. Consumer system/service requests an access token from the Authorization Server.
  2. The Authorization Server responds with the access token.
  3. Consumer system/service initiates a GET request to the Provider's system/service 'getClrs' endpoint, passing the access token as a bearer token in the Authorization header.
  4. Compliant ClrSet payload will be generated by Provider based on the access granted by the access token.
  5. Provider responds HTTP status 200 OK with the payload to the Consumer.
  6. Consumer receives the CLR payload.
  7. Consumer processes the payload successfully.

Alternate Flows:

  • Consumer system includes the since query parameter in the GET request.
    • Provider responds with a ClrSet payload that contains CLRs that were issued after the provided timestamp.
  • Consumer sends a malformed request
    • Provider responds with HTTP status 400 Bad Request and an imsx_StatusInfo payload with the exact error.
  • Consumer is not authenticated
    • Provider responds with HTTP status 401 Unauthorized and an unauthorized payload using the imsx_StatusInfo object.
  • Consumer is not authorized
    • Provider responds with HTTP status 403 Forbidden and an unauthorized payload using the imsx_StatusInfo object.
  • CLRs not found
    • Provider responds with HTTP status 404 Not Found and an imsx_StatusInfo object with the exact error.

2.3.2 As a consumer system I want to post a single CLR to a provider system

A Consumer organization's system sends (POSTs) a Comprehensive Learner Record to an Provider organization's system. This use case supports systems interoperability uses such as transferring CLR data from one system to another. It can also be used to create or update a Comprehensive Learner Record on the Provider.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System; and Authorization Server.

Preconditions: The Consumer knows the Provider's 'postClr' endpoint URL. The Consumer has an authorization code or client credentials which can be used to request an access token that grants the appropriate access to the CLR on the Provider system.

Primary Flow:

  1. Consumer system/service requests an access token from the Authorization Server.
  2. The Authorization Server responds with the access token.
  3. Consumer creates the POST request payload consisting of the CLR to create or update on Provider.
  4. Consumer system/service initiates a POST request to the Provider's system/service 'postClr' endpoint, passing the payload in the body of the request, and the access token as a bearer token in the Authorization header.
  5. Provider creates or updates the CLR and create the response payload consisting of the CLR that was created or updated.
  6. Provider responds HTTP status 200 OK if the CLR was updated/replaced or 201 Created if the CLR was created and the payload to the Consumer.
  7. Consumer receives the CLR payload.
  8. Consumer processes the payload successfully.

Alternate Flows:

  • Consumer sends a CLR that already exists and exactly matches the CLR on the Provider system.
    • Provider responds with HTTP status 304 Not Modified and no payload.
  • Consumer sends a malformed request
    • Provider responds with HTTP status 400 Bad Request and an imsx_StatusInfo payload with the exact error.
  • Consumer is not authenticated
    • Provider responds with HTTP status 401 Unauthorized and an unauthorized payload using the imsx_StatusInfo object.
  • Consumer is not authorized
    • Provider responds with HTTP status 403 Forbidden and an unauthorized payload using the imsx_StatusInfo object.
  • CLR not found
    • Provider responds with HTTP status 404 Not Found and an imsx_StatusInfo object with the exact error.

2.3.3 As a consumer system I want to delete a single CLR from a provider system

A Consumer organization's system DELETEs a Comprehensive Learner Record to an Provider organization's system.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System; and Authorization Server.

Preconditions: The Consumer knows the Provider's 'deleteClr' endpoint URL and the id of the CLR to be deleted. The Consumer has an authorization code or client credentials which can be used to request an access token that grants the appropriate access to the CLR on the Provider system.

Primary Flow:

  1. Consumer system/service requests an access token from the Authorization Server.
  2. The Authorization Server responds with the access token.
  3. Consumer system/service initiates a DELETE request to the Provider's system/service 'deleteClr' endpoint, passing the access token as a bearer token in the Authorization header.
  4. Provider deletes the CLR.
  5. Provider responds HTTP status 204 No Content to the Consumer.

Alternate Flows:

  • Consumer sends a malformed request
    • Provider responds with HTTP status 400 Bad Request and an imsx_StatusInfo payload with the exact error.
  • Consumer is not authenticated
    • Provider responds with HTTP status 401 Unauthorized and an unauthorized payload using the imsx_StatusInfo object.
  • Consumer is not authorized
    • Provider responds with HTTP status 403 Forbidden and an unauthorized payload using the imsx_StatusInfo object.
  • CLR not found
    • Provider responds with HTTP status 404 Not Found and an imsx_StatusInfo object with the exact error.

2.3.4 As an inspector I want to get a single CLR

A Consumer organization or system reads (GETs) a specific Comprehensive Learner Record from a Provider system. This use case supports hosted verification of a CLR and/or determines if the CLR has been revoked.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System.

Preconditions: Consumer has the id of a CLR and the id is the URL to the Provider's 'getClr' endpoint that returns the CLR.

Primary Flow:

  1. Consumer system/service will initiate a call to the Provider's system/service for a specific CLR.
  2. Compliant CLR payload will be generated by Provider based on a lookup of the unique identifier of the CLR.
  3. Provider responds HTTP status 200 OK with the payload to the Consumer.
  4. Consumer receives the CLR payload.
  5. Consumer processes the payload successfully.

Alternate Flows

  • The CLR does not exist
    • Provider responds HTTP status 404 Not Found.

2.3.5 As an inspector I want to get a single assertion

A Consumer organization or system reads (GETs) a specific Assertion from a Provider system. This use case supports hosted verification of an Assertion and/or determines if the Assertion has been revoked.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System.

Preconditions: Consumer has the id of an Assertion and the id is the URL to the Provider's 'getAssertion' endpoint that returns the Assertion.

Primary Flow:

  1. Consumer system/service will initiate a call to the Provider's system/service for a specific Assertion.
  2. Compliant Assertion payload will be generated by Provider based on a lookup of the unique identifier of the Assertion.
  3. Provider responds HTTP status 200 OK with the payload to the Consumer.
  4. Consumer receives the Assertion payload.
  5. Consumer processes the payload successfully.

Alternate Flows

  • The Assertion does not exist
    • Provider responds HTTP status 404 Not Found.

2.3.6 As an inspector I want to get a single endorsement

A Consumer organization or system reads (GETs) a specific Endorsement from a Provider system. This use case supports hosted verification of an Endorsement and/or determines if the Endorsement has been revoked.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System.

Preconditions: Consumer has the id of an Endorsement and the id is the URL to the Provider's 'getEndorsement' endpoint that returns the Endorsement.

Primary Flow:

  1. Consumer system/service will initiate a call to the Provider's system/service for a specific Endorsement.
  2. Compliant Endorsement payload will be generated by Provider based on a lookup of the unique identifier of the Endorsement.
  3. Provider responds HTTP status 200 OK with the payload to the Consumer.
  4. Consumer receives the Endorsement payload.
  5. Consumer processes the payload successfully.

Alternate Flows

  • The Endorsement does not exist
    • Provider responds HTTP status 404 Not Found.

2.3.7 As an inspector I want to get an issuer's public key

A Consumer organization or system reads (GETs) a specific CryptographicKey from a Provider system. This use case supports signed verification of CLRs, Assertions, and Endorsements.

Actors: CLR Provider and CLR Consumer Institution, Vendor, Student Information System (SIS), Learning Management System (LMS), Employer, Organization, CLR Renderer, or Internal System.

Preconditions: Consumer has the id of a CryptographicKey and the id is the URL to the Provider's 'getKey' endpoint that returns the CryptographicKey.

Primary Flow:

  1. Consumer system/service will initiate a call to the Provider's system/service for a specific CryptographicKey.
  2. Compliant CryptographicKey payload will be generated by Provider based on a lookup of the unique identifier of the CryptographicKey.
  3. Provider responds HTTP status 200 OK with the payload to the Consumer.
  4. Consumer receives the CryptographicKey payload.
  5. Consumer processes the payload successfully.

Alternate Flows

  • The CryptographicKey does not exist
    • Provider responds HTTP status 404 Not Found.

3. Best Practices

3.1 Institutional Context

The Comprehensive Learner Record is a new concept for learners, faculty, and administrators; but all of these groups have a role in creating the CLR in a way that supports the mission of a particular institution or organization. An institutional or organizational team is recommended to appropriately plan for, implement, and assess the CLR.

  • Foundations: Critical Questions
    • Define the CLR for your institution and stakeholder groups. Ask: What does the CLR mean to you? What information do you want to include? How do you expect learners to use this information? How does this type of document fit into your organizational mission and brand?
    • Where is the information you hope to represent on the CLR currently located (system, paper, not recorded anywhere)? What data is available in an accessible format and what data is not? For data that is not accessible, what needs to happen to get the data in a format that will allow you to create a CLR?
    • What kind of record do you need to provide? PDF, digital, paper, or all of these?
    • Do you need to conduct a pilot first, or do you plan to implement directly across the entire institution?
    • Will you engage employers as part of the process?
    • Which institutional policies will be impacted in the decision to move forward, and who will shepherd them through changes and approval processes?
    • How can the document be secured in terms of data integrity and security?
  • Foundations: Planning
    • Identify the stakeholders and "champions" that need to be involved in the planning and implementation phases from an administrative, academic, and technological perspective.
    • Develop a project plan, including milestones, timeline for deliverables, and ownership accountability.
    • Clearly define responsibilities of the project team.
    • Identify a go live date.
    • Determine what support and technology can be built in-house and what might require vendor support.
    • What is your communication plan? How will you socialize and explain this document to those outside of the project?
    • Determine how you will assess the CLR, collect feedback, and evaluate how is it being used, including determining what tools to use in this part of the process.
  • Implementation:
    • Create a plan to test integration, user experience, and the CLR documents themselves.
    • Create feedback loops to ensure project team is connected and aware of changes or delays.
    • Finalize look and feel of the document.
    • Create a marketing plan to be clear on the communications that will be received by learners, faculty, and staff.
    • Determine how will you collect data.
    • Define a plan for continuous process improvement based on assessment, feedback, and industry trends and developing practices.
    • Put together a plan of how to resolve an technology or content related issues once the document is live.
  • Evaluation and Assessment of the CLR:
    • How should an individual's CLR be managed and updated over time? The CLR is meant to be a dynamic document reflecting the most current and correct information as of its production. There should be a date on the CLR that reflects the date it was produced.
    • Identify how changes should be handled – it is recommended changes happen in the source systems as the CLR is designed to be produced dynamically with real time data.
    • Identify revocation practices as needed.
    • Analyze results and implement a continuous improvement model for the CLR that embraces the changing educational experiences of learners.

3.2 Security and Privacy

All conformant Comprehensive Learner Record provider services are secured using OAuth 2.0 Bearer Token authorization [RFC6749], and conformant Comprehensive Learner Record consumers must also support bearer token authorization. Additionally, some providers and consumers may support additional authorization mechanisms.

In general, for any consumer that is authorized to access any Comprehensive Learner Record(s), the Comprehensive Learner Record service should provide all relevant data that the authorized party should have access to, accounting for data availability and performance considerations. However, in the event that a provider wishes to provide varying degrees of access to various entities, or that the provider does not wish to disclose other details out of privacy concerns, the provider may intentionally omit data from the Comprehensive Learner Record.

3.2.1 Dynamic Client Registration of a Consumer Application

Dynamic client registration [RFC7591] and the Authorization Code Flow [RFC6749] is required when the learner is involved in the decision of what (if anything) can be shared between the Provider and Consumer applications. The beauty of the dynamic client registration piece is that there does not need to be a pre-established relationship (shared secrets) between the Provider and Consumer applications that take part in this interaction. Please refer to the REST Binding document for details.

  1. A learner is on an application that is a CLR consumer.
  2. They are offered the chance to bring their CLR into the consumer application.
  3. They identify their provider server domain, and they are directed to the provider server to authorize.
  4. They get to the provider server and authenticate.
  5. They see a permission grant request to grant permission to the CLR consumer application.
  6. They grant permission and are redirected back to the CLR consumer application.
  7. The consumer application then has the capability to pull CLRs for that learner from the provider.

3.2.2 Out-of-Band Registration of a Consumer Application

Dynamic client registration is not required for system-to-system transfer (i.e. when the learner is not involved in the transaction). In this case, the two systems must use Client Credentials [RFC6749] and may use dynamic client registration or manually exchange client credentials out-of-band. Please refer to the REST Binding document for details.

3.2.3 Protecting Personally Identifiable Information

In the United States, students' personally identifiable information is protected from unauthorized disclosure by the Family Educational Rights and Privacy Act (FERPA). While the Federal Law applies to schools that receive federal funding, it is also a best practice. CLRs are educational records that contain a student's PII in the Learner Profile. Therefore all CLR REST operations that deal with a whole CLR must implement OAuth Authorization ([CLR-CERT-10]).

A CLR Assertion may contain PII in the recipient field, and the getAssertion operation does not require authorization. Therefore, organizations that are impacted by FERPA should not use PII to identify the recipient. As a best practice, use a UUID to identify the recipient that is not the student's email, sourcedId, or studentId in any other source of educational records. This will prevent an unauthorization person with access to the Assertion, but without access to the CLR, from linking the Assertion to a student.

3.3 Trust Model

The current relationship between the issuer/publisher, the learner, and the inspector/verifier depends on somewhat blind trust. The CLR 1.0 model does not explicitly provide proof that people and organizations are who they say they are. For example there is no solution yet for these two use cases:

  • As an inspector of a CLR, I have obtained a CLR from Publisher A which claims its profile to have a name "BigCorp, Inc.". I know that BigCorp, Inc is a well-known company with a corporate office in New York. I want to verify that the CLR I am viewing that claims to be published by this organization is actually the word of this organization.
  • As an inspector of a CLR, I have obtained a CLR from Publisher A with an achievement record "BigSchool". I know that BigSchool is a well-known institution of higher education in California. I want to verify that the achievement record I am viewing that is claimed by the publisher to be issued by this organization is actually the word of this organization.

Future versions of the CLR specification will address this issue.

3.4 Learner Control of Shared Information (@@@TBD)

3.5 Linked Data (JSON-LD)

The CLR specification uses JSON-LD 1.0, which is a standard for creating linked data on the web. This enables anyone interested in linked data to understand common entities across standards and data sources.

JSON-LD enables transformations of the data, such as normalizing the exchanged data between various sources. This is a capability of JSON-LD and associated tools and is not specific to the Comprehensive Learner Record standard.

Although the CLR specification provides these linked data capabilities, most consumers and providers are likely to treat the data the same way they would treat any JSON data; they do not need to do anything special in order to accommodate the linked data.

The CLR specification also uses the OpenAPI Specification to describe the API. OpenAPI uses an extended subset of JSON Schema: core definitions and terminology to describe data formats. Some keywords are supported with minor differences. One of those differences leads to two constraints on JSON-LD within the CLR specification:

Difference

type – the value must be a single type and not an array of types.

Constraints

  1. Arrays with one element cannot be collapsed to a JSON value type

  2. JSON objects cannot be collapsed to just the @id

3.6 Additional Properties

Providers may extend many entities within the data model by simply adding properties. No special prefixing or naming convention is required. The only requirement is that providers do not override standard properties.

Additionally, a provider may provide a JSON-LD context containing definitions of the extensions; in this case, the provider must specify the standard context definition, and additionally list any custom JSON-LD extensions.

3.7 Verification

Verification is the process to ensure the CLR as a whole, and 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.

3.7.1 Verification Process

The verification process is implemented by the Consumer application. Although verification is not required, it is highly recommended for applications with a user facing interface. The user or machine requesting verification is called an inspector. Clrs, Assertions, and Endorsements are all verifiable if they include a Verification object. The process of verification includes tests to ensure that:

  • Clrs, Assertions and Endorsements were created by the appropriate issuer/publisher 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, Clr, or Endorsement has not been revoked by the issuer
  • The Assertion, Clr, or Endorsement either has not been changed since it was issued (signed verification) or the issuer can issue a copy of the entity during verification (hosted verification)
  • 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

Additional checks may ensure that:

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

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

  • Signed
  • Hosted

3.7.2 Signed Verification

Issuers can sign an Assertion, Endorsement, or the Clr as a whole, and consumers can verify signed entities without relying on the availability of the issuer's hosting services. Signed entities can be verified long after they are issued, even if the issuer has ceased operations. Therefore, signed verification is RECOMMENDED due to its ensured longevity.

A signed entity is published as a Compact JSON Web Signature (JWS) [RFC7515]. A Compact JWS has three components separated by dots (.):

The complete JSON representation of the entity 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 entity must be included in the issuer Profile and should be publicly accessible via HTTP(S).

Steps to sign an entity

  1. Starting with a fully populated entity, serialize the entity to a JSON string.
  2. Create a Compact JWS as described in [RFC7515] using the JSON string as the payload and the issuer's private key.
Steps to verify a signed entity
  1. Base64url decode the JWS payload. This will be a JSON string representation of the entity.
  2. Parse the decoded JWS payload into the appropriate object type (Assertion, Endorsement, or Clr). If the parsing operation fails, the entity must be treated as unverified.
  3. Get the trusted CryptographicKey from the issuer Profile and entity'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 entity's Verification object available via the verification property of the entity. Then 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 entity 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 entity.
  5. Using the publicKey in the trusted CryptographicKey verify the JWS. If the JWS verification fails, the entity must be treated as unverified.
  6. Retrieve the issuer's RevocationList from revocationList URL in issuer Profile if present. If a RevocationList is returned in the response payload, and the id appears in the RevocationList, the entity must be treated as unverified.
  7. If the above steps pass, the signed entity may be treated as verified.
Revoking a signed entity

To identify an entity as revoked, add an entry to the resource pointed at by the issuer's Profile revocationList URL with the id of the entity and, optionally, a reason why the entity is being revoked.

3.7.3 Hosted Verification

Hosted verification requires the entity be hosted at a URL as a document in JSON-LD format 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 entity id (which must be a URL). When hosted verification is used, this URL is the source of truth for the entity, and any verification attempt will request it to make sure the entity exists and describes the expected entity. Redirects are permissible as long as the appropriate content is eventually returned. The hosting application must properly set the content-type.

The entity id must be within the permitted scope for hosted verification declared in issuer Profile. This defaults to requiring the entity be hosted on the same origin as the issuer Profile id if there is no verification property declared in the issuer Profile. For Assertions this rule extends to the Assertion's Achievement. 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.

Steps to verify a hosted entity

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

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

To mark a hosted entity as revoked, hosts should respond with an HTTP Status of 410 Gone. The response may include an entity body containing some additional metadata, such as a revocationReason.

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

3.7.4 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.

4. CLR in the IMS Ecosystem

4.1 CASE - Competency and Academic Standards Exchange

4.1.1 When to use CLR Associations versus CASE CFAssociations

CLR Achievements can be associated by including CLR Associations in the CLR. CASE CFItems can be associated by including CFItemAssociations in the framework. Because CLR Achievements can be Aligned with CASE CFItems, there are two ways to associate CLR Achievements:

  1. Define the associations using CLR Associations
  2. Define the associations by aligning the achievements with CFItems and then using the CFItemAssociations to mean the achievements are also aligned

Use #2 if the CLR Achievement and CFItem are strongly aligned (i.e. have the same meaning) and the CFItem is already associated with other CFItems in the CASE framework. Otherwise use #1 and define the associations in the CLR.

4.2 Learner Information Services (LIS) and OneRoster

  • The Comprehensive Learner Record uses a flattened version of the LIS Person model, similar to OneRoster and LTI, and can be joined by sourcedId.
  • The Issuer can map to an organization within an IMS specification by way of the sourcedId.

4.3 Open Badges

An Open Badges v2.0 (OB) badge is composed of an OB Assertion and an OB BadgeClass. The OB Assertion class is similar to the CLR Assertion class and they share many of the same properties with the same meaning. Likewise, the OB BadgeClass is similar to the CLR Achievement class and they also share many of the same properties with the same meaning. Two common use cases for using Open Badges and CLR together are described below.

4.3.1 As an OB Host and CLR Publisher I want to publish a collection of badges as a CLR

As an OB Host you have collected several badges for a recipient, and now you want to publish a collection of their badges as a CLR. This can be done in two ways: convert the badges to CLR Assertions or create CLR Assertions that link to the badges.

Convert the badges to CLR Assertions

  1. Start with a blank Clr.
  2. Add a learner CLR Profile based on the badge's recipient OB Profile.
  3. Add a publisher CLR Profile to represent the organization issuing the CLR.
  4. Add a CLR Assertion based on each badge's OB Assertion.
    1. Add a CLR Achievement based on the badge's OB BadgeClass.
    2. Set achievementType property to "Badge".
  5. Set issuedOn to the timestamp of when the CLR is issued.
  6. Publish the CLR.

Include the badges without conversion

  1. Start with a blank Clr.
  2. Link to the Open Badge context "https://w3id.org/openbadges/v2".
    {
      "@context": [
        "https://purl.imsglobal.org/spec/clr/v1p0/context",
        "https://w3id.org/openbadges/v2"
      ]
    }
    
  3. Add a learner CLR Profile based on the badge's recipient OB Profile.
  4. Add a publisher CLR Profile to represent the organization issuing the CLR.
  5. Add a CLR Assertion for each badge's OB Assertion.
    1. Use the badge id.
    2. Add the "obi:Assertion" type.
      "type": ["Assertion", "obi:Assertion"]
    3. Add the badge properties using compact IRIs.
      "obi:BadgeClass": { ... }
  6. Set issuedOn to the timestamp of when the CLR is issued.
  7. Publish the CLR.

Link to the badges

  1. Start with a blank Clr.
  2. Add a learner CLR Profile based on the badge's recipient OB Profile.
  3. Add a publisher CLR Profile to represent the organization issuing the CLR.
  4. Add a CLR Assertion based on each badge's OB Assertion.
    1. Add a CLR Artifact that links to the badge. Artifacts are added to the Assertion's evidence property.
  5. Set issuedOn to the timestamp of when the CLR is issued.
  6. Publish the CLR.

4.3.2 As a CLR Achievement Issuer I want to issue an Open Badge

As a CLR issuer you can issue CLR assertions, and now you also want to issue an OB badge.

  1. Create an OB BadgeClass based on the CLR Achievement.
  2. Create an OB Assertion based on the CLR Assertion.
  3. Set the OB Assertion badge property to the OB BadgeClass defined above.
  4. Issue the badge.

5. Common Questions and Answers on CLR

Question Answer
Who validates the CLR and its contents? The CLR and the Assertions and Endorsements it contains should be secure and verified by the issuing organization. For CLRs the publisher is the issuer. For Assertions and Endorsements, the issuer is the issuer.
What data should go on the CLR, and is there a need for a process of petition to add things to a CLR? In general, the organization or institution determines the content of a CLR. If there is a desire to allow learners to petition to add content, clear guidelines should be created that address what kind of content can be added, where the data and content originates, and how it will be noted (verified/not verified) on the CLR.
Who are the typical stakeholders for a CLR? Student Affairs, Registrar, SEM, and/or Academic Affairs. Involved should be all enrollment management functionalities, financial aid, marketing, academic affairs, Registrar Office, Student Services, Career Services, Residential Life, Co-Curricular bodies.
Should we charge for a CLR? This decision is individualized. The business model will need to be examined. The choice of whether to create a transactional model (where the learner requests the Comprehensive Learner Record and it is produced on a "per request" basis) or a model where the Comprehensive Learner Record is "pushed" to learners and they own the Comprehensive Learner Record and can use it as they see fit will be determined by many factors including revenue gain/loss, policies and practices, data systems and scalability.
Are there any things we should not put on a CLR? The institution should determine whether achievements which reflect personal information that may be sensitive to a learner should provide an option to include or not to include on a request.
Do we want to distribute the CLR in addition to the official transcript? The CLR can be created to include what is on the official transcript, or distributed along with the official transcript which is still the known, verified document among institutions of higher education and employers.
Where should the CLR be housed? Where will learners access the CLR? There are many places such as the digital classroom or through career service portals, but each institution will have to decide this based on what the CLR represents.
Who will manage questions about the CLR once it is live? Learners and others who have access to the CLR may have various questions once they see the document. Establishing FAQ's to be shared with those who interact with learners and also making known one or more point of contacts that can speak fluently about the CLR can be beneficial.

6. About this Document

A. Revision History

This section is non-normative.

A.1 Version History

Version No. Release Date Comments
Version 1.0 DRAFT February 3, 2020 The second draft.
Version 1.0 DRAFT August 26, 2019 The first draft.

B. References

B.1 Normative references

[CASE-10]
Competencies and Academic Standards Exchange (CASE) Service Version 1.0. IMS Global Learning Consortium. July 2017. IMS Final Release. URL: https://www.imsglobal.org/activity/case/
[CLR-10]
IMS Comprehensive Learner Record (CLR) Specification Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://www.imsglobal.org/spec/clr/v1p0/
[CLR-CERT-10]
IMS Comprehensive Learner Record (CLR) Conformance and Certification Guide Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://www.imsglobal.org/spec/clr/v1p0/cert/
[CLR-IMPL-10]
IMS Comprehensive Learner Record (CLR) Implementation Guide Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://www.imsglobal.org/spec/clr/v1p0/impl/
[CLR-INFO-10]
IMS Comprehensive Learner Record (CLR) Information Model Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://www.imsglobal.org/spec/clr/v1p0/InfoModel/clr_InfoModel.html
[CLR-JSON-10]
IMS Comprehensive Learner Record (CLR) JSON Schema Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://purl.imsglobal.org/spec/clr/v1p0/schema/json/
[CLR-JSONLD-10]
IMS Comprehensive Learner Record (CLR) JSON-LD Context Version 1.0. IMS Global. February 7, 2020. IMS Candidate Final. URL: https://purl.imsglobal.org/spec/clr/v1p0/context/
[CLR-OPEN-10]
IMS Comprehensive Learner Record (CLR) OpenAPI Schema Version 1.0. IMS Global. February 7, 2020. 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. February 7, 2020. IMS Candidate Final. URL: https://www.imsglobal.org/spec/clr/v1p0/RESTBinding/clr_RESTBind.html
[JSON-LD]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[JSON-Schema]
JSON Schema: core definitions and terminology. K. Zyp. Internet Engineering Task Force (IETF). 31 January 2013. Internet-Draft. URL: https://tools.ietf.org/html/draft-zyp-json-schema
[OB-20]
Open Badges v2.0. Otto, Nate; Bohrer, Jeff; Cook, Timothy; Gylling, Markus; Hripak, Alexander; Pitcher, Justin. IMS Global Learning Consortium. April 2018. IMS Final Release. URL: https://www.imsglobal.org/spec/ob/v2p0/
[OB-21]
Open Badges Specification v2.1. Jeff Bohrer; Andy Miller. IMS Global. August 29, 2019. URL: https://www.imsglobal.com/spec/ob/v2p1/
[OpenAPI]
OpenAPI Specification. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. URL: https://www.openapis.org/
[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
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6749
[rfc6750]
The OAuth 2.0 Authorization Framework: Bearer Token Usage. M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6750
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515
[RFC7591]
OAuth 2.0 Dynamic Client Registration Protocol. J. Richer, Ed.; M. Jones; J. Bradley; M. Machulak; P. Hunt. IETF. July 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7591

B.2 Informative references

[CASE-IMPL-10]
IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0: Best Practices and Implementation Guide. IMS Global. July 7, 2017. IMS Final Release. URL: https://www.imsglobal.org/sites/default/files/CASE/casev1p0/best_practices/caseservicev1p0_bestpracticesv1p0.html
[LIS-20]
IMS Global Learning Information Services v2.0. L. Feng; W. Lee; C. Smythe. IMS Global Learning Consortium. June 2011. URL: https://www.imsglobal.org/lis/

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 UniversityCo-Chair
Alex HripakCredly
Mark LeubaIMS Global
Jeff McNealState of Michigan Department of Education
Andy MillerIMS Global
Greg NadeauPublic Consulting GroupCo-Chair
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: February 7, 2020