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

By default, the receiver of a CLR can assume the publisher included all the achievement assertions for the learner that the receiver is allowed to see. The publisher must include their own publisher profile, the learner profile, the assertions, and the issuedOn timestamp. If the publisher includes the partial property, it should be false. If an assertion does not appear in a later CLR from the same publisher and for the same leaner, and partial is omitted or false, the receiver can assume the assertion has been revoked.

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

Each assertion within a CLR can be independently verified. That means a new CLR can be formed which includes verifiable achievements from other CLRs. For example, a Learner may want to send a custom CLR to a potential employer that only includes achievements relevant to the job.

A self-published CLR is one where both the publisher id and learner idare the same. The assertions may come from different issuers and the recipient may be identified with different identity values. Consumers should assume a CLR is self-published if the learner profile has the same id as the code>publisher profile id.

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

A Learner can issue achievement assertions to themself and a Publisher can include the self-issued achievement assertion in a CLR. In this case the achievement issuer and learner profiles are the same (have the same id).

2.2.4 As publisher I want to issue a single achievement assertion

As noted in 2.2.1 As a publisher I want to publish a "complete" or "whole" CLR, a Publisher normally includes all of a Learner's achievement assertions the receiver is allowed to see. And the receiver can assume that if an achievement assertion no longer appears in the Learner's CLR, it has been revoked.

If the Publisher wants to transfer a single achievement assertion without revoking others, the publisher should include partial with a value of true. In this case the receiver should not assume any other achievement assertions have been revoked.

A common use case for setting partial to true is when an LMS is sending a single achievement to a credential management hub in real time.

2.2.5 As an issuer I want to identify the entity that assessed an achievement

The achievement Issuer is the entity responsible for providing verification of an achievement assertion. However, it may be the case the Issuer did not make the assessment that the achievement should be asserted. In that case, the Assertion should include the source property to identify the person or organization that assessed the achievement.

For example, a school district may be the official issuer of achievements, but the schools within the district are responsible for assessing the achievement. In this scenario, the assertion should include the source profile of the school making the assessment, and the achievement should include the issuer profile of the school district.

2.2.6 As an issuer I want to assert the level of mastery

If you wish to assert levels of mastery, each Achievement resultDescription should contain rubricCriterionLevels. And each Assertion should include the achievedLevel as a Result.

The assertion results should contain the level of mastery achieved.

2.2.7 As an issuer I want to assert a competency defined in a CASE framework

When the achievement description represents a CASE compentency or academic standard, the Achievment should contain an Alignment to the CASE CFItem. The Alignment should have a targetType of CFItem and the targetUrl should should be the uri of the CFItem.

2.2.8 As an issuer I want to assert a rubric criterion level defined in a CASE framework

When the Result represents a particular CASE rubric criterion level, the Achievement resultDescriptions should include a ResultDescription aligned to the CFRubric, the ResultDescription rubricCriterionLevels should include a RubricCriterionLevel aligned to the CFRubricCriterionLevel, and the Assertion results should contain a Result with the achievedLevel.

2.2.9 As a publisher I want to associate achievements in a hierarchy

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 isReplacedBy 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 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.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.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 code>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.6.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.6.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).

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

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.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"]

6. Add the badge properties using compact IRIs.

   "obi:BadgeClass": { ... }

7. Set issuedOn to the timestamp of when the CLR is issued.
8. 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.