Final

Open Badges Implementation Guide

Introduction

The 1EdTech digital credentials specifications, Open Badges and Comprehensive Learner Record (CLR) enable the recognition of learning achievements in many contexts that are cryptographically verifiable as the learners present them to unlock new opportunities across a lifetime of learning and employment. Key use cases include the recognition of skills and competencies, degrees, certificates and professional certifications, participation, and community engagement.

This implementation guide aims to inform product developers who are investigating or planning implementation of the Open Badges 3.0 and/or CLR 2.0 specifications about the available implementation options and how to situate a product within the ecosystem compatible with these specifications.

Overview

Each Open Badges OpenBadgeCredential is digitally signed by its issuing organization as Verifiable Credentials compatible with the Verifiable Credentials Data Model v2.0. Issuers may bundle together multiple related achievement credentials into transcripts and other longitudinal records for an individual learner in a CLR as a ClrCredential, which is also signed using the same technique as the individual credentials. Additionally, credentials can be augmented with an EndorsementCredential from a third party to lend the support of another individual or organization to the quality or relevance of an issuer or credential data.

A RESTful API, with dynamic client registration, is available to transport data in OpenBadgeCredential and ClrCredential format, under the control of the learner, between systems where they are issued, hosted on behalf of the learner, or verified by third parties in order to qualify the learner for job placement or other opportunities. Implementing systems can participate in a variety of roles

Spec documents (Normative References)

The full set of documents is comprised of the following documents:

Audiences

This implementation guide is intended for product developers across various implementation roles necessary for the operation of an ecosystem where digital credentials efficiently recognize achievements that matter and flow to the contexts where these achievements each need to be understood. Products may be situated to perform one or more roles within the ecosystem, such as issuing credentials, hosting credentials on behalf of learners, and verifying credentials.

OB Overview

An Open Badge (OpenBadgeCredential) is a individual achievement recognized about an individual learner. An Issuer makes a claim that a learner has met the criteria of a particular defined Achievement.

CLR Overview

A Comprehensive Learner Record allows many Open Badge achievement credentials to be bundled together, with some additional associations between them defined. This is like another onion layer wrapping the inner set of credentials that is also signed. Individual component credentials are verifiable, and the wrapping CLR is also verifiable. CLRs can contain achievements from multiple different issuers to show a learner's progression with multiple organizations or subdivisions of a large educational institution.

Use Cases

Use cases are outlined in each the Open Badges and Comprehensive Learner Record specifications. Use cases outline how each specification is intended to provide value to end users through interoperability between products.

Open Badges use cases include:

Assertion Issuance to Wallet
Assertion Issuance Without a Wallet
Recipient Presentation of Assertion
License Issuance
Single Skill Assertion
Mapping Skills
Verifying Continuing Education
Self-assertion
Endorsement
Re-issue an OB 2.0 Badge as an OB 3.0 Badge
Authorization to Issue Given by Creator to Issuer
Revocation of an Issued Credential
Badge Class Status

Comprehensive Learner Record use cases include:

Recent graduate wants to hold a copy of their own official transcript
Job applicant provides proof of degree and transcript to potential employer
Job applicant provides proof of degree and specific courses/engagements from the CLR
Higher Ed Competency-Based Education
Issuer Asserting All Student Achievements Comprehensively as a CLR
Issuer Asserting Partial Transcript at Intermediate Points in Learning Journey
Issuer Asserting Student Up to Date Partial Transcript of Achievements as CLR on Request
Internal Organizational Staff Development and Promotion
Upskilling with Higher Ed Professional/Continuing Education
Teacher Placement with a District
Professional Licensure Test Taker results
Students in Tutoring Program

OB/CLR in the 1EdTech Ecosystem

The core of both Open Badges and Comprehensive Learner Record is an assertion about an achievement. As defined in Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0, an assertion is specific to one learner. It contains a claim that the learner has made a particular achievement and metadata about the achievement, the issuer, and the learner, including possible evidence that provides support for the claim.

These concepts are also present in some way in other specifications within 1EdTech, enabling connections between specifications.

Note: This section is purely informative. The scenarios described here does not define any additional requirements of the specification to conform to.

A clear connection to other specifications occurs through the alignment of achievements. An alignment of an Achievement to can refer to a 1EdTech Competencies and Academic Standards Exchange (CASE)'s CFItem for linking the achievement to a learning object in a CASE's Competency Framework Package.

Another possible connection with other 1EdTech's specifications is the issuer of the credential. Since it can be an organization or entity it can represent the same entity described as an Org in 1EdTech OneRoster® Specification v1.1 or Edu-API Specification Specification v1.0.

Moreover, the learner who the credential is issued to can have a relationship with the User entity in 1EdTech OneRoster® Specification v1.1 or the Person entity in Edu-API Specification Specification v1.0, as well.

Also, 1EdTech OneRoster® Specification v1.1 covers performance of the learner in a context such an assignment vi the Result entity. This can be related with the Result Definition of the issued Achievement, and the Result of an AchievementSubject.

Open Badges and Comprehensive Learner Record can be implemented by systems that use other specifications as well. For example, an Open Badges or CLR application be offered as a tool within an LMS using IMS Global Learning Tools Interoperability® Core Specification v1.3 to launching the OB or CLR-specific interfaces.

Relationship between Verifiable Credentials and OB/CLR

New to this version of the specification, Open Badges and Comprehensive Learner Record are compatible with the Verifiable Credentials Data Model v2.0 (both version 2.0 and the previous Verifiable Credentials Data Model v1.1). The VC Data Model describes an envelope that may be used to express many different types of messages, or "claims", about credential subjects, but credential-type-specific schemas such as OB and CLR are needed in the VC ecosystem to enable coordination of specific credential types and shared expectations for their use.

Open Badges and CLR define three verifiable credential types and expectations for the claims that may be expressed using these types.

OpenBadgeCredential (alias AchievementCredential, formerly "Assertion" in OB 2.0): An assertion that an individual credentialSubject has achieved the criteria of a specified "Achievement" (formerly "BadgeClass"). Metadata about the achievement, its alignment to standards or competency frameworks, evidence related to its attainment, and the learner and issuer's identifying information may be expressed in the credential.
ClrCredential: a container for several AchievementCredentials and associations that link them. Capable of representing both a degree and subsidiary credentials or a detailed transcript full of courses completed and progress through a framework of learning outcomes.
EndorsementCredential: An endorsement of the quality or value, this is an open-ended low-level container that instead of targeting an individual learner, usually makes claims about an Achievement, Issuer Profile or OpenBadgeCredential. Endorsements may be issued by individuals or organizations, potentially even badge recipients themselves.

CLR and OB also define the verification algorithm for these credentials, as well as a set of APIs for exchanging these credentials. But they will also circulate within the broader Verifiable Credentials ecosystem, including through tools that do not apply the full range of domain-specific checks. ClrCredential and OpenBadgeCredential are Verifiable Credentials and may circulate through wallets and protocols that support other credential types as well. The validity status within these general tools may only show a subset of the checks needed to consider OB/CLR valid and fit for a particular purpose.

In addition, issuers may issue these types and make use of issuer identifier types (DID methods), cryptographic key or signature types, status methods, or other Verifiable Credentials options beyond those known to the OB/CLR spec. These additional components may be noted as possibilities in future updates to the OB/CLR specs, but for best interoperability within OB/CLR tools and conformance certification from 1EdTech, issuers should support issuer identifiers, key types, signature types, and (if applicable) status methods mentioned in these specifications. Consult the TrustEd Apps Directory and participate in the 1EdTech membership community to coordinate the selection and rollout of these components as well as potential incorporation into specification updates as named options.

Getting Started (for Developers)

It may seem like an overwhelming task to implement Open Badges 3.0 or CLR 2.0, but there are straightforward options that can take your product to a certified launch simply.

Issuer quickstart

Here is a quickstart tutorial to build an MVP of an Open Badges product that issues Open Badges to learners. It aims to sketch out a simple path to a successful conformant implementation of Open Badges 3.0 issuance. From this base, optional components of the specifications can be layered on to implement relevant APIs, package records in CLR format, implementing revocation or refresh services, and more. Products that complete all the user stories in this quickstart will potentially be eligible for issuer-only certification.

We can track the workflows that must be built through a set of user stories.

Issuer Profile:

As an institutional administrative agent, I can define an Issuer Profile that represents my organization.

See details on the selection of recipient and issuer identifiers, but for the purposes of a quickstart, hosting an issuer profile on an HTTPS url associated with a did:web Decentralized Identifier is an easy choice for a web application. See DID Web Method Specification For example, if the web application under development is running on the domain example.com, an issuer profile identifier might be did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774, which would resolve to a hosted resource available at https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774. But what is served at this URL when a client requests it? The most effective answer is to present a response that best matches what the client is requesting, as it indicates with the Accept HTTP header.

When a client requests Accept: application/json or application/ld+json or does not include an Accept header, a JSON-LD that includes the OB 3.0 context should be returned. It should include its own primary id, all required properties from Profile, and a representation of the public key component of the keypair this issuer uses to sign credentials in selected JWK or eddsa-2022 format. See Dereferencing the Public Key
When a client requests Accept: */* or application/html, an HTML representation of the Achievement should be presented. This should express information about the issuer using Open Graph meta tags, including at least name, description, and image tags for easy rendering of preview cards when the Achievement URL is shared to social media platforms, for instance.

In order to sign credentials, the issuer needs to have an associated key referenced from their profile, whether that profile is resolved via a DID or an HTTPS URL. Either a JWT stack using RSA 256 (or RSA with larger key sizes) or an EdDSA stack using a JSON-LD linked data signature must be used to achieve conformance certification as shown below. See Selecting proof methods and crypto algorithms for a detailed discussion on the management of keys and creation of signatures.

An example of a JSON-LD representation of an issuer profile follows, that uses the EdDSA Cryptosuite 2022 option for signing credentials:

{
	"@context": [
		"https://www.w3.org/ns/did/v1",
		"https://www.w3.org/ns/credentials/v2",
		"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
	],
	"id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
	"type": "Profile",
	"name": "Example Institution",
	"url": "https://example.com",
	"description": "An example of an educational institution, such as a University",
	"email": "info@example.com",
	"verificationMethod": [{
		"id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774#key-0",
		"type": "DataIntegrityProof",
        "cryptosuite": "eddsa-rdf-2022",
		"controller": "https://example.com/issuer/123",
		"publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
	}]
}

Achievement:

As an authorized institutional representative, I can define an Achievement on behalf of my organization, so that I can issue badges recognizing this achievement to learners.

Internally, an Achievement is a database record or document within an issuer system that can be presented using the required and optional properties of the Open Badges Achievement data model. For example, if your app uses a relational database, Achievements would be stored in a database table that has columns for each of the required fields and any supported optional fields. See Achievement Data Model for a listing of fields, noting those with [1] or [1..*] multiplicity are the required ones.

Open Badges Achievements are often associated with images that provide a visual representation of the achievement. Images are optional but are visually prominent components of badges and are often included. OpenBadgeCredentials are issued for many achievementTypes (see enumeration) that may not traditionally include an image, but OB 3.0 now enables this an image to be included for any type of achievement.

For an issuing system that operates a web application on a stable domain, an easy path forward is to select an HTTPS URL as the identifier for each defined Achievement in its database. For example, if the web application under development is running on the domain example.com, an achievement identifier might be https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6. See Publishing achievement definitions for a discussion of options for Achievement identifier. Again, is is best to present a response to requests made to this URL that best matches what the client is requesting, as it indicates with the Accept HTTP header.

When a client requests Accept: application/json or application/ld+json or does not include an Accept header, a JSON-LD that includes the OB 3.0 context should be returned.
When a client requests Accept: */* or application/html, an HTML representation of the Achievement should be presented. This should express information about the Open Graph meta tags including at least name, description, and image tags for easy rendering of preview cards when the Achievement URL is shared to social media platforms, for instance.

An example of the JSON-LD document that might be fetched from this endpoint follows:

 {
 	"@context": "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
 	"id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
 	"type": "",
 	"name": "Advanced Shoe Tie",
 	"description": "Experts at shoe tying can securely fasten laces with a balanced knot.",
 	"achievementType": "Competency",
 	"creator": {
 		"id": "https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774",
 		"type": "Profile",
 		"name": "Example Institution",
 		"url": "https://example.com",
 		"description": "An example of an educational institution, such as a University",
 		"email": "info@example.com"
 	},
 	"criteria": {
 		"narrative": "# Requirements\nShoe tiers must complete..."
 	},
 	"image": {
 		"id": "https://example.com//achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6/image",
 		"type": "Image"
 	},
 	"tag": [
 		"research",
 		"computer science"
 	]
 }

Note that an image associated with the achievement is hosted at a related URL. This could be alternatively presented as a data URI within the Achievement.

Recipient Identifier:

As a learner, I am assigned a badge recipient identifier or can select one of my choosing.

See Selecting recipient and issuer identifiers for an in-depth discussion on how identifiers may be trusted within software to be associated with organizations or natural persons. A "Self-sovereign identity (SSI)" movement advocates for end user control over the identifiers that refer to users. OB and CLR are compatible with identifiers that support traditional or SSI approaches, including email addresses or student ID numbers on the traditional side and Decentralized Identifiers (DIDs) with varying SSI capabilities.

A workable approach that straddles the divide and can achieve good credential transferability to traditional and new verifiers (credential consumers, such as employers) is to deliver badges that target recipients by human-verifiable means at a minimum but then enable end users to present proof of control of a DID, at which point they may claim a version of the credential signed to that identifier instead.

Implementing this workflow varies for different organizations, depending on what identity management solutions they already use. For example, if an app that enables assessment and award of credentials connects to a Student Information System to gain access to course rosters and the student records in that system each include a student ID number and an email address, that application might choose the email address as the best recipient identifier to use in credentials, because it is easiest for target external consumers of those credentials to verify is associated with an individual. That learner might share their badge on a resume and the hiring manager they send it to can verify it matches them by sending them a six digit code and asking their job applicant to read it back to them.

Recommended options include:

If the platform supports integration with a wallet or other system where a learner can present and prove control of an identifier that is usable as a VC or VP issuer identifier, and the user has gone through this process, use their preferred identifier as credentialSubject.id.
If the badges will be delivered primarily for URL-based sharing or download, and the user has not presented a DID, do not include a credentialSubject.id property, and instead include an identifier property referencing a known identifier that may be verified by humans or other non-VC, such as an email address.

As an educator, I can assess a learner and trigger the award of an OpenBadgeCredential recognizing that the student has met the criteria of the previously defined Achievement.

Implementing this workflow may look like an educator accessing details about the credential, and then in an "award" section of those details, selecting a student from a roster list and confirming. The result of this action is typically to make a record in the product's database containing the metadata of the award, such as its creation time, the recipient and their identifier, and any other details such as what the educator may have entered in an evidence narrative text box. While it is possible to generate the signature on the credential in order to store it in the system as a signed document at this point, it is not necessary to sign the credential except when delivering it, via download, wallet integration, or OB/CLR REST API.

As a learner, I am notified that I have achieved the Achievement and that I can claim my badge.

Implementing this workflow may look like an email message sent to the recipient with a link into the issuing coordination system.

As a learner, I can access information about my badge in Open Badges 3.0 OpenBadgeCredential format, complete with a reference to my recipient identifier and a cryptographic proof.

Within a notification email, a learner might see a link into the issuing coordination system, where they are offered the chance to authenticate with their organizational single-sign-on (SSO) provider. After successfully authenticating, they can see options to access or share their badge. See recommended practices about sharing badges via URL, but those capabilities might be available within an Open Badges Host platform, not necessarily an issuer coordination app that produces signed OpenBadgeCredentials. Here, the recipient may see a download JSON option, which upon activation yields a signed verifiable credential like the following.

{
	"@context": [
		"https://www.w3.org/ns/credentials/v2",
		"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
	],
	"id": "urn:uuid:a9fc82eb-416f-47c3-8786-de890331d4a5",
	"type": [
		"VerifiableCredential",
		"OpenBadgeCredential"
	],
	"issuer": {
		"id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
		"type": "Profile",
		"name": "Example Institution",
		"url": "https://example.com",
		"description": "An example of an educational institution, such as a University",
		"email": "info@example.com"
	},
	"validFrom": "2010-01-01T00:00:00Z",
	"name": "Advanced Shoe Tie",
	"credentialSubject": {
		"type": "AchievementSubject",
		"identifier": {
			"type": "IdentityObject",
			"hashed": true,
			"identityHash": "sha256$658625b25ab3d75d613ca97d9a5a77f70e2192feca5557f4ad09a4d4f121f5fc",
			"identityType": "email",
			"salt": "FleurDeSel"
		},
		"achievement": {
			"id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
			"type": "",
			"name": "Advanced Shoe Tie",
			"description": "Experts at shoe tying can securely fasten laces with a balanced knot.",
			"achievementType": "Competency",
			"creator": {
				"id": "https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774",
				"type": "Profile",
				"name": "Example Institution",
				"url": "https://example.com",
				"description": "An example of an educational institution, such as a University",
				"email": "info@example.com"
			},
			"criteria": {
				"narrative": "# Requirements\nShoe tiers must complete..."
			},
			"image": {
				"id": "https://example.com//achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6/image",
				"type": "Image"
			},
			"tag": [
				"research",
				"computer science"
			]
		}
	},
	"proof": [{
		"type": "DataIntegrityProof",
        "cryptosuite": "eddsa-rdf-2022",
		"created": "2022-12-15T16:56:16Z",
		"verificationMethod": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774#key-0",
		"proofPurpose": "assertionMethod",
		"proofValue": "z4o2Pva6ksbXtCCzHv4VM8Ss9WJg2tnxgDbVwfZr1dq3i2jjzNHWPPpHHRw8s1AknGzL4XjBZVyh3BzSo59qz8NBp"
	}]
}

Several things to note about this credential.

There is no primary credential subject ID in this example. The recipient has not yet presented proof of control of a DID, so the credential identifies them by their email address. The identityHash is the SHA-256 hash of the concatenated student email address and credential salt jjefferson18@example.comFleurDeSel. This enables the student to present the credential and their institutional email address to a verifier who can check the hash to ensure the badge belongs to them.
The verificationMethod.id identifies the issuer's public signing key using a fragment identifier within the issuer's identifier. This is the same ID that appeared in the representation of the key in the issuer DID document itself.
This credential uses the id urn:uuid:a9fc82eb-416f-47c3-8786-de890331d4a5. Some implementers might choose an HTTPS URL on the same domain as the issuer DID Document and the Achievement, but is not assumed that the general public would be able to access data about this credential if they retrieved the id of the document. Other issuers may allow learners to rely on badge backpacks or mobile wallets to provide sharing capabilities that match the use case. See discussion: Sharing badge links to social media.

Follow the steps in the Conformance Certification Guide for the issuer role to submit a downloaded signed credential like the above for conformance checks.

Note: You can review Issuer's best practices in its own section.

API quickstart

The API of Open Badges 3.0 and Comprehensive Learner Record 2.0 is divided into four groups, whether the OB / CLR tool is a consumer or a provider of the API and whether the operations it consumes / provides are read operations or write operations.

Note: The API of Open Badges 3.0 and Comprehensive Learner Record 2.0 defines the exchange of credentials and update of the profile between two hosts. The API defines methods for revoking a previously allowed access, which prevents future exchange of credentials. That said, this revocation doesn't affect the already exchanged credentials. Open Badges Credentials and CLR Credentials have its own revocation methods.

Depending of your certification goals it must be necessary to implement one or more of these groups of API. For instance, if you're seeking the certification as an Issuer (not Issuer only) you'll need to implement the service-consumer-write group.

Consumer basics

Consumers of the OB / CLR API must acquire an OAuth 2.0 access token from an authorization server for making API calls. The acquisition of the token implies a set of steps:

Call the ServiceDescription endpoint. Once you know the base url of your authorization server, make a GET call to the well-know getServiceDescription endpoint. The response will contains all the endpoints needed for register your client application (x-imssf-registrationUrl) and acquiring and access token (authorizationUrl, tokenUrl and refreshUrl) with the desired scopes.

Example: Sample getServiceDescription request

GET /ims/ob/v3p0/discovery HTTP/1.1
Host: example.edu
Accept: application/json

Example: Sample getServiceDescription response

HTTP/1.1 200 OK
Content-Type: application/json

...
"components": {
	"securitySchemes": {
		"OAuth2ACG": {
			"type": "oauth2",
			"description": "OAuth 2.0 Authorization Code Grant authorization",
			"x-imssf-name": "Example Provider",
			"x-imssf-privacyPolicyUrl": "provider.example.com/privacy",
			"x-imssf-registrationUrl": "provider.example.com/registration",
			"x-imssf-termsOfServiceUrl": "provider.example.com/terms",
			"flows": {
				"authorizationCode": {
					"tokenUrl": "provider.example.com/token",
					"authorizationUrl": "provider.example.com/authorize",
					"refreshUrl": "provider.example.com/token",
					"scopes": {
						"https://purl.imsglobal.org/spec/clr/v2p0/scope/delete" : "...",
						"https://purl.imsglobal.org/spec/clr/v2p0/scope/readonly" : "...",
						"https://purl.imsglobal.org/spec/clr/v2p0/scope/replace" : "..."
					}
				}
			}
		}
	},
	"schemas": {
		...
	}
}
...

Register your client using OAuth 2.0 Dynamic Client Registration Protocol OAuth 2.0 Dynamic Client Registration Protocol. To do that, make a POST call to the endpoint defined in the x-imssf-registrationUrl field from the previous step.

Example: Sample registration request

POST /connect/register HTTP/1.1
Host: auth.1edtech.org
Accept: application/json
Content-Type: application/json; charset=utf-8

{
	"client_name": "Example Client Application",
	"client_uri": "https://client.1edtech.org/",
	"logo_uri": "https://client.1edtech.org/logo.png",
	"tos_uri": "https://client.1edtech.org/terms",
	"policy_uri": "https://client.1edtech.org/privacy",
	"software_id": "c88b6ed8-269e-448e-99be-7e2ff47167d1",
	"software_version": "v4.0.30319",
	"redirect_uris": [
		"https://client.1edtech.org/Authorize"
	],
	"token_endpoint_auth_method": "client_secret_basic",
	"grant_types": [
		"authorization_code",
		"refresh_token"
	],
	"response_types": [
		"code"
	],
	"scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/delete https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly https://purl.imsglobal.org/spec/ob/v3p0/scope/replace offline_access"
}

The response object will contain the details needed to perform the OAuth 2.0 Authorization Code Grant flow (client_id, client_secret, among others).

Acquire an access token following OAuth 2.0 Authorization Code Grant flow as described in then IMS Security Framework IMS Global Security Framework v1.1. Briefly, it consists in building the authorizationUrl from the url defined in the authorizationUrl field gotten from step one with some query parameters. The use of Proof Key for Code Exchange (PKCE) Proof Key for Code Exchange by OAuth Public Clients is recommended.

Once built, redirect the user to this url in order to start the OAuth 2.0 Authorization Code Grant flow.

Example: Sample ACG authorization request (line breaks for clarity)

	HTTP/1.1 302 Found
	Location: https://auth.1edtech.org/authorize?
	client_id=4ad36680810420ed
	&response_type=code
	&scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%ob%2Fv3p0%2Fscope%2Fassertion.readonly%20offline_access
	&redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
	&state=26357667-94df-4a14-bcb1-f55449ddd98d
	&code_challenge=XeDw66i9FLjn7XaecT_xaFyUWWfUub02Kw118n-jbEs
	&code_challenge_method=S256

Once the authorization is made, the authorization server will redirect the browser back to the specified redirect_uri with the code, scope, and state query string parameters.

Then, you have to acquire an access token by making a POST request to the tokenUrl gotten from the Service Description endpoint. The HTTP POST request MUST include a Basic authorization header with the client_id and client_secret provided in the registration response. The body of the token request MUST include the following form fields: grant_type, code, redirect_uri, scope and code_verifier.

Example: Sample ACG token request (line breaks for clarity)

	POST /token HTTP/1.1
	Host: auth.1edtech.org
	Authorization: Basic NDE2ZjI1YjhjMWQ5OThlODoxNWQ5MDA4NTk2NDdkZDlm
	Content-Type: application/x-www-form-urlencoded

	grant_type=authorization_code
		&code=7c7a73263ee14b2b48073d0615f286ec74f6636689046cb8dbede0b5e87a1338
		&redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
		&scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%2Fob%2Fv3p0%2Fscope%2Fassertion.readonly+offline_access
		&code_verifier=mYUQfKNgI1lSbY8EqtvNHLPzu0x%2FcVKO3fpWnX4VE5I%3D

The response of this call will contain the access token to use in future calls to the API.

Example: Sample ACG token response

	HTTP/1.1 200 OK
	Cache-Control: no-store, no-cache, max-age=0
	Pragma: no-cache
	Content-Type: application/json; charset=UTF-8

	{
		"access_token": "863DF0B10F5D432EB2933C2A37CD3135A7BB7B07A68F65D92",
		"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
		"expires_in": 3600,
		"token_type": "Bearer",
		"scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly offline_access"
	}

User stories for an issuer (API consumer) and host (API provider)

Here are a selection of user stories covering how to add on support for the OB 3.0 API as an Issuer to a simple product after completing the issuer quickstart above. Completing the consumer-side portion of the will potentially qualify a product for conformance certification as an Open Badges Issuer (with API service-consumer-write support). This is a presentation of the experience of using the API from the user's perspective. Additional under-the-hood technical details for each procedure are described in the Specification section 6: Open Badges API.

As a badge holder, I can inform my issuer of my selected Open Badges host service.

Provide the base url or domain of the selected Open Badges host service to the issuer. This could utilize a text input where a user can paste a URL, or a consumer service could add known service providers to a list, presenting the manual input as an advanced option.

As an issuer service, I can discover information about an Open Badges host service.

The service consumer will call the getServiceDescription endpoint from the base url of the Open Badges service provider (host).

As an issuer service, I can register with a Open Badges host service provider.

By performing the OAuth 2.0 Client Dynamic Registration OAuth 2.0 Dynamic Client Registration Protocol to the endpoint defined in the x-imssf-registrationUrl field of the Open Badges Host service description.

As a badge holder, I can request and approve a connection between my issuer and my host account.

By following the OAuth 2.0 Authorization Code Grant flow in their browser, following redirects between the issuer and the host service.

As a badge holder, I can select one, some or all OpenBadgeCredentials to transmit to my host account.

A basic service consumer (write) integration would typically push all awarded badges to the host, and a more advanced service consumer may enable users to select a specific scope of credentials for transmission.

As a badge holder, I can see that new badges I am awarded are automatically transmitted to my host, even when I am not interacting with either the issuer or host services directly, if I have configured my issuer to send badges automatically.

As a badge holder, I can deauthorize my issuer from connection to my Open Badges host, so my issuer can't retrieve badges from my Open Badges host no more.

By revoking the access token granted to the issuer from within the Open Badges (service provider) interface.

As a user who has revoked consumer access to my host, I should see the broken connection within the consumer app and be able to initiate reauthorization.

While authenticated with a host service, one action users may take is to view the connected issuer(s) or displayer(s) they have authorized and to revoke some of those approvals. When a user takes this action, it invalidates any access tokens or refresh tokens the connected services, so that those services may no longer access API endpoints on the user's behalf. This should be handled in the issuer or displayer service as a potential expected outcome, after which the service may display an inactive status on the connection and/or prompt the user to reauthorize if they desire to continue sending badges to that host once again.

Your issuer service may discover that your access credentials no longer work as expected when you receive a 401 or 403 status response from the host when attempting to access a protected endpoint and then subsequently receive an error response when attempting token refresh.

Provider basics

The above description of a consumer implementation shows the requests that are made of a provider. This guide does not go into depth about how to accomplish the provider side of these interactions, but the API roughly follows common OAuth patterns for (a) dynamic client registration, authorization code access token grants, and protected resource endpoint access.

Provide the ServiceDescription endpoint with the right values for the OAuth2ACG's securitySchema. The urls there must point to your OAuth related endpoints.
Allow Registration of clients using Dynamic Registration.
Implement OAuth 2.0 Authorization Code Grant flow for granting tokens.
Enable access to protected resources to requests authenticated with an appropriately scoped access token.
Enable deauthorization of access tokens via user interface. Show a list of authorized applications and their associated access details and enable users to revoke authorizations from the service provider (host).

Supporting Technical Resources

Recommended Practices

Conformance certification ensures consistency across an important but focused scope of requirements. A healthy ecosystem will necessarily develop out the collective experience and collaboration of implementers. Implementers are encouraged to join the 1EdTech community to provide feedback and discuss how we can collectively improve our implementations and guidance.

Below are a variety of recommended practices and considerations for the implementation of the Open Badges and CLR specification.

Issuer

Selecting recipient and issuer identifiers, such as DID methods

Both issuers and recipients (credential subjects) of Open Badges and CLR credentials may be identified with a range of identifiers.

Issuers may be identified with an HTTP URL that resolves to an issuer profile that expresses profile and key information in JSON-LD. Or, they might be identified by a Decentralized Identifier (DID) that resolves to a document with some information about the issuer and/or its signing key(s).

DID methods most commonly used in interoperability testing by community members, both for issuer identifiers and recipient identifiers:

The did:key method resolves identifiers to a DID document that contains a public key representation without accessing any remote resources by embedding a representation of the key itself in the DID path.
The did:jwk method is similar to did:key, except the value encoded in the DID path is a base64url-encoded representation of a key in JWK (JSON Web Key) format.
The did:web method is a quick way to use HTTP URLs with DIDs, because the value in the path of the DID decodes to a URL which is then fetched, resulting in a DID document. It relies on the DNS registration of a domain holder, but many DIDs may be associated with any one domain or subdomain.

Technically, this set of DID methods whose use is commonly observed among early implementers is a narrow range of the DID methods proposed, and each of them lacks some capabilities promoted as possibilities with certain DID methods, such as the ability to rotate keys periodically, recover control after losing relevant keys, or avoidance of the use of DNS. The DID Method Rubric provides a number of relevant comparison factors. Usage of other DID methods may significantly change in the coming years as the consumer technology landscape and open source libraries develop.

The OB 3.0 and CLR 2.0 specifications make no normative requirements strictly limiting which DID methods may be used. Implementers have an incentive to create interoperable experiences with one another through implementing common DID methods and testing interoperability paths for users. In practice, the DID method(s) a credential's Issuer supports being the same as the DID methods Hosts and Displayers (or other wallets and verifiers) support is what governs interoperability.

The Open Badges, CLR and broader Verifiable Credentials ecosystems will take time to converge on reliable interoperability pathways. Specific implementations working together through cooperation and communication will create the opportunities for others to make compatible implementation choices as well as inform future normative specification versions.

Selecting proof methods and crypto algorithms

The OB and CLR specifications define some requirements around the signing or proving of credentials (see Proofs). Two formats of proof method are introduced, JWTs and Linked Data Proofs. Within each format, there are a range of options that issuers may select for cryptographically signing the credentials. Notably, signing algorithm selection and its closely related concept of key material expression format must be considered. The best choices within these options sometimes depend on other parts of the issuer's tech stack and which options are supported among wallets and verifiers with whom badge recipients want to share their badges.

The OB 3.0 and CLR 2.0 specifications identify some specific options, which are used by the conformance test suite to check product implementations. In order to achieve conformance certification, issuers MUST produce credentials secured with a supported mechanism. These identified algorithms will likely see the broadest early implementation within Open Badges.

Linked Data Proofs using the Data Integrity EdDSA Cryptosuites v1.0. Issuers produce an DataIntegrityProof proof referencing a key URL of a public key expressed in eddsa-rdf-2022 format as its verificationMethod.
JWTs with RSA256 algorithm, with key material published as JSON Web Key (JWK).

Some issuers may experiment with or implement novel proof mechanisms, such as new Linked Data Proofs or JWT signing algorithms, in coordination with hosts and verifiers. These may be useful for specific use cases or to explore new capabilities. However, issuers should be aware that these may not be supported by all hosts, wallets and verifiers, and that interoperability may be limited until these new mechanisms are more widely adopted. The 1EdTech Digital Credentials Workgroup may periodically consider recommending new proof methods for inclusion in the OB and CLR specifications and the 1EdTech certification program.

A step-by-step guide to signing an OB or CLR is provided in the OB specification section on Proofs. In order to achieve certification, implementers must be able to pass conformance testing with one of the listed methods, but it is expected that the ecosystem will grow as issuers, verifiers, and other services explore new approaches.

It is important to not only prevent unauthorized access to keys and application processes that can trigger signing. At least as important to keeping the signing keys themselves safe is being confident in knowing if keys may have been accessed or compromised with a high degree of confidence. Considerations include:

Issuers may wish to make use of Hardware Security Modules (HSMs) whenever possible that prevent keys from leaving the device where authorized signing occurs.
Cloud platform Key Management Services are largely not yet compatible with Ed25519 keys and may not be able to generate the signatures within linked data proofs.
- HashiCorp Vault (open source or in HashiCorp cloud) offers a Ed25519-compatible sign API via its "Transit" API.
- Google Cloud Platform supports RSA and ECDSA on the non-NIST secp256k1 curve but not Ed25519.
- JWT signing with RSA family keys may have broader support in systems like this across all major cloud vendors offering a KMS.
Some proof mechanisms feature additional security properties, such as a capability for selective disclosure, or improved "unlinkability", the resistance to correlation of credentials or verification requests from the same holder.

Publishing `Achievement` definitions and selecting `Achievement` identifiers

Arguably the most important field for an Achievement is the id, the creator's primary identifier for that achievement. It is expressed as a URI. Two approaches for identifier expression are common, with differing capabilities and slightly different instructions for interpretation:

Use an HTTPS URL as the identifier: Issuer systems and other achievement publishing systems can publish achievements at the identifier URLs. Clients can use the URL to request the metadata directly from its creator when a client wants an authoritative representation of the issuer's current understanding of the metadata associated with the Achievement. When two OpenBadgeCredentials are issued at different points in time but reference the same Achievement.id, they may contain slightly different representations of the Achievement metadata itself. Relying parties are encouraged to understand the embedded signed data as the representation that the issuer had for the credential at the time it was issued, and they may encounter a different representation embedded in a different credential, which they should understand as a different version of the same achievement. The issuer may use the optional version property to express a label for each of these versions for presentation where relevant. At any point in time, a relying party may request an updated copy of the Achievement from its id URL. If the response returns Achievement data successfully, the client should understand the retrieved metadata to represent the issuer's current understanding of the Achievement. When relying parties encounter the same HTTPS-type achievement ID in AchievmentCredentials across multiple issuers, they can assume that the issuers did intend to recognize the same achievement, as it is defined by its publisher, but they cannot make an assumption that each of the issuers were duly authorized to recognize this achievement by its creator or even that the Achievement honestly represents the identity of its creator, unless the relying party verifies an OpenBadgeCredential referencing this Achievement issued by the creator referenced in the copy of the Achievement retrieved from its ID URL. Future versions of Open Badges may address use cases and normative requirements serving use cases around verifiable authorship of an Achievement or delegation of capabilities related to an Achievement by the Achievement's creator.
Use a UUID: Issuers sometimes assign an identifier that is assumed to be locally unique to that issuer but cannot be dereferenced. Nevertheless, relying parties may encounter multiple OpenBadgeCredentials that reference an achievement with this ID over time. For OpenBadgeCredentials from the same issuer that reference an Achievement with the same ID, relying parties should interpret these as different versions of the same Achievement. When the same UUID-type Achievement.id is referenced by different issuers across multiple OpenBadgeCredentials, relying parties cannot authoritatively determine that the intent was to recognize the same semantic achievement.

A common use case among Open Badges implementers is for a verifier to expect a particular Achievement claim in an OpenBadgeCredential from a specific issuer. With Open Badges 2.0, it was presumed that verification that an achievement (BadgeClass) was associated with a credential (Assertion) issuer as part of verification, by determining that hosted Achievement IDs were on the same domain as hosted Assertion IDs and/or hosted Issuer IDs. With OB 3.0, some of this capability can no longer be assumed to remain. This is partly because there is no longer a requirement for issuer profiles to use HTTP IDs, but also because integrity verification is assumed to occur at the Verifiable Credentials Data Model level only, because wallets and credentials verifiers will primarily focus on verifying the integrity of the proof on each credential without assumed capacity to verify other relationships represented deeply within these credentials even if OB 3.0 had included such a mechanism in its scope.

Managing credential status and revocation

The ability to mark a credential as revoked is an important capability for many organizations that make use of Open Badges and CLR. The Verifiable Credentials Data Model v2.0 offers an extensible mechanism by which a credential status resource may be exposed within a credential. Various use cases and solutions have been developed to enable credential status checking with a range of capabilities and implications. OB and CLR reference optional 1EdTech extensions supporting verifiers in obtaining updated representations of credentials and checking for revocation. Issuers and verifiers need to support a common mechanism in order for status checking to work, and yet issuers often need to produce the credential without knowing which other parties might someday rely on it or what methods those verifiers may support. Here are some mechanisms identified by the implementing community for status and revocation management.

The 1EdTech Credential Refresh Service also accompanies the OB and CLR specifications and enables fetching of an updated version of a credential under inspection by a verifier. The 1EdTech verifier tools will request updated version if such an endpoint is indicated in the badge. There is no approach to authentication or variable authorization defined in this specification, so if an issuer uses it, it is presumed that any client could request the latest version of the credential from this endpoint if they knew the correct URL. Future versions of this specification may serve use cases that require more in-depth protection of refresh endpoints.
The recommended option for checking revocation is the Bitstring Status List v1.0 specification, which was adopted as a standards-track specification by the VCWG on December 14th 2022. This protocol enables an issuer to publish a compactly encoded list of status indicator bits covering many credentials at once in an unnamed order. Within each issued credential, the issuer includes a pointer to a specific bit within the bulk status list. This enables verifiers to efficiently query for status results without revealing which specific credential's status is being checked. It does not feature the ability to retrieve a revocation reason for a revoked credential, nor does it provide a refreshed version of the credential consistent with the issuer's latest status data, features that are sometimes bundled with revocation.

Alignment with CASE items

1EdTech Competencies and Academic Standards Exchange (CASE) specification defines how systems exchange and manage information about learning standards and/or competencies in a consistent and referenceable way.

1EdTech Competencies and Academic Standards Exchange (CASE) defines an information model consisting in, briefly, a container (CFDoc) of a set of academic standard/competency document definitions (CFItem). These CFItem can have associations with others CFItem of another containers, allowing several types of relationships between learning objectives/competences from one institution and another.

In Open Badges and Comprehensive Learner Record, the recording of related skills, competencies, standards, and other associations are enabled by the alignment of an Achievement. This field defines the fields for univocally establish a connection between the Achievement and a node in an educational framework, i.e CFItem.

Example: Achievement alignment (CASE)

Verifiable Credential (JSON)

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [
        {
          "type": "Alignment",
          "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
          "targetFramework": "Alabama Course of Study: English Language Arts",
          "targetName": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain",
          "targetType": "CFItem",
          "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e8-824f-0242ac160002"
        }
      ]
    }
  },
  "iss": "https://example.edu/issuers/565049",
  "jti": "http://example.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}

Verifiable Credential with Proof (JSON-LD)

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [
        {
          "type": "Alignment",
          "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
          "targetFramework": "Alabama Course of Study: English Language Arts",
          "targetName": "Cite strong and thorough textual evidence to support analysis of what the text says explicitly as well as inferences drawn from the text, including determining where the text leaves matters uncertain",
          "targetType": "CFItem",
          "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e8-824f-0242ac160002"
        }
      ]
    }
  },
  "proof": [
    {
      "type": "DataIntegrityProof",
      "created": "2026-05-27T13:00:51Z",
      "verificationMethod": "https://example.edu/issuers/565049#z6MkiPEq8BsAbPJaC7k2edCzV4DQh8CHsaVFnbWDDkHa3Z9H",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "z3Uxv6zD8GnaUEi8Rc4YhsyfepJ38iboiG5XSnY1DxN1CLjyV2BKobvF42H42CemWTSxzREdryJL48Jh48JSifdvL"
    }
  ]
}

Verifiable Credential (JWT)

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "kty": "RSA",
    "n": "oM2NnO43jO424JtG48cioSy-bhaGMLQDyP6vscLAMoyRpPmzsH1lIGp-AuhmpX7bRZ3BXY
tReH98UHIEiqrBUZFbQ8e-G2rfsf0R7O4MdcuHjvQ_6RNCw4vrVoTIu9HqXS1dr4kby5K-05ZNRHRcIC
cJ_Jgd-H8ih3LmMlnMcX984pgb_Z2CxV82SD9IBngDgmSiW6I01OVpKVq77lzfVoImgCkqJdkuU96WVY
S12IQ8p3YW7Ra2W8wZ4qUXanNCezgL_aX-xgsZHMlBr1T55eLZCiCiQJklZGRxCAqFUypHLUQ5GLwrKN
kSC6qDVdhBT-C0mlMjn7cCDBhLdFhqeQ",
    "e": "AQAB"
  }
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
//       that duplicates the iss, nbf, jti, and sub fields in the
//       Verifiable Credential (vc) field.
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Example University Degree",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://1edtech.edu/achievements/1",
      "type": "Achievement",
      "criteria": {
        "narrative": "Cite strong and thorough textual evidence to support analy
sis of what the text says explicitly as well as inferences drawn from the text, 
including determining where the text leaves matters uncertain"
      },
      "description": "Analyze a sample text",
      "name": "Text analysis",
      "alignment": [
        {
          "type": "Alignment",
          "targetCode": "74f5bb7d-d7cc-11e8-824f-0242ac160002",
          "targetFramework": "Alabama Course of Study: English Language Arts",
          "targetName": "Cite strong and thorough textual evidence to support an
alysis of what the text says explicitly as well as inferences drawn from the tex
t, including determining where the text leaves matters uncertain",
          "targetType": "CFItem",
          "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-11e
8-824f-0242ac160002"
        }
      ]
    }
  },
  "iss": "https://example.edu/issuers/565049",
  "jti": "http://example.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJrdHkiOiJSU0EiLCJuIjoib00yTm5PNDNq
TzQyNEp0RzQ4Y2lvU3ktYmhhR01MUUR5UDZ2c2NMQU1veVJwUG16c0gxbElHcC1BdWhtcFg3YlJaM0JY
WXRSZUg5OFVISUVpcXJCVVpGYlE4ZS1HMnJmc2YwUjdPNE1kY3VIanZRXzZSTkN3NHZyVm9USXU5SHFY
UzFkcjRrYnk1Sy0wNVpOUkhSY0lDY0pfSmdkLUg4aWgzTG1NbG5NY1g5ODRwZ2JfWjJDeFY4MlNEOUlC
bmdEZ21TaVc2STAxT1ZwS1ZxNzdsemZWb0ltZ0NrcUpka3VVOTZXVllTMTJJUThwM1lXN1JhMlc4d1o0
cVVYYW5OQ2V6Z0xfYVgteGdzWkhNbEJyMVQ1NWVMWkNpQ2lRSmtsWkdSeENBcUZVeXBITFVRNUdMd3JL
TmtTQzZxRFZkaEJULUMwbWxNam43Y0NEQmhMZEZocWVRIiwiZSI6IkFRQUIifX0.eyJAY29udGV4dCI6
WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3B1cmwuaW1zZ2xv
YmFsLm9yZy9zcGVjL29iL3YzcDAvY29udGV4dC0zLjAuMy5qc29uIl0sImlkIjoiaHR0cDovL2V4YW1w
bGUuZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiT3Bl
bkJhZGdlQ3JlZGVudGlhbCJdLCJpc3N1ZXIiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3Vl
cnMvNTY1MDQ5IiwidHlwZSI6IlByb2ZpbGUiLCJuYW1lIjoiRXhhbXBsZSBVbml2ZXJzaXR5In0sInZh
bGlkRnJvbSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwibmFtZSI6IkV4YW1wbGUgVW5pdmVyc2l0eSBE
ZWdyZWUiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2
ZjFjMjc2ZTEyZWMyMSIsInR5cGUiOiJBY2hpZXZlbWVudFN1YmplY3QiLCJhY2hpZXZlbWVudCI6eyJp
ZCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUvYWNoaWV2ZW1lbnRzLzEiLCJ0eXBlIjoiQWNoaWV2ZW1lbnQi
LCJjcml0ZXJpYSI6eyJuYXJyYXRpdmUiOiJDaXRlIHN0cm9uZyBhbmQgdGhvcm91Z2ggdGV4dHVhbCBl
dmlkZW5jZSB0byBzdXBwb3J0IGFuYWx5c2lzIG9mIHdoYXQgdGhlIHRleHQgc2F5cyBleHBsaWNpdGx5
IGFzIHdlbGwgYXMgaW5mZXJlbmNlcyBkcmF3biBmcm9tIHRoZSB0ZXh0LCBpbmNsdWRpbmcgZGV0ZXJt
aW5pbmcgd2hlcmUgdGhlIHRleHQgbGVhdmVzIG1hdHRlcnMgdW5jZXJ0YWluIn0sImRlc2NyaXB0aW9u
IjoiQW5hbHl6ZSBhIHNhbXBsZSB0ZXh0IiwibmFtZSI6IlRleHQgYW5hbHlzaXMiLCJhbGlnbm1lbnQi
Olt7InR5cGUiOiJBbGlnbm1lbnQiLCJ0YXJnZXRDb2RlIjoiNzRmNWJiN2QtZDdjYy0xMWU4LTgyNGYt
MDI0MmFjMTYwMDAyIiwidGFyZ2V0RnJhbWV3b3JrIjoiQWxhYmFtYSBDb3Vyc2Ugb2YgU3R1ZHk6IEVu
Z2xpc2ggTGFuZ3VhZ2UgQXJ0cyIsInRhcmdldE5hbWUiOiJDaXRlIHN0cm9uZyBhbmQgdGhvcm91Z2gg
dGV4dHVhbCBldmlkZW5jZSB0byBzdXBwb3J0IGFuYWx5c2lzIG9mIHdoYXQgdGhlIHRleHQgc2F5cyBl
eHBsaWNpdGx5IGFzIHdlbGwgYXMgaW5mZXJlbmNlcyBkcmF3biBmcm9tIHRoZSB0ZXh0LCBpbmNsdWRp
bmcgZGV0ZXJtaW5pbmcgd2hlcmUgdGhlIHRleHQgbGVhdmVzIG1hdHRlcnMgdW5jZXJ0YWluIiwidGFy
Z2V0VHlwZSI6IkNGSXRlbSIsInRhcmdldFVybCI6Imh0dHBzOi8vY2FzZXJlZ2lzdHJ5Lmltc2dsb2Jh
bC5vcmcvdXJpLzc0ZjViYjdkLWQ3Y2MtMTFlOC04MjRmLTAyNDJhYzE2MDAwMiJ9XX19LCJpc3MiOiJo
dHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNTY1MDQ5IiwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1
L2NyZWRlbnRpYWxzLzM3MzIiLCJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUx
MmVjMjEifQ.kxGiRH0I8CX-Fg8zO3cEDubgb8qO_GH_BFBgwr087il-lz2VgZ9QoQRB-9HL4_XU06l00
bbBod0vAdxd7AvWMKXF-R6glILxEgu-2kFh8Vi1MQJ8nnfMK0Xt1ZtEXNK3DLJA4JLUCTRsbUpM1_v6J
iY0MyUu-gw111VmOUB6ckEshYo_WGnHSwdYlB3Q7aZ_1Gy2WBeVbiNdc15aNtVVXxuJCG4wFj_IYfb6Q
ors4JawDMr5rZ_a6bnPy0P18bkxbXOuS5aZxkypTsCeNcCxjak2RkNA2BGhnBy20L1P6oGKKhPk5kNuc
9ToVdH5kXv2eBz4wlnpmoinqNJOyNjqpA

Alignment with a ceterms:Credential resource

In Open Badges and Comprehensive Learner Record, it is possible to use alignment to link an achievement to a resource that is described using non-1EdTech vocabularies. Three targetTypes (specifically, ceterms:Credential, ceasn:Competency, and CTDL) have been defined to link to a resource described using the Credential Transparency Description Language (CTDL) family of schema. CTDL defines how credentials, competencies, and many other attributes (such as assessments, courses, programs, transfer value, organizations, and more) can be described in detail and linked to other useful information.

ceterms:Credential is used to establish that a connection is between an achievement and a credential offering described using CTDL. In CTDL, a "credential" can be described using hundreds of defined terms and connections amongst those terms. For example, CTDL can identify a credential as a ‘license’ requiring a particular ‘assessment’ for the demonstration of particular ‘competencies’.

Organizations may publish rich descriptive information about the achievements they offer to the Credential Registry. Credential offering information published to the Registry is available in the Credential Finder application (https://credentialfinder.org/), and issuers of badges for these achievements can link to the page in the Credential Finder using an alignment with targetType of ceterms:Credential using the credential’s CTID.

Example: Achievement alignment to more information about the Credential (ceterms:Credential)

    "achievement": {
      "id": "https://1edtech.edu/achievements/9",
      "type": "Achievement",
      "criteria": {
        "narrative": "Demonstrate a comprehensive understanding of core 3D modeling concepts, successfully create a range of 3D models that meet specified criteria, and pass a practical examination applying foundational techniques in real-time scenarios"
      },
      "description": "Credential for proficiency in the basic techniques and concepts of 3D modeling.",
      "name": "Fundamentals of 3D Modeling Certificate",
      "alignment": [{
        "type": "Alignment",
        "targetCode": "ce-66ae075c-5cc0-4b49-bb15-ea513e1480ac",
        "targetDescription": "Additional information powered by the Credential Registry.",
        "targetName": "Fundamentals of 3D Modeling Certificate",
        "targetFramework": "Credential Transparency Description Language",
        "targetType": "ceterms:Credential",
        "targetUrl": "https://sandbox.credentialengine.org/publisher/credential/ce-66ae075c-5cc0-4b49-bb15-ea513e1480ac"
      }]
    }

Alignment with a ceasn:Competency resource

Achievements often align to skills or Competencies, which can be published to the Credential Registry. When aligning to this type of data, use the targetType ceasn:Competency.

Example: Achievement alignment to a competency (ceasn:Competency)

    "achievement": {
      "id": "https://1edtech.edu/achievements/10",
      "type": "Achievement",
      "criteria": {
        "narrative": "Technical Proficiency: The student's use of 3D modeling tools and techniques should be evident, with smooth surfaces, clean meshes, and appropriate use of textures and materials. The model should be free from technical errors, such as overlapping vertices, and should be optimized for the intended platform or medium."
      },
      "description": "Demonstrated through an academic project requiring an architectural structure, design of a product prototype, simulating a real-world scenario in a virtual environment, and application of 3D modeling principles.",
      "name": "Transform conceptual ideas into tangible 3D representations.",
      "alignment": [{
        "type": "Alignment",
        "targetCode": "ce-e76ee0c4-c455-4cf9-8382-c9d226c69d99",
        "targetDescription": "Additional information powered by the Credential Registry.",
        "targetName": "Transform conceptual ideas into tangible 3D representations.",
        "targetFramework": "Credential Transparency Description Language",
        "targetType": "ceasn:Competency",
        "targetUrl": "https://sandbox.credentialengine.org/finder/competency/ce-e76ee0c4-c455-4cf9-8382-c9d226c69d99"
      }]
    }

Alignment with a CTDL resource

There are many other entity classes that can be described using the CTDL vocabulary. When making an alignment to an Assessment, Learning Opportunity, Job, Occupation, or other entity, use the generic targetType CTDL. This informs consumers to expect CTDL data of one of these other types. Some consumers may simply render a link to the webpage where more information can be retrieved, and others may support fetching the specific data to provide an even richer display. The following example shows how an issuer might express an alignment to a Learning Opportunity Course that has been published to the Credential Registry as CTDL-formatted open data.

Example: Achievement alignment to another type of entity (CTDL)

    "achievement": {
      "id": "https://1edtech.edu/achievements/11",
      "type": "Achievement",
      "criteria": {
        "narrative": "Earns a passing grade."
      },
      "description": "Dive into the world of three-dimensional design with ART 302. This course offers students an immersive experience in transforming abstract concepts into tangible 3D models. Through hands-on projects, expert-led demonstrations, and cutting-edge software tools, learners will master the art of conceptualizing and creating detailed 3D representations. Ideal for aspiring designers, animators, and digital artists, this course emphasizes both technical proficiency and creative expression. Join us and bring your ideas to life in three dimensions!",
      "name": "ART 302: 3D Modeling From Concept to Creation",
      "alignment": [{
        "type": "Alignment",
        "targetCode": "ce-23390b82-eff7-4ff1-894c-9dfe174206be",
        "targetDescription": "Additional information powered by the Credential Registry.",
        "targetName": "ART302: 3D Modeling From Concept to Creation",
        "targetFramework": "Credential Transparency Description Language",
        "targetType": "CTDL",
        "targetUrl": "https://sandbox.credentialengine.org/finder/learningopportunity/ce-23390b82-eff7-4ff1-894c-9dfe174206be"
      }]
    }

Skills

A Skill Assertion credential is just like a basic OpenBadgeCredential in how an Achievement is included, except that it makes a claim referencing an Achievement that is generic to allow for use by many possible issuers. The Achievement may describe alignment to external competency or skill definitions, such as a CFItem, but the most important aspect of the skill assertion pattern is the shared use of a common achievement that represents a skill or competency across multiple OpenBadgeCredential issuers.

This usage of shared achievements enables consumers to describe specific achievements that they would like learners to hold without being particular about where the learner obtains a credential certifying that achievement. This recognizes the many pathways that lifelong learners find to attain comparable skills.

Example: Skill Assertion (Credential Registry)

Verifiable Credential (JSON)

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://1edtech.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "name": "Solve and graph linear equations and inequalities",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://example.com/achievements/math/linear-1",
      "type": "Achievement",
      "achievementType": "Competency",
      "creator": {
        "id": "https://example.com/issuers/123767",
        "type": "Profile",
        "name": "Example Industry Group",
        "url": "https://example.com",
        "description": "Example Industry Group is a consortium of luminaries who publish skills data for common usage.",
        "email": "info@exammple.com"
      },
      "criteria": {
        "narrative": "Learners must demonstrate understanding of linear algebra and graphic representation of linear equations."
      },
      "description": "This achievement represents developing capability to solve and graph linear equations and inequalities",
      "image": {
        "id": "https://example.com/achievements/math/linear-1/image",
        "type": "Image",
        "caption": "A line, sloping upward optimistically"
      },
      "name": "Linear equations and inequalities"
    }
  },
  "issuer": {
    "id": "https://1edtech.edu/issuers/565049",
    "type": "Profile",
    "name": "1EdTech University",
    "url": "https://1edtech.edu",
    "phone": "1-222-333-4444",
    "description": "1EdTech University provides online degree programs.",
    "image": {
      "id": "https://1edtech.edu/logo.png",
      "type": "Image",
      "caption": "1EdTech University logo"
    },
    "email": "registrar@1edtech.edu"
  },
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ],
  "iss": "https://1edtech.edu/issuers/565049",
  "jti": "http://1edtech.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}

Verifiable Credential with Proof (JSON-LD)

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://1edtech.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "name": "Solve and graph linear equations and inequalities",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://example.com/achievements/math/linear-1",
      "type": "Achievement",
      "achievementType": "Competency",
      "creator": {
        "id": "https://example.com/issuers/123767",
        "type": "Profile",
        "name": "Example Industry Group",
        "url": "https://example.com",
        "description": "Example Industry Group is a consortium of luminaries who publish skills data for common usage.",
        "email": "info@exammple.com"
      },
      "criteria": {
        "narrative": "Learners must demonstrate understanding of linear algebra and graphic representation of linear equations."
      },
      "description": "This achievement represents developing capability to solve and graph linear equations and inequalities",
      "image": {
        "id": "https://example.com/achievements/math/linear-1/image",
        "type": "Image",
        "caption": "A line, sloping upward optimistically"
      },
      "name": "Linear equations and inequalities"
    }
  },
  "issuer": {
    "id": "https://1edtech.edu/issuers/565049",
    "type": "Profile",
    "name": "1EdTech University",
    "url": "https://1edtech.edu",
    "phone": "1-222-333-4444",
    "description": "1EdTech University provides online degree programs.",
    "image": {
      "id": "https://1edtech.edu/logo.png",
      "type": "Image",
      "caption": "1EdTech University logo"
    },
    "email": "registrar@1edtech.edu"
  },
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ],
  "proof": [
    {
      "type": "DataIntegrityProof",
      "created": "2026-05-27T13:00:50Z",
      "verificationMethod": "https://1edtech.edu/issuers/565049#z6MkppnDhCSBQuzD7iZ1Fcoacgm3YrU83GMK3dP6zRBxqbHs",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2mfCMXwyadvviszwhAMvRmaGHJSsehrgAqFkabpEVhzS4M8rmhZAyxEfXjfwCfDdzeJxyW34QwvLAiEXaFTFq5pm"
    }
  ]
}

Verifiable Credential (JWT)

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "kty": "RSA",
    "n": "mMoPJHcE7DmBpPOHPkaEYAlrXuFxWoQdGPEQSXahBelKTC1GhYf54daELqwYdtin-NfLts
tVnkKVTQIH8dWYViSB1oxwtsRfxwUWS2J-w_Mt8fjJznHoYnMoGI7B5fIwcyxoAo3wQz8Ml7hFQTPDDC
41ny6C48OI4TQhSOwrFbvhthV5av3pmvFvZ8BMfZd5Jifx8QQIk4pxSHRDLIM3QWgFY0C8DoT6o1c6vd
ZiXLJuP02VJGR0YVJlSPyh-Psm7d9vn9K5K3LUAm9o-1oRzsw0KhgYgqXpmgxKrntBJpSIVlCLG9DYzP
Od71YPwJgMcq5kL_vFJ1_TKaE_kTzUvw",
    "e": "AQAB"
  }
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
//       that duplicates the iss, nbf, jti, and sub fields in the
//       Verifiable Credential (vc) field.
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://1edtech.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "name": "Solve and graph linear equations and inequalities",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "AchievementSubject",
    "achievement": {
      "id": "https://example.com/achievements/math/linear-1",
      "type": "Achievement",
      "achievementType": "Competency",
      "creator": {
        "id": "https://example.com/issuers/123767",
        "type": "Profile",
        "name": "Example Industry Group",
        "url": "https://example.com",
        "description": "Example Industry Group is a consortium of luminaries who
 publish skills data for common usage.",
        "email": "info@exammple.com"
      },
      "criteria": {
        "narrative": "Learners must demonstrate understanding of linear algebra 
and graphic representation of linear equations."
      },
      "description": "This achievement represents developing capability to solve
 and graph linear equations and inequalities",
      "image": {
        "id": "https://example.com/achievements/math/linear-1/image",
        "type": "Image",
        "caption": "A line, sloping upward optimistically"
      },
      "name": "Linear equations and inequalities"
    }
  },
  "issuer": {
    "id": "https://1edtech.edu/issuers/565049",
    "type": "Profile",
    "name": "1EdTech University",
    "url": "https://1edtech.edu",
    "phone": "1-222-333-4444",
    "description": "1EdTech University provides online degree programs.",
    "image": {
      "id": "https://1edtech.edu/logo.png",
      "type": "Image",
      "caption": "1EdTech University logo"
    },
    "email": "registrar@1edtech.edu"
  },
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achieve
mentcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ],
  "iss": "https://1edtech.edu/issuers/565049",
  "jti": "http://1edtech.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJrdHkiOiJSU0EiLCJuIjoibU1vUEpIY0U3
RG1CcFBPSFBrYUVZQWxyWHVGeFdvUWRHUEVRU1hhaEJlbEtUQzFHaFlmNTRkYUVMcXdZZHRpbi1OZkx0
c3RWbmtLVlRRSUg4ZFdZVmlTQjFveHd0c1JmeHdVV1MySi13X010OGZqSnpuSG9Zbk1vR0k3QjVmSXdj
eXhvQW8zd1F6OE1sN2hGUVRQRERDNDFueTZDNDhPSTRUUWhTT3dyRmJ2aHRoVjVhdjNwbXZGdlo4Qk1m
WmQ1SmlmeDhRUUlrNHB4U0hSRExJTTNRV2dGWTBDOERvVDZvMWM2dmRaaVhMSnVQMDJWSkdSMFlWSmxT
UHloLVBzbTdkOXZuOUs1SzNMVUFtOW8tMW9SenN3MEtoZ1lncVhwbWd4S3JudEJKcFNJVmxDTEc5RFl6
UE9kNzFZUHdKZ01jcTVrTF92RkoxX1RLYUVfa1R6VXZ3IiwiZSI6IkFRQUIifX0.eyJAY29udGV4dCI6
WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3B1cmwuaW1zZ2xv
YmFsLm9yZy9zcGVjL29iL3YzcDAvY29udGV4dC0zLjAuMy5qc29uIiwiaHR0cHM6Ly9wdXJsLmltc2ds
b2JhbC5vcmcvc3BlYy9vYi92M3AwL2V4dGVuc2lvbnMuanNvbiJdLCJpZCI6Imh0dHA6Ly8xZWR0ZWNo
LmVkdS9jcmVkZW50aWFscy8zNzMyIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIk9wZW5C
YWRnZUNyZWRlbnRpYWwiXSwibmFtZSI6IlNvbHZlIGFuZCBncmFwaCBsaW5lYXIgZXF1YXRpb25zIGFu
ZCBpbmVxdWFsaXRpZXMiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmVi
MWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsInR5cGUiOiJBY2hpZXZlbWVudFN1YmplY3QiLCJhY2hpZXZl
bWVudCI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWNoaWV2ZW1lbnRzL21hdGgvbGluZWFyLTEi
LCJ0eXBlIjoiQWNoaWV2ZW1lbnQiLCJhY2hpZXZlbWVudFR5cGUiOiJDb21wZXRlbmN5IiwiY3JlYXRv
ciI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xMjM3NjciLCJ0eXBlIjoiUHJvZmls
ZSIsIm5hbWUiOiJFeGFtcGxlIEluZHVzdHJ5IEdyb3VwIiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNv
bSIsImRlc2NyaXB0aW9uIjoiRXhhbXBsZSBJbmR1c3RyeSBHcm91cCBpcyBhIGNvbnNvcnRpdW0gb2Yg
bHVtaW5hcmllcyB3aG8gcHVibGlzaCBza2lsbHMgZGF0YSBmb3IgY29tbW9uIHVzYWdlLiIsImVtYWls
IjoiaW5mb0BleGFtbXBsZS5jb20ifSwiY3JpdGVyaWEiOnsibmFycmF0aXZlIjoiTGVhcm5lcnMgbXVz
dCBkZW1vbnN0cmF0ZSB1bmRlcnN0YW5kaW5nIG9mIGxpbmVhciBhbGdlYnJhIGFuZCBncmFwaGljIHJl
cHJlc2VudGF0aW9uIG9mIGxpbmVhciBlcXVhdGlvbnMuIn0sImRlc2NyaXB0aW9uIjoiVGhpcyBhY2hp
ZXZlbWVudCByZXByZXNlbnRzIGRldmVsb3BpbmcgY2FwYWJpbGl0eSB0byBzb2x2ZSBhbmQgZ3JhcGgg
bGluZWFyIGVxdWF0aW9ucyBhbmQgaW5lcXVhbGl0aWVzIiwiaW1hZ2UiOnsiaWQiOiJodHRwczovL2V4
YW1wbGUuY29tL2FjaGlldmVtZW50cy9tYXRoL2xpbmVhci0xL2ltYWdlIiwidHlwZSI6IkltYWdlIiwi
Y2FwdGlvbiI6IkEgbGluZSwgc2xvcGluZyB1cHdhcmQgb3B0aW1pc3RpY2FsbHkifSwibmFtZSI6Ikxp
bmVhciBlcXVhdGlvbnMgYW5kIGluZXF1YWxpdGllcyJ9fSwiaXNzdWVyIjp7ImlkIjoiaHR0cHM6Ly8x
ZWR0ZWNoLmVkdS9pc3N1ZXJzLzU2NTA0OSIsInR5cGUiOiJQcm9maWxlIiwibmFtZSI6IjFFZFRlY2gg
VW5pdmVyc2l0eSIsInVybCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUiLCJwaG9uZSI6IjEtMjIyLTMzMy00
NDQ0IiwiZGVzY3JpcHRpb24iOiIxRWRUZWNoIFVuaXZlcnNpdHkgcHJvdmlkZXMgb25saW5lIGRlZ3Jl
ZSBwcm9ncmFtcy4iLCJpbWFnZSI6eyJpZCI6Imh0dHBzOi8vMWVkdGVjaC5lZHUvbG9nby5wbmciLCJ0
eXBlIjoiSW1hZ2UiLCJjYXB0aW9uIjoiMUVkVGVjaCBVbml2ZXJzaXR5IGxvZ28ifSwiZW1haWwiOiJy
ZWdpc3RyYXJAMWVkdGVjaC5lZHUifSwidmFsaWRGcm9tIjoiMjAyMi0wNy0wMVQwMDowMDowMFoiLCJj
cmVkZW50aWFsU2NoZW1hIjpbeyJpZCI6Imh0dHBzOi8vcHVybC5pbXNnbG9iYWwub3JnL3NwZWMvb2Iv
djNwMC9zY2hlbWEvanNvbi9vYl92M3AwX2FjaGlldmVtZW50Y3JlZGVudGlhbF9zY2hlbWEuanNvbiIs
InR5cGUiOiIxRWRUZWNoSnNvblNjaGVtYVZhbGlkYXRvcjIwMTkifV0sImlzcyI6Imh0dHBzOi8vMWVk
dGVjaC5lZHUvaXNzdWVycy81NjUwNDkiLCJqdGkiOiJodHRwOi8vMWVkdGVjaC5lZHUvY3JlZGVudGlh
bHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSJ9.WFF
ys_Vh18XVbBfMOBZka18pwvywJvHKGQjqg6lFE6NqwkRQBhmRCFDCCaMIhstD0tBCm4VfqNVFVeitXQT
zIWHayV9Mc4gXtOSgvNutjspPWIM4ET-YSwAObqi_3-qPtDUOvjjOGP4O6sec0b8BZbLOAMgMB6TwcwF
ci8gk2aFTNNEVogrvCSQBvVzK0TyNCNmXXOS6Yq1lII-rwW-9EHh0HQFv3Q19xfp-7m4UxGpy0u8IweR
z-SpaXEcP9HKxESk6VjzgO4YJOo9peyP5KNbASsi_ZvkpXBwCwtxsFxAm6RuMCCwRglJZXF67tmytiJV
itXQpptj_9Y1elmaBpA

Including additional recipient profile information

Sometimes issuers want credentials to be shareable to audiences who are not capable of authenticating subjects via an identifier such as a DID. Many of these use cases may be served by including one or more email identifiers. (Only partial data is shown for clarity, for example omitting the achievement claim within credentialSubject.)

Example: Email identifier in credential subject

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "identifier": [
            {
                "type": "IdentityObject",
                "hashed": false,
                "identityHash": "a.exampleton@example.edu",
                "identityType": "emailAddress"
            }
        ]
    }
}

If the known email address for the user is expected to no longer be a useful source of authentication, such as if the user loses access to a work or university email after leaving that organization (perhaps 6 months after graduation), an issuer may wish to provide additional identifying information, such as a name.

Example: Name identifier in credential subject

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "identifier": [
            {
                "type": "IdentityObject",
                "hashed": false,
                "identityHash": "Albert Exampleton",
                "identityType": "ext:name"
            }
        ]
    }
}

Inclusion of additional personally identifiable information about the subject, especially with "hashed": false, reduces the potential anonymity of the subject. Those with whom the credential is shared may share it to others, who would be able to view this identifying information. While sharing typically passes through control of the subject/holder, different issuers may weigh the potential benefits of including this information against the risks of unauthorized disclosure.

If issuers desire to include much more information about the subject in the credential, they may add the Profile type and include additional properties from Profile. The above approach using IdentityObject is expected to be more broadly usable, because displayers of OpenBadgeCredentials will expect this type of data. Additional data from Profile is not expected directly within credentialSubject, so it is less likely that displayers would build custom handling for these unexpected properties. An "advanced" view where users may review the JSON data directly may be included in some displayer products, in which case viewers would be able to review this information more directly.

Example: Given name and family name credential subject with Profile

{
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": ["AchievementSubject", "Profile"],
        "givenName": "Albert",
        "familyName": "Exampleton"
    }
}

Embedding Evidences

Issuers can add a description of the work that the recipient did to earn the achievement via the evidence attribute of AchievementCredential. This description can be a page that links out to other pages if linking directly to the work is infeasible.

The id property also can be the evidence encoded as a Data URI. However, embedding the evidence as Data URI as the id of the evidence has some caveats:

Due to the JSON-LD canonicalization process for signing, there's a row for each field of the evidence with the id inside. If the id is the evidence itself as Data URI, the size of the payload to process grows significantly, moreover when evidence has 5 fields and is extensible.
Some libraries fail when processing this.

Also attempting to embed large data in a credential JSON is not recommended. You should expect uneven interop performance if you do that.

Instead, the recommendation for embedding the evidence is:

use a urn: URI for the id.
have a separate property (data or whatever works) that contains the text-encoded data.

Key provenance

Keys used in proof generation must belong to the issuer. However, there isn't an existing way in current standards to completely assure this provenance.

The following best practices establish a verification mechanism to assure that the issuer is the owner of the key used in a credential.

Linked Data proof

Linked Data Proofs defines a method to get the public key (via verificationMethod) which, as defined by Verifiable Credential Data Integrity 1.0, implies the dereference of a controller document.

Section 2.6 of Verifiable Credential Data Integrity 1.0 describes a way to verify the association of the verification method with an issuer:

One way to check for such an association is to ensure that the value of the controller property of a proof's verification method matches the URL value used to identify the issuer or holder, respectively. This particular association indicates that the issuer or holder, respectively, is the controller of the verification method used to verify the proof.

We recommend following this practice. As an issuer, then, you must set the value of the controller as the id of the issuer.

External proof

When using an external proof, an issuer must set either the kid or jwt fields of the JOSE header of the JWS. kid is an URI that can be dereferenced to an object of type JWK representing the public key, wether jwt is the representation of the public key.

In order to assure key provenance, we recommend the use of a JWK Set (JKWS) JSON Web Key (JWK). This set, following this recommendation, should be publicly accessible via the well-known url:

https://{domain}/.well-known/jwks.json

The reponse of a request to this url is a JSON-serialized representation of the JKWS with the media type application/jwk-set+json.

Section 6 of IMS Global Security Framework v1.1 contains recommendations for key management.

When using the kid attribute, an issuer must set it to an existing key in its set. On the other hand, when using the jwt attribute, the key set in this field must be one of the keys in the set.

Issuing platforms with multiple issuers

JSON Web Key (JWK) allows adding additional members to the JWK format:

Additional members can be present in the JWK; if not understood by implementations encountering them, they MUST be ignored. Member names used for representing key parameters for different keys types need not be distinct. Any new member name should either be registered in the IANA "JSON Web Key Parameters" registry established by Section 8.1 or be a value that contains a Collision-Resistant Name.

We propose leverage this to add a new member iss in the JWK for the issuer's id.

JWK Set endpoint

Following this recommendation ultimately means that, for an issuer to be trusted, the endpoint for the issuer's JSON Web Key Set should be publicly available at any time a credential is verified, which can happen long after the issuing of the credential. If don't, there's a potential issue of a valid credential not accepted because the endpoint is no longer available.

Following this recommendation, thus, implies a commitment for the issuer to maintain its JWK Set and publicly expose it through the endpoint.

Privacy

Privacy of grades and evidence

Results or evidence fields may contain data that should be kept confidential or require learner’s consent to disclose. These includes items such as grade data or evidence documents that may have personally identifiable information (PII). Unless it is protected, this data will be transmitted in a “SHARE” transmission of the full payload (i.e.: Baked image, API request, or Web link to an HTML version of a credential) or in a verified presentation request from a verifier application.

The verified credentials data model 2.0 outlines ways that verified credentials (VCs) can manage data privacy by either an enveloping proof or an embedded proof. The BBS or SD-JWT signing methods can support selective disclosure or encryption of the data (such as with TLS), while a Linked Data Proof does not. CBOR encoding can also be used within the JSON of a credential for selective disclosure so only parts of the specific badge data are shared and can handle the inclusion of zero-knowledge proofs. CBOR can be used with the SD-JWT or LinkedData Proof methods but only manages the selective disclosure and encryption of the protected data at the time of the verified presentation request.

It is recommended that the issuer provide information on which fields may be governed by selective disclosure and the method used in the beginning of the credential payload.

Context of grades

In the case where an issuer is intending to implement credentials for the purpose of documenting all academic activity, grade data might include such use cases as work that is in progress, on hold, provisional, withdrawn, or failed. In this case, it should be required for the issuer to include the ResultStatus. Learners should not be able to disassociate the context of this status from their results if a Holder application implements selective disclosure.

Evidence documents

In the case that a link is included as evidence, it should be immutable. Links that a learner or another party has access to edit (i.e.: YouTube, photo sharing site, document sharing site, etc.) should not be used in a verified credential so that the file is always in the same state as when the credential was issued. The issuer may wish to implement some form of password access control to links and a mechanism for the learner to approve access. It is advisable for Holder applications to implement a process for a verifying application to disclose their identity or reason for a verified presentation request (e.g.: “I need to verify that the course was completed with a passing grade”).

Displayer

Cryptosuites in Linked Data Proofs

Linked data proofs imply the use of a cryptosuite for its generation and further verification. The Open Badges 3.0 and Comprehensive Learner Record 2.0 specifications define cryptosuite(s) supported by 1EdTech conformance tests. Verifiers should expect to encounter credentials secured with these cryptosuites.

Cryptosuites evolve and produce new versions occasionally. The 1EdTech conformance process may over time support updated version or additional cryptosuite options, and there are issued credentials with a proof generated using a cryptosuite now considered deprecated. Verifiers should consider supporting prior cryptosuites, especially for cases when the credential doesn't define the refresh service. Issuers that do support refresh services may be able to update the credential to use a newer cryptosuite.

Prior (deprecated) cryptosuites identified in OB 3.0 and CLR 2.0 drafts include:

eddsa-2022
Ed25519Signature2020

Key provenance and issuer identity information

Keys used in proof generation must belong to the issuer. However, there isn't a existing way in current standards to completely assure that the key that signed a credential proof is associated with the issuer identifier. These steps do not ensure that issuer metadata expressed in a credential is accurate, such as its name, url or contact email. Displayers may choose to authenticate the issuer identifier against a trusted list of issuers obtained out of band of the credential. When such a mechanism isn't available, the displayer should mark issuer data included in a credential as unverified.

The following best practices establish a verification mechanism to assure that the issuer is the owner of the key used in a credential.

Linked Data proof

Linked Data Proofs defines a method to get the public key (via verificationMethod) which, as defined by Verifiable Credential Data Integrity 1.0, implies the dereference of a controller document.

Section 2.6 of Verifiable Credential Data Integrity 1.0 describes a way to verify the association of the verification method with an issuer:

One way to check for such an association is to ensure that the value of the controller property of a proof's verification method matches the URL value used to identify the issuer or holder, respectively. This particular association indicates that the issuer or holder, respectively, is the controller of the verification method used to verify the proof.

We recommend following this practice. As an verifier, then, you must check that the value of the controller is the id of the issuer.

External proof

Section 6.3.1 of Securing Verifiable Credentials using JOSE and COSE extends the definition of kid as

If kid is present in the JOSE Header or the COSE Header, a verifier can use this parameter as a hint indicating which key was used to secure the verifiable credential, when performing a verification process as defined in JSON Web Signature (JWS).

kid MUST be present when the key of the issuer or subject is expressed as a DID URL

With these two premises, the recommendation for verifying key provenance is using JWK Set. A verifier must, then, get the public JKWS of the issuer for further check of the provided key.

In order to get the issuer's JKWS, a verifier must build a well-known url with the authority part of the issuer's id (Uniform Resource Identifier (URI): Generic Syntax):

https://{authority}/.well-known/jwks.json

A verifier must make a HTTP request to this endpoint with an accept header of application/jwk-set+json. The response of this call must a JWKS.

After the request, a verifier must check that the provided key in in the returned set. If the key in the JOSE Header in referenced by the kid field, this kid must be in the set. On the other hand, if the key is represented by the jwk field, this jwk must be in the set with any specified kid.

If the found JWT in the set contains the member iss, this must be equal to the issuer's id.

The credential should be considered invalid and not trustworthy if the key provenance cannot be verified via the method described above.

Verifiable Credentials v1.1

One of the main reasons for upgrading Open Badges and Comprehensive Learner Record to a new major release was the alignment of the specifications with W3C's Verifiable Credentials Data Model.

The alignment to an external specificacion require some sort of change management. During the development of both Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0, the current version of W3C's Verifiable Credentials Data Model was Verifiable Credentials Data Model v1.1, version with the specificacions went to Candidate Public Final.

During the time Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0 were in Canditate Public Final, W3C's Verifiable Credentials Data Model was upgraded to Verifiable Credentials Data Model v2.0. After an analysis of the changes the working group decided to upgrade Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0 to align with the newest version of W3C's VC.

However, there were already existing issued credentials based in the older version of W3C's VC. These credentials, until upgraded to the newest version, must be valid. Therefore, the displayer certification requires validation of credentials issued with this old version.

Changes

In terms of data model, the main changes between versions of W3C's VC are:

New context URI. While in version 1.1 was https://www.w3.org/2018/credentials/v1, in version 2.0 is https://www.w3.org/ns/credentials/v2. Also, when signing with Linked Data Proofs, version 1.1 required the addition of the context https://w3id.org/security/data-integrity/v1. In version 2.0, those terms are included in the main context file.
Validity period. validFrom and validUntil, in version 2.0, replace issuanceDate and expirationDate, in version 1.1

In terms of file format, version 2.0 adds the application/vc+ld+json content type, that wasn't defined in version 1.1.

In terms of integrity, especially in the JSON Web Token Proof Format, version 2.0 removes the requirement of storing the payload of the credential in the vc claim of the JWT. Instead, the whole JWT body is the payload credential.

This chapter resumes the changes between versions of the W3C's VC specification that have impact in Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0. Please refer to official documents for an exhausting list of changes between these versions.

Verification

Displayers must be able to verify OpenBadgeCredentials and ClrCredentials built under versions 1.1 and 2.0 of W3C's VC specification.

In order to successfully verify a received credential, the first step is to identify which version of Verifiable Credential Data Model is based on. This identification depends mainly of the integrity of the credential, especifically on the proof used.

For instance, in credentials issued with the Linked Data Proof, where the payload received by the displayer is the JSON of the credential, the first item in the @context array will determine which version of W3C's VC the credential is based on:

https://www.w3.org/2018/credentials/v1, for Verifiable Credentials Data Model v1.1
https://www.w3.org/ns/credentials/v2, for Verifiable Credentials Data Model v2.0

On the other hand, when the credential received by the displayer was issued with the JSON Web Token Proof Format, the displayer should check wheter there is a vc claim in the JWT body, as its existance may indicate that the credential is based on Verifiable Credentials Data Model v1.1. However, the displayer must also check the value of the first item in the @context array to match the value of each W3C's VC version, and mark the credential as invalid when the value in the @context array doesn't correspond to the claim within the JWT where the payload of the credential was stored.

The specifications provide some JSON schemas supporting this duality in a way that succeed for valid – in terms of data schema - credentials based either on Verifiable Credentials Data Model v1.1 or Verifiable Credentials Data Model v2.0.

These schemas are:

The specifications also provide JSON schemas supporting this duality for EndorsementCredential's:

Host

Open Badges 3.0 API recommendations

Consider the following example two products using the OB 3.0 API to interact:

Example: Sending an Open Badge to a credential backpack via API

Luis is in college pursuing a technical degree. He completes an assessment in class and receives a grade. He is notified by email that he has earned a badge and clicks through, where he is authenticated to the college's student Open Badges portal using his college single sign on. He sees that he has actually earned two badges, each representing competencies, that were assessed by his instructor. The website says the CLR is ready to save, so Luis selects that option. The application shows him a list of two credential backpack providers he can use to save. There is an advanced toggle that reveals an additional option to enter a service provider URL, but Luis closes that and picks one of the known options that looks good and has a good privacy policy. He selects that option and is directed to the backpack site where he signs up for an account. After he completes registration, he is prompted that he may return to the Open Badges portal to complete receiving his credential. He confirms and appears back in the Open Badges portal, where a confirmation message greets him saying all credentials were successfully transferred. He then confirms to return once more to the backpack site, where sees the two Open Badges representing his competencies.

Luis looks at a page detailing the metadata of the first achievement, including the achievement type of Competency and a description of what he had been working to learn. He thinks that being able to look back at these and see the description will help him prepare for job interviews in the future.

Luis sees an option to share his competency badge to a social media site. He proceeds and is prompted to customize sharing settings, including whether anyone with the link is able to view full verifiable details or if viewers need to request access. He selects full details and shares the generated URL to a professional social network site, where a preview card appears including relevant keywords for the competency. His post receives a like from one of Luis's friends immediately.

This is a long user workflow. What makes this interaction successful?

These products each have a clear sense of their scope of responsibility. One is the "Issuer" of the Open Badges, the other is the "Backpack". They can each implement the necessary parts of the experience that fits their role and not invest deeply in other parts. For example, the issuer platform doesn't need to offer a system of sharing URLs and online access control management, all it does is sign the credential and implement the Client side of the Open Badges API. The Backpack handles the sharing, including giving Luis significant control over URL-based access. This takes product focus.
Known-successful integrations are highlighted in the experience. This takes cooperation between implementation partners, but the benefit is clear: Luis doesn't need to know what an Open Badge is or how to find a compatible backpack on the TrustEd Apps Directory in order to take advantage of his credential. Tested compatibility paths and instructions on how to take the next step are provided as the primary choice for non-advanced users.
The backpack platform implemented the Open Graph Protocol for the sharing URL, better supporting the social network site's generation of a preview card that included the badge image and a relevant title and content snippet.

Other recommendations related to implementing the API include:

Service provider (host) platforms represent the learner (resource owner) in interactions that allow that learner to share their credentials with relying parties. In order to give the learner adequate control over sharing, hosts should recognize that learners may want to use their system for multiple different partially overlapping uses. For example, a learner might hold formal professional credentials and informal social badges in the same account. Hosts should give the learner the ability to attenuate access grants to read their badges so that certain service consumers (read) can only access badges that the user has designated for that purpose. The mechanism to do this may vary across different systems. For example, a host might enable a learner to gather badges into collections and may make it possible to select one or more collections when making an access grant. The consumer application they grant access to will be able to read any badges added to the collection at the time of the request, even if the badge is added to the collection after the original access grant was approved.
Products should take into account many factors and opportunities for user failure including high conceptual complexity or use of jargon, forgotten passwords or no-longer working email addresses, and potential incompatibilities due to differing choices of DID methods, key formats/signature suites, or credential exchange protocol choices across different certifiable products.

The OB API enables key use cases for interoperability between web services that manage Open Badges on holders' behalf. This is centered on an ecosystem of backpacks and clients. "Backpack" and "web wallet" are commonly used terms to refer to a web service that holds Open Badges and/or CLR credentials for learners, enabling them to manage and share them. Clients each often primarily act to issue credentials or to verify credentials to display or convert into local understanding of someone's capabilities and accomplishments. Typically learners authorize issuers to send their credentials to backpacks and then from those backpacks, authorize verifier clients to access them.

This is an ambitious ecosystem to propose, even though users are familiar with the underlying OAuth and OpenID Connect experiences that tie together dozens of their online accounts. There is the addition of dynamic client registration and the wide variety of optional components these specifications feature. Implementers should prioritize high success-rate user experiences in credential acceptance.

Products that best aim to teach users a controlled number of concepts and provide interfaces offering easy successful options for the most common actions have a better chance of ensuring learners can take advantage of their digital credentials. No learner should be disadvantaged by poor interoperability experiences and dead ends.

CLR 2.0 API recommendations

As ClrCredentials bundle a number of individual OpenBadgeCredentials together, they sometimes offer additional information about the relationships between elements. Implementations of the CLR API should be done for use cases where the signed bundles (signed by the original issuers) or the inclusion of associations provides benefit to users.

Example: Sending a CLR to a credential backpack (host) via API

Luis achieved his Associate Degree and is looking for jobs. He is notified by email that his CLR is ready and clicks through, where he is authenticated to the college's student CLR portal using his college single sign on. He sees the CLRCredential. This is his first CLR, and he wants to see how to use it to help his job search.

The website says the CLR is ready to save, so Luis selects that option. The application shows him a list of two credential backpack providers he can use to save. There is an advanced toggle that reveals an additional option to enter a service provider URL, but Luis closes that and picks one of the known options that looks good and has a good privacy policy. He selects that option and is directed to the backpack site where he signs up for an account. After he completes registration, he is prompted that he may return to the CLR portal to complete receiving his credential. He confirms and appears back in the CLR portal, where a confirmation message greets him saying all credentials were successfully transferred. He then confirms to return once more to the backpack site, where sees the CLR Credential and all the individual Achievement Credentials within it representing the degree, the courses he took, and the competencies he mastered.

Protocols for connection to Verifiable Credentials Wallets

While the OB 3.0 and CLR 2.0 APIs serve use cases for web services to verifiably exchange credentials on behalf of holders, the Verifiable Credentials community is exploring how more portable wallets, often operating on mobile devices which cannot serve HTTP requests can serve additional use cases. All Verifiable Credentials, including Open Badges and CLRs can and will be communicated over a range of protocols. This is a space that is seeing significant experimentation pre-standardization.

Implementers are encouraged to cooperate through communities like 1EdTech to ensure high-quality user experience in the exchange of credentials between their products, both via OB and CLR APIs and emerging protocols to carry these credentials into next-generation use cases. When new user experience patterns are presented that aim to become universal, take care to help the user through the workflow, and give them fallback solutions whenever possible.

Protocols under development to transport Verifiable Credentials including Open Badges and CLR include Credential Handler API (CHAPI), DIDComm, and OID4VC.

Example: The experience of a learner who receives their CLR

Luis now is viewing his CLR in his backpack, a web service that holds Open Badges & CLR Verifiable Credentials on his behalf:

Luis is looking at his college's CLR portal. He sees these credentials are set to be issued to his college email address, but he just graduated and will lose access to that email address in 6 months. There is an option to prove control of a personal address and have the credentials issued to that address, but Luis also sees another option to connect a wallet on his mobile device, where he can use a securely generated passkey to create a cryptographically verifiable Decentralized Identifier (DID) to use. Links appear to mobile app stores for several mobile wallet options.

Luis puts it off until Saturday but then reads a little about Verifiable Credentials and is interested to try out replacing his soon-to-expire email address with a DID. He chooses one of the wallet options that works on his device and sets it up. Back at the CLR portal on his desktop computer, he selects to proceed to connect to a mobile wallet. He chooses the CLR Credential and several of the competency achievements to send to the wallet initially. He is directed to an experience where through scanning a QR code displayed on screen and confirming some details on his phone, he is shown that there is a successful connection, and that credentials have been downloaded to the wallet. He sees them on his phone, which says he'll be able to use them in the future on websites that use Verifiable Credentials.

Here, Luis walks through the experience of downloading a mobile app to use as a wallet for credentials including his CLRCredential and several OpenBadgeCredentials. This issuer app seems to be compatible with a wide variety of web wallets, perhaps even through implementing multiple protocols used by these wallets with a variety of options. Some issuer services may be operating with connections to fewer or different wallet applications.

Some recommendations for pre-standardization implementation of service connection protocols include:

Test integrations and communicate with your implementation partners for the benefit of users' experience.
Share pain points (without exposing personal information) and learn about possible solutions from others.
Accurately inform users of the experimental status of features and integrations as necessary. Giving users an accurate sense of whether they are traveling a smooth and well-trodden path or a new route that may have pitfalls or dead ends goes a long way to gaining user trust.
Prioritize tested high-success pathways to product integration.
Provide some opportunities for users who desire it to learn about the work your product is doing under the hood to take care of their important data and empower them as participants in non-monopolistic ecosystems using open standards.
Give users fallback options that are likely to succeed if the first path they try fails. For example, offer the chance to choose any wallet that uses a certain supported protocol, but suggest one particular integration as an easy choice, so users don't get stuck if the wallet they previously used for a different issuer doesn't work with the protocol used on your site. If all else fails, maybe a signed credential in a JSON download is an adequate compromise.
Present benefits and risks to user to help them understand their choices. This example emphasized the user-owned nature of DIDs enabled by wallet connection in the face of the potential loss of control of an institutional or organizational email identifier. Products should make users aware of risks, such as any loss of data or verifiability that might be caused by losing a physical device.

Gene receives an Open Badge for the completion of a certificate program and wants to include it verifiably on a professional social network. He can post a reference to the badge as a URL on the his profile. The social network site displays a summary card showing the credential information.

The URL is the universal mechanism for sharing content on the web. URLs provide the easiest mechanism for badge recipients to share their achievements on social media, in resumes, and job applications. The vast majority of last-generation Open Badges 2.0 and CLR 1.0 credentials in production support URLs for both verification and sharing. Learners' need to be able to place their achievements verifiably into platforms via URL sharing will continue, but platforms that hold their data are encouraged to take advantage of new OB 3.0 and CLR 2.0 capabilities to grant greater control over sharing to data subjects themselves as they implement share by URL capabilities.

Recommendations for the use of share URLs include:

Give data subjects easy to use options to limit or grant access to data or inclusion of their data in directories. Do not publish learner achievement data in credential format on unauthenticated URLs by default. Pushing badges to a dedicated backpack or wallet can enable that platform to generate and appropriately protect sharing URLs with the data subject's consent in mind.
If any Open Badges objects have HTTPS URLs as their id, such as Achievement endpoints or Open Badges 2.0 verification endpoints are used for legacy support by an issuer that also publishes objects using the current version of the standard, use content negotiation on sharing URLs to enable the presentation of Use Open Graph Protocol tags on the sharing URLs to enable easy generation of card previews.

Baked badges and iOS devices

Starting iOS 16, this operating system strips EXIF data from photos when saved in the Photos or the Files app. This means the credential is stripped, so no badges can be exchanged as baked images on an iPhone that has been using an operating system for the last few years.

Using Reference Implementations

The Reference Implementation is an 1EdTech implementation of Open Badges 3.0 and Comprehensive Learner Record 2.0 which contains a Issuer, a Displayer and a Host. The reference implementation is written in Java. We provide source code and a hosted version of the tool. Our reference implementation has passed Conformance Certification and is complete with 100% automated tests. Developers can run it locally and develop against this tool. We are working to have this available in multiple languages and common functionality eventually available as libraries. From OB 3.0 and CLR 2.0 on, 1EdTech, with the support of the working group, will be keeping this implementation up-to-date, to have all versions supported.

Source Code is a member-only resource.
Hosted version will be available to the public, with services being a member-only resource.

Conformance and Certification

The Open Badges Specification Conformance and Certification Guide v3.0 covers the specific requirements that implementers must cover in order to achieve certification for a successful implementation of Open Badges 3.0. An accompanying CLR 2.0 guide is forthcoming. Here is a quick summary of the types of services that can be certified.

Certified Roles in Open Badges

Services implementing Open Badges fall into one or more ecosystem roles, depending on their relationship to issued credentials. These roles are named "Issuer", "Host", and "Displayer". Issuer services may also add on API support as an additional optional certification level, whereas API support is required for the other two roles. This recognizes that some issuers deliver signed credentials directly to holders via file downloads or potential integrations with wallet

Issuer: A product that issues Open Badges and transmits them to learners. Certification as an issuer covers whether a well-formed signed OpenBadgeCredential is produced by the tested product.
- Optional API support: Issuers can achieve an additional level of certification for Issuer API support if they can demonstrate successful registration with the reference Host system, authorization code grant flow execution for a test user, and transmission of signed Open Badge(s) to the reference Host system by posting them to the Host API.
Host: A product implementing the server side of the Open Badges API that holds badges on behalf of data subjects or holders and controls API access to them. The Resource Server responds to automatic registration requests, authorization grant flow initiations, and authenticated resource requests via the API endpoints.
Displayer: A product that implements the client side of the Open Badges API. Certification is granted that the product can demonstrate successful registration with the reference Host system, authorization code grant flow execution for a test user, and transmission of signed Open Badge(s) from the reference Host system by making a request for credentials held by a user who completed the authorization flow.

Certified Roles in CLR

Certified CLR 2.0 services require use of the API in the same roles as Open Badges, except that the credentials transmitted over the API must be ClrCredentials meeting the requirements displayed by the test system. Issuer-only certification without API support is not listed as an option for CLR.

Conformance Testing Process

Follow the conformance and certification guide listed in the specification for detailed instructions on conformance. A 1EdTech member organization wishing to submit their product for conformance certification will undergo a semi-automated process, following onscreen instructions to run the tests. Then they submit their test results for review by 1EdTech, and if they successfully meet the requirements, the product will appear in the TrustEd Apps Directory, where consumers may find it under filters for each of the implementation roles they are looking for a product to serve.

1EdTech Conformance Test Suite for Open Badges 3.0

Migrating from OB 2.0, OB 2.1, and CLR 1.0

Open Badges 3.0 and Comprehensive Learner Record 2.0 are major releases, and objects published under these versions are not backwards-compatible

Issuers who use Open Badges 2.0 typically make available standard-compliant endpoints for each Issuer Profile, BadgeClass, and Assertion. In addition to enabling verification of their badge awards, these endpoints often also serve to present human-readable information to clients in HTML when HTML is requested by browsers. Social media networks to which badge awards are shared gather information to display awards from these endpoints as Open Graph Protocol metadata. Exceptions to the pattern of one endpoint per Assertion or BadgeClass occur for implementers who have chosen to use OB 2.0 signed verification for assertions or ephemeral BadgeClass IDs in the urn:uuid namespace.

For any system already using hosted endpoints for these objects, use cases remain within the 3.0 ecosystem to continue that support in addition to delivering these objects compliant with 3.0. In OB 3.0 and CLR 2.0, assertions become OpenBadgeCredentials or AchievementCredentials (an alias), and BadgeClasses become Achievements, which may be more likely to use urn:uuid identifiers. As the ecosystem transitions to support OB 3.0 serialization of these objects, some products will continue to support OB 2.0 representations, so an efficient transition for issuer services likely involves a window of continued support for 2.0 with no breaking changes for clients who rely on it today.

As portable signed credentials, there are now expanded privacy options for learners to control how their data is used and shared. The OB 3.0 and CLR 2.0 releases represent a beginning, but these capabilities will take time and require the launch of new features and new products to deliver on their potential impact. A transition to this generation of specification should be non-destructive but should also move quickly to take advantage of new capabilities.

The recommendations in this guide are intended to identify opportunities for interoperable implementation of of the Open Badges and Comprehensive Learner Record specifications. This serves goals of enabling (a) immediate improvement of last-gen credentials due to next-gen thinking, and (b) gradual technology change.

How to support both OB 2.0 and OB 3.0 as an Issuer

The quickstart in this implementation guide provides an example implementation using a did:web issuer identifier, HTTPS Achievement identifier, and a urn:uuid in the OpenBadgeCredential. Meanwhile, an issuer may wish to avoid breaking support for OB 2.0 to ensure learners can still use their badges in tools that do not yet support the new version. This is possible and can work elegantly to express the relationships between related objects if a few steps are followed. The same achievement data may be exposed in OB 2.0 and OB 3.0/CLR 2.0 formats. It is not advisable to attempt to publish a combined expression of an entity that is compatible with OB 3.0/CLR 2.0 and the previous version formats, but it is possible to express the relationship between related objects using different IDs for the new versions of these specifications.

For example, a related association may be made within an Achievement and the OB 2.0 equivalent BadgeClass that represents the same achievement. The issuer service does not store the data in two separate formats, but it is capable of serializing the data into the relevant formats when requested at different endpoints. It is a helpful hint to include the IRI of the legacy BadgeClass type (but because the term BadgeClass doesn't appear in the OB 3.0 context and the two contexts are not compatible with one another to be applied to the same document, the full IRI https://w3id.org/openbadges#BadgeClass is used here).

{
    "@context": "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "type": ["Achievement", "https://w3id.org/openbadges#BadgeClass"],
    "inLanguage": "en",
    "id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6"
    ...
    "related": [
        {
            "type": [
                "Related",
                "https://w3id.org/openbadges#BadgeClass"
            ],
            "id": "https://example.com/badgeclasses/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
            "version": "Open Badges v2p0"
        },
        {
            "type": ["Related"],
            "id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6/es",
            "inLanguage": "es"
        }
    ]
}

There is an existing OB 2.0 endpoint for a BadgeClass at HTTPS id https://example.com/badgeclasses/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6
Implement the OB 3.0 serialization at an endpoint https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6
This example also shows another entry in the related array, to describe a Spanish translation of the achievement, serialized in OB 3.0 Achievement format.

An OB 2.0 related property could be implemented to make the reverse connection from the OB 2.0 BadgeClass:

{
    "@context": "https://w3id.org/openbadges/v2",
    "type": "BadgeClass",
    "id": "https://example.com/badgeclasses/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
    "related": [{
        "type": ["https://purl.imsglobal.org/spec/vc/ob/vocab.html#Achievement"],
        "id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
        "version": "Open Badges v3p0"
    }]
}

Again, the type IRI is spelled out in full, because Achievement is not defined in the OB 2.0 context.

The issuer profile shown in the quickstart uses a did:web identifier, and the issuer must use an HTTPS identifier for the OB 2.0 hosted profile. Within the 3.0 Profile as embedded in a credential, an otherIdentifier property is described that may be used to link to the 2.0 representation.

Additionally, within the DID Document context, an alsoKnownAs property is available, that may express the HTTPS id of the OB 2.0 representation of the profile.

Example: Issuer profile relation between Open Badges 3.0 and Open Badges 2.0

{
	"@context": [
		"https://www.w3.org/ns/did/v1",
		"https://www.w3.org/ns/credentials/v2",
		"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
	],
	"id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
    "alsoKnownAs": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
    "otherIdentifier": [{
        "type": ["IdentifierEntry"],
        "identifier": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
        "identifierType": "identifier"
    }]
    "name": "Example Institution",
    "url": "https://example.edu",
    "email": "info@example.edu",
}

Within the OB 2.0 representation of the issuer, a reverse link may be made with related, as was done with the BadgeClass

Example: Issuer profile relation between Open Badges 2.0 and Open Badges 3.0

{
    "@context": "https://w3id.org/openbadges/v2",
    "id": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
    "type": "Profile",
    "name": "Example Institution",
    "url": "https://example.com",
    "email": "info@example.com",
    "related": [{
        "type": [
            "https://purl.imsglobal.org/spec/vc/ob/vocab.html#Profile"
        ],
        "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
        "version": "Open Badges v3p0"
    }]
}

And finally, at the level of the OpenBadgeCredential, an association to the original OB 2.0 Assertion may be made using "evidence". The use of "evidence" instead of a more complicated construction with related enables human-readable display of a useful link to the original document in as many cases as possible, by any displayer that supports the concept of evidence.

Example: Upgraded OB 2.0 assertion included within CLR 2.0

{
    "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
    ],
    "id": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130004",
    "type": ["VerifiableCredential", "OpenBadgeCredential"],
    "issuer": {
        "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
        "type": ["Profile"],
        "alsoKnownAs": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
        "otherIdentifier": [{
            "type": ["IdentifierEntry"],
            "identifier": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
            "identifierType": "identifier"
        }],
        "url": "https://example.edu",
        "email": "info@example.edu"
    },
    "validFrom": "2010-01-01T00:00:00Z",
    "name": "Example Competency Badge Issued under OB 2.0",
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "AchievementSubject",
        "achievement": {
            "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
            "type": "Achievement",
            "creator": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile"
            },
            "name": "Example Competency Badge Issued under OB 2.0",
            "criteria": {
                "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
            },
            "description": "This example badge was issued originally as an Open Badges 2.0 assertion",
            "image": {
                "id": "https://example.edu/achievements/sample.png",
                "type": "Image"
            }
        }
    },
    "evidence": [
        {
            "type": ["Evidence", "https://w3id.org/openbadges#Assertion"],
            "id": "https://example.org/ob2/assertions/10481810-e094-4ffe-806f-25de49c87933",
            "name": "Original Open Badges 2.0 assertion for this credential",
            "description": "This credential was originally issued as an Open Badges 2.0 assertion. It has been updated to the latest version for delivery to Verifiable Credentials wallets and verifiers or inclusion within a Comprehensive Learner Record (CLR 2.0)."
        }
    ]
}

Notes about this example:

A new ID is assigned for the upgraded assertion, in this case an urn:uuid identifier
The original badge data, which was expressed as a "hosted" OB 2.0 assertion is linked via the OB 3.0 Evidence.
A strong hint that the evidence item is an OB 2.0 Assertion is the use of the full IRI https://w3id.org/openbadges#Assertion as an additional type for the Evidence item. Consumers should understand that if they desire, they may verify the original using OB 2.0 protocols.
For additional context and human readability of the evidence link, a name and description appear in the Evidence record describing the upgrade process.
As the issuer in this example is the same entity offering credentials in either OB 2.0 or OB 3.0 format, there is a proof expected to be included in this credential.

How to migrate from CLR 1.0 to CLR 2.0

There is less of an ecosystem of consumption for CLR 1.0 than for OB 2.0, and the increased complexity of a CLR makes support for multiple versions more expensive than for Open Badges, so it is not likely to be worth the investment to maintain simultaneous serialization of both formats of packaged records. A CLR 2.0 platform that also serves as the issuer for the OpenBadgeCredentials packaged within the ClrCredential may choose to implement the above backwards-compatibility steps for increased visibility and shareability of the individual achievements. At the level of the CLR, it is likely that new consumption products coming on the scene will implement the capability to process CLR in the new 2.0 format rather than the legacy version.

Migrating to CLR 2.0 involves a replacement of endpoints where CLR 1.0 documents were available with the implementation of the CLR 2.0 API. If there are existing clients or relying parties on the CLR 1.0 representations, the best path is to work with those clients to upgrade to 2.0 representations and transfer via API and then remove the 1.0 endpoints once a 2.0 channel has been established.

Including older Open Badges in CLR 2.0

When Comprehensive Learner Record (CLR) issuers want to include Open Badges issued over time, these credentials must match the expected schema of an OB 3.0 OpenBadgeCredential. But the CLR issuer might have collected them in an older format, such as OB 2.0, which largely expressed the same achievement information, except in a different schema. To ensure that consumers are able to process data included in a CLR efficiently, the CLR issuer may use the technique above to represent the OB 2.0 data in OB 3.0 format with a reference to the original as "evidence".

If the issuer of the CLR is the same as the issuer of the embedded upgraded credentials, they may sign each with their own key, presumably the same used to sign the outer CLR itself. If the original issuer of an embedded credential is another entity, the embedded OpenBadgeCredential may be included without signature. In either case, the related reference back to the original enables consumers or viewers to trace the verification back to the original. The inclusion of the unsigned third party credential implies the CLR issuer's verification or trust of the original. Consumers may perform their own verification of the referenced original OB 2.0 assertion using the OB 2.0 verification protocols.

This approach enables the CLR to meet the schema requirements for CLR 2.0 without leaving behind the millions of achievement assertions issued using previous versions of the Open Badges Specification.

Implementation notes:

If the issuer is the same entity between the OB 2.0 and OB 3.0 versions, the CLR issuer should include a proof for the upgraded credential, but if the issuer is different, the CLR issuer should not include a proof and should expect that interested verifiers could perform OB 2.0 verification based on the assertion linked in Evidence.
An approach for OB 2.0 signed assertions is not included, as these represent less than 1% of all OB 2.0 assertions in existence, but this approach could be modified to work with a signed assertion, perhaps using a data URI to embed the original OB 2.0 compact JWS string.

Open Badges Extensions

Open Badges 3.0 and Comprehensive Learner Record 2.0 allows extensibility in several ways: data model, extensible enumerated vocabularies and API.

Extending the data model enables the addition of supplementary properties to an existing entity.

This process entails the development of two primary artifacts: a JSON-LD context and a JSON schema. This chapter provides guidance on constructing these essential components.

Sample extension

If you, for instance, want to extend Achievement with a couple of fields, what you have to do is:

Let’s suppose you want to extend Achievement with a couple of fields, and decide to name your extension type MyCustomAchievement. The two new fields to add are:

myField of type description (required)
anotherField of type DateTime (optional).

Custom JSON-LD context

The first step is to define a custom JSON-LD context with the added attributes. Following our example extension, it would be as follows:

Example: OB / CLR Extension JSON-LD Context

{
  "@context": {
    "@protected": true,
    "id": "@id",
    "type": "@type",
    "MyCustomAchievement": {
      "@id" : "http://your_url/vocabulary#MyCustomAchievement",
      "@context": {
        "@protected": true,
        "id": "@id",
        "type": "@type",
        "myField": {
          "@id": "https://schema.org/description"
        },
        "anotherField": {
          "@id": "https://your_url/vocabulary#anotherField",
          "@type": "xsd:dateTime"
        }
      }
    }
  }
}

Your credentials MUST include this context in their @context. ie:

Example: Sample Credential with Extension JSON-LD Context

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://your_url/your_context"
  ]
  ...
}

In this example, “https://your_url/your_context” resolves to the above JSON-LD context. Also, the Achievement in your credentials MUST also be of your newly created type. i.e.:

Example: Sample Credential with Extension type

{
  ...
  "credentialSubject": {
    ...
    "achievement": {
      "type": ["Achievement", "MyCustomAchievement"]
      ...
    }
  }
  ...
}

Custom JSON Schema

The next step is to define a custom Define a JSON schema for your new type. Following our example extension, it would be as follows:

Example: OB / CLR Extension JSON Schema

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "$id": "https://your_url/your_schema.json",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "achievement": {
          "type": "object",
          "properties": {
            "myField": {
              "type": "string"
            },
            "anotherField": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": ["myField"],
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Note: Note the existence of additionalProperties to allow fields from another schemas, like the ones 1EdTech provides.

Your credentials MUST include this schema in the credentialSchemaProperty so verifiers can check them against your schema. I.e:

Example: Sample Credential with Extension JSON schema

{
  ...
  "credentialSchema": [{
    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }, {
    "id": "https://your_url/your_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }]
  ...
}

Example Credential

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://your_url/your_context"
  ],
  "id": "http://example.com/credentials/3527",
  "type": ["VerifiableCredential", "OpenBadgeCredential"],
  "issuer": {
    "id": "https://example.com/issuers/876543",
    "type": ["Profile"],
    "name": "Example Corp"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Teamwork Badge",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": ["AchievementSubject"],
    "achievement": {
  			"id": "https://example.com/achievements/21st-century-skills/teamwork",
  			"type": ["Achievement", "MyCustomAchievement"],
  			"criteria": {
  				"narrative": "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management."
  			},
  			"description": "This badge recognizes the development of the capacity to collaborate within a group environment.",
  			"name": "Teamwork",
            "myField": "Put your custom value here."
            "anotherField": "2024-07-24T00.00:00Z"
  		}
  },
  "credentialSchema": [{
    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }, {
    "id": "https://your_url/your_schema.json",
    "type": "1EdTechJsonSchemaValidator2019"
  }]
}

Getting Help

If you have questions or need help with implementing Open Badges 3.0 or Comprehensive Learning Record 2.0, or achieving conformance certification, here are some available resources:

Public Forum for all members of the 1EdTech community.
Affiliate Forum for Learning Tools and Content Alliance, Affiliate, and Contributing Members.
1EdTech Contributing Members have access to private GitHub repositories and a Slack channel for Digital Credentials Project Group discussions and collaborations. Contact an 1EdTech staff member to gain access.
Digital Credentials and Open Badges FAQs If you have a question, an answer may already be waiting. If not, please contact us.

Linked Data Proof Test Vector for Open Badges 3.0

This chapter is an example of the signing process of a given credential with an Linked Data Proof producing a DataIntegrityProof of a public key expressed in eddsa-rdf-2022 format.

Key pair & Multikey

For this example we are using the following keypair:

Public key (hex): 4bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
Private key (hex): 6241a409e6707bb640a0140a8a32bc3d193c33a661747284d6adfa4ed4180be44bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5

{
      id: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
      controller: 'https://example.edu/issuers/565049',
      publicKey: Uint8Array(32) [
         75, 222, 175, 222,  46, 168, 190,
        239, 173, 216, 198, 153, 181, 199,
        224, 112,  76, 245,  17,  84, 213,
         46,  23, 178,  11, 113,  51, 124,
        160,  76, 197, 165
      ],
      secretKey: Uint8Array(64) [
         98,  65, 164,   9, 230, 112, 123, 182,  64, 160,  20,
         10, 138,  50, 188,  61,  25,  60,  51, 166,  97, 116,
        114, 132, 214, 173, 250,  78, 212,  24,  11, 228,  75,
        222, 175, 222,  46, 168, 190, 239, 173, 216, 198, 153,
        181, 199, 224, 112,  76, 245,  17,  84, 213,  46,  23,
        178,  11, 113,  51, 124, 160,  76, 197, 165
      ],
      publicKeyMultibase: 'z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
      secretKeyMultibase: 'zrv2bqTbNwCTsRrHFcJCPjVAduh4Ezcnoq1A3ZxH1GWTNkxipLVuaAoMFmze2gFN9oNXfJjufxSHWVZzsJiUsMHFMcx',
      revoked: undefined,
      export: [AsyncFunction: export],
      signer: [Function: signer],
      verifier: [Function: verifier]
    }

Test data

The credential used in the example is:

{
            "@context": [
                "https://www.w3.org/ns/credentials/v2",
                "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
            ],
            "id": "http://example.com/credentials/3527",
            "type": [
                "VerifiableCredential",
                "OpenBadgeCredential"
            ],
            "issuer": {
                "id": "https://example.edu/issuers/565049",
                "type": [
                "Profile"
                ],
                "url": "https://www.imsglobal.org",
                "name": "Example Corp"
            },
            "validFrom": "2010-01-01T00:00:00Z",
            "name": "Teamwork Badge",
            "credentialSubject": {
                "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
                "type": [
                "AchievementSubject"
                ],
                "achievement": {
                "id": "https://example.com/achievements/21st-century-skills/teamwork",
                "type": [
                    "Achievement"
                ],
                "criteria": {
                    "narrative": "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management."
                },
                "description": "This badge recognizes the development of the capacity to collaborate within a group environment.",
                "name": "Teamwork"
                }
            }
        }

Document before signing

{
            '@context': [
                'https://www.w3.org/ns/credentials/v2',
                'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json'
            ],
            id: 'http://example.com/credentials/3527',
            type: [ 'VerifiableCredential', 'OpenBadgeCredential' ],
            issuer: {
                id: 'https://example.edu/issuers/565049',
                type: [ 'Profile' ],
                url: 'https://www.imsglobal.org',
                name: 'Example Corp'
            },
            validFrom: '2010-01-01T00:00:00Z',
            name: 'Teamwork Badge',
            credentialSubject: {
                id: 'did:example:ebfeb1f712ebc6f1c276e12ec21',
                type: [ 'AchievementSubject' ],
                achievement: {
                id: 'https://example.com/achievements/21st-century-skills/teamwork',
                type: [
                    "Achievement"
                ],
                criteria: {
                    "narrative": "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management."
                },
                description: 'This badge recognizes the development of the capacity to collaborate within a group environment.',
                name: 'Teamwork'
                }
            }
        }

Proof before signing

{
            type: 'DataIntegrityProof',
            created: '2010-01-01T19:23:24Z',
            verificationMethod: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
            cryptosuite: 'eddsa-rdfc-2022',
            proofPurpose: 'assertionMethod'
        }

Proof normalized

_:c14n0 <http://purl.org/dc/terms/created> "2010-01-01T19:23:24Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/security#DataIntegrityProof> .
_:c14n0 <https://w3id.org/security#cryptosuite> "eddsa-rdfc-2022"^^<https://w3id.org/security#cryptosuiteString> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi> .

Document normalized

<did:example:ebfeb1f712ebc6f1c276e12ec21> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#AchievementSubject> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#achievement> <https://example.com/achievements/21st-century-skills/teamwork> .
<http://example.com/credentials/3527> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#OpenBadgeCredential> .
<http://example.com/credentials/3527> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<http://example.com/credentials/3527> <https://schema.org/name> "Teamwork Badge" .
<http://example.com/credentials/3527> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:ebfeb1f712ebc6f1c276e12ec21> .
<http://example.com/credentials/3527> <https://www.w3.org/2018/credentials#issuer> <https://example.edu/issuers/565049> .
<http://example.com/credentials/3527> <https://www.w3.org/2018/credentials#validFrom> "2010-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://example.com/achievements/21st-century-skills/teamwork> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Achievement> .
<https://example.com/achievements/21st-century-skills/teamwork> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Criteria> _:c14n0 .
<https://example.com/achievements/21st-century-skills/teamwork> <https://schema.org/description> "This badge recognizes the development of the capacity to collaborate within a group environment." .
<https://example.com/achievements/21st-century-skills/teamwork> <https://schema.org/name> "Teamwork" .
<https://example.edu/issuers/565049> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Profile> .
<https://example.edu/issuers/565049> <https://schema.org/name> "Example Corp" .
<https://example.edu/issuers/565049> <https://schema.org/url> "https://www.imsglobal.org"^^<https://www.w3.org/2001/XMLSchema#anyURI> .
_:c14n0 <https://purl.imsglobal.org/spec/vc/ob/vocab.html#narrative> "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management." .

Document hash (hex)

87f65a76d40146205e3b3e06cb0fbd153f97f9ce70372390f52566bb7f9e0773

Proof hash (hex)

d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19

Data to sign (hex)

d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d1987f65a76d40146205e3b3e06cb0fbd153f97f9ce70372390f52566bb7f9e0773

Signature (hex)

f7a017acf7d27983267ec362657c0fb08e955549f49dac5bf36a03c4f2c3a4f1e3738a6c5ecd7ffba7135cb9cd754e6196f4b73082ea8df8e703c8ecd4333503

Proof value (hex)

z5x9aCBYovW3CQCbKdNyhEm7ffYSw1YpEdPywQJoNbzDD2gkzQDKJ1sYKJaWvqZtkMtSbz35HcbgXVEDYHxCzgkCr

Proof

{
            "type": "DataIntegrityProof",
            "created": "2010-01-01T19:23:24Z",
            "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
            "cryptosuite": "eddsa-rdfc-2022",
            "proofPurpose": "assertionMethod",
            "proofValue": "z5x9aCBYovW3CQCbKdNyhEm7ffYSw1YpEdPywQJoNbzDD2gkzQDKJ1sYKJaWvqZtkMtSbz35HcbgXVEDYHxCzgkCr"
        }

Signed credential

{
        "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
        ],
        "id": "http://example.com/credentials/3527",
        "type": [
            "VerifiableCredential",
            "OpenBadgeCredential"
        ],
        "issuer": {
            "id": "https://example.edu/issuers/565049",
            "type": [
            "Profile"
            ],
            "url": "https://www.imsglobal.org",
            "name": "Example Corp"
        },
        "validFrom": "2010-01-01T00:00:00Z",
        "name": "Teamwork Badge",
        "credentialSubject": {
            "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
            "type": [
            "AchievementSubject"
            ],
            "achievement": {
            "id": "https://example.com/achievements/21st-century-skills/teamwork",
            "type": [
                "Achievement"
            ],
            "criteria": {
                "narrative": "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management."
            },
            "description": "This badge recognizes the development of the capacity to collaborate within a group environment.",
            "name": "Teamwork"
            }
        },
        "proof": {
            "type": "DataIntegrityProof",
            "created": "2010-01-01T19:23:24Z",
            "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
            "cryptosuite": "eddsa-rdfc-2022",
            "proofPurpose": "assertionMethod",
            "proofValue": "z5x9aCBYovW3CQCbKdNyhEm7ffYSw1YpEdPywQJoNbzDD2gkzQDKJ1sYKJaWvqZtkMtSbz35HcbgXVEDYHxCzgkCr"
        }
    }

Linked Data Proof Test Vector for Comprehensive Learner Record 2.0

Note: The signing process for CLR 2.0 is the same as for OB 3.0. Therefore, the only difference between this chapter and the previous one is the use of a ClrCredential instead of an AchievementCredential as the input data

This chapter is an example of the signing process of a given credential with an Linked Data Proof producing a DataIntegrityProof of a public key expressed in eddsa-rdf-2022 format.

Key pair & Multikey

Public key (hex): 4bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
Private key (hex): 6241a409e6707bb640a0140a8a32bc3d193c33a661747284d6adfa4ed4180be44bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5

{
        id: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
        controller: 'https://example.edu/issuers/565049',
        publicKey: Uint8Array(32) [
            75, 222, 175, 222,  46, 168, 190,
            239, 173, 216, 198, 153, 181, 199,
            224, 112,  76, 245,  17,  84, 213,
            46,  23, 178,  11, 113,  51, 124,
            160,  76, 197, 165
        ],
        secretKey: Uint8Array(64) [
            98,  65, 164,   9, 230, 112, 123, 182,  64, 160,  20,
            10, 138,  50, 188,  61,  25,  60,  51, 166,  97, 116,
            114, 132, 214, 173, 250,  78, 212,  24,  11, 228,  75,
            222, 175, 222,  46, 168, 190, 239, 173, 216, 198, 153,
            181, 199, 224, 112,  76, 245,  17,  84, 213,  46,  23,
            178,  11, 113,  51, 124, 160,  76, 197, 165
        ],
        publicKeyMultibase: 'z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
        secretKeyMultibase: 'zrv2bqTbNwCTsRrHFcJCPjVAduh4Ezcnoq1A3ZxH1GWTNkxipLVuaAoMFmze2gFN9oNXfJjufxSHWVZzsJiUsMHFMcx',
        revoked: undefined,
        export: [AsyncFunction: export],
        signer: [Function: signer],
        verifier: [Function: verifier]
    }

Test data

The credential used in the example is:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "ClrCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "validFrom": "2010-01-01T00:00:00Z",
  "name": "Sample Transcript",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "type": "ClrSubject",
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
          "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
        ],
        "id": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002",
        "type": [
          "VerifiableCredential",
          "AchievementCredential"
        ],
        "issuer": {
          "id": "https://example.edu/issuers/565049",
          "type": "Profile",
          "name": "Example University"
        },
        "validFrom": "2010-01-01T00:00:00Z",
        "name": "Example University Degree",
        "credentialSubject": {
          "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
          "type": "AchievementSubject",
          "achievement": {
            "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
            "type": "Achievement",
            "creator": {
              "id": "https://example.edu/issuers/565049",
              "type": "Profile"
            },
            "name": "Achievement 1",
            "criteria": {
              "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
            },
            "description": "Achievement 1",
            "image": {
              "id": "https://example.edu/achievements/sample.png",
              "type": "Image"
            }
          }
        },
        "credentialSchema": [
          {
            "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
            "type": "1EdTechJsonSchemaValidator2019"
          }
        ],
        "proof": [
          {
            "type": "DataIntegrityProof",
            "created": "2010-01-01T19:23:24Z",
            "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
            "cryptosuite": "eddsa-rdfc-2022",
            "proofPurpose": "assertionMethod",
            "proofValue": "z45QnLySMt2mWuW787G6cf3SLkP97ZkMZxLeXH5yaaTQPCtTup4GCV95tU8HEnQJSyGCokSj3AvUhmJtvveTmN4Vu"
          }
        ]
      }
    ],
    "achievement": [
      {
        "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
        "type": "Achievement",
        "creator": {
          "id": "https://example.edu/issuers/565049",
          "type": "Profile"
        },
        "name": "Achievement 1",
        "criteria": {
          "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
        },
        "description": "Achievement 1",
        "image": {
          "id": "https://example.edu/achievements/sample.png",
          "type": "Image"
        }
      },
      {
        "id": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002",
        "type": "Achievement",
        "creator": {
          "id": "https://example.edu/issuers/565049",
          "type": "Profile"
        },
        "name": "Achievement 2",
        "criteria": {
          "id": "https://example.edu/achievements/dd887f0a-56cb-11ec-bf63-0242ac130002/criteria"
        },
        "description": "Achievement 2",
        "image": {
          "id": "https://example.edu/achievements/sample.png",
          "type": "Image"
        }
      }
    ],
    "association": [
      {
        "type": "Association",
        "associationType": "isParentOf",
        "sourceId": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
        "targetId": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002"
      }
    ]
  },
  "credentialSchema": [
    {
      "id": "https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json",
      "type": "1EdTechJsonSchemaValidator2019"
    }
  ]
}

Document before signing

{
        "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
        ],
        "id": "http://example.edu/credentials/3732",
        "type": [
            "VerifiableCredential",
            "ClrCredential"
        ],
        "issuer": {
            "id": "https://example.edu/issuers/565049",
            "type": "Profile",
            "name": "Example University"
        },
        "validFrom": "2010-01-01T00:00:00Z",
        "name": "Sample Transcript",
        "credentialSubject": {
            "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
            "type": "ClrSubject",
            "verifiableCredential": [
            {
                "@context": [
                "https://www.w3.org/ns/credentials/v2",
                "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
                "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
                ],
                "id": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002",
                "type": [
                "VerifiableCredential",
                "AchievementCredential"
                ],
                "issuer": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile",
                "name": "Example University"
                },
                "validFrom": "2010-01-01T00:00:00Z",
                "name": "Example University Degree",
                "credentialSubject": {
                "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
                "type": "AchievementSubject",
                "achievement": {
                    "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                    "type": "Achievement",
                    "creator": {
                    "id": "https://example.edu/issuers/565049",
                    "type": "Profile"
                    },
                    "name": "Achievement 1",
                    "criteria": {
                    "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
                    },
                    "description": "Achievement 1",
                    "image": {
                    "id": "https://example.edu/achievements/sample.png",
                    "type": "Image"
                    }
                }
                },
                "credentialSchema": [
                {
                    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
                    "type": "1EdTechJsonSchemaValidator2019"
                }
                ],
                "proof": [
                {
                    "type": "DataIntegrityProof",
                    "created": "2010-01-01T19:23:24Z",
                    "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
                    "cryptosuite": "eddsa-rdfc-2022",
                    "proofPurpose": "assertionMethod",
                    "proofValue": "z45QnLySMt2mWuW787G6cf3SLkP97ZkMZxLeXH5yaaTQPCtTup4GCV95tU8HEnQJSyGCokSj3AvUhmJtvveTmN4Vu"
                }
                ]
            }
            ],
            "achievement": [
            {
                "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                "type": "Achievement",
                "creator": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile"
                },
                "name": "Achievement 1",
                "criteria": {
                "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
                },
                "description": "Achievement 1",
                "image": {
                "id": "https://example.edu/achievements/sample.png",
                "type": "Image"
                }
            },
            {
                "id": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002",
                "type": "Achievement",
                "creator": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile"
                },
                "name": "Achievement 2",
                "criteria": {
                "id": "https://example.edu/achievements/dd887f0a-56cb-11ec-bf63-0242ac130002/criteria"
                },
                "description": "Achievement 2",
                "image": {
                "id": "https://example.edu/achievements/sample.png",
                "type": "Image"
                }
            }
            ],
            "association": [
            {
                "type": "Association",
                "associationType": "isParentOf",
                "sourceId": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                "targetId": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002"
            }
            ]
        },
        "credentialSchema": [
            {
            "id": "https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json",
            "type": "1EdTechJsonSchemaValidator2019"
            }
        ]
    }

Proof before signing

{
        type: 'DataIntegrityProof',
        created: '2010-01-01T19:23:24Z',
        verificationMethod: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
        cryptosuite: 'eddsa-rdfc-2022',
        proofPurpose: 'assertionMethod'
    }

Proof normalized

_:c14n0 <http://purl.org/dc/terms/created> "2010-01-01T19:23:24Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/security#DataIntegrityProof> .
_:c14n0 <https://w3id.org/security#cryptosuite> "eddsa-rdfc-2022"^^<https://w3id.org/security#cryptosuiteString> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi> .

Document normalized

<did:example:ebfeb1f712ebc6f1c276e12ec21> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#ClrSubject> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#AchievementSubject> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#achievement> <urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#achievement> <urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#association> _:c14n2 .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#verifiableCredential> <urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> .
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#achievement> <urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> .
<http://example.edu/credentials/3732> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#ClrCredential> .
<http://example.edu/credentials/3732> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<http://example.edu/credentials/3732> <https://schema.org/name> "Sample Transcript" .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#credentialSchema> <https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:ebfeb1f712ebc6f1c276e12ec21> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#issuer> <https://example.edu/issuers/565049> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#validFrom> "2010-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://example.edu/achievements/sample.png> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Image> .
<https://example.edu/issuers/565049> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Profile> .
<https://example.edu/issuers/565049> <https://schema.org/name> "Example University" .
<https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vccs/v1p0/context.json#1EdTechJsonSchemaValidator2019> .
<https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vccs/v1p0/context.json#1EdTechJsonSchemaValidator2019> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#OpenBadgeCredential> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://schema.org/name> "Example University Degree" .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://w3id.org/security#proof> _:c14n1 .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://www.w3.org/2018/credentials#credentialSchema> <https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:ebfeb1f712ebc6f1c276e12ec21> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://www.w3.org/2018/credentials#issuer> <https://example.edu/issuers/565049> .
<urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002> <https://www.w3.org/2018/credentials#validFrom> "2010-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Achievement> .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Criteria> <https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria> .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#creator> <https://example.edu/issuers/565049> .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#image> <https://example.edu/achievements/sample.png> .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <https://schema.org/description> "Achievement 1" .
<urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002> <https://schema.org/name> "Achievement 1" .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Achievement> .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#Criteria> <https://example.edu/achievements/dd887f0a-56cb-11ec-bf63-0242ac130002/criteria> .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#creator> <https://example.edu/issuers/565049> .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <https://purl.imsglobal.org/spec/vc/ob/vocab.html#image> <https://example.edu/achievements/sample.png> .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <https://schema.org/description> "Achievement 2" .
<urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002> <https://schema.org/name> "Achievement 2" .
_:c14n0 <http://purl.org/dc/terms/created> "2010-01-01T19:23:24Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> _:c14n1 .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/security#DataIntegrityProof> _:c14n1 .
_:c14n0 <https://w3id.org/security#cryptosuite> "eddsa-rdfc-2022"^^<https://w3id.org/security#cryptosuiteString> _:c14n1 .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> _:c14n1 .
_:c14n0 <https://w3id.org/security#proofValue> "z45QnLySMt2mWuW787G6cf3SLkP97ZkMZxLeXH5yaaTQPCtTup4GCV95tU8HEnQJSyGCokSj3AvUhmJtvveTmN4Vu"^^<https://w3id.org/security#multibase> _:c14n1 .
_:c14n0 <https://w3id.org/security#verificationMethod> <https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi> _:c14n1 .
_:c14n2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://purl.imsglobal.org/spec/vc/clr/vocab.html#Association> .
_:c14n2 <https://purl.imsglobal.org/spec/vc/clr/vocab.html#AssociationType> "isParentOf" .
_:c14n2 <https://purl.imsglobal.org/spec/vc/clr/vocab.html#sourceId> "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002"^^<xsd:anyURI> .
_:c14n2 <https://purl.imsglobal.org/spec/vc/clr/vocab.html#targetId> "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002"^^<xsd:anyURI> .

Document hash (hex)

768d7015ae69e0210e1c2a45194d9c1d15d7a6022e52b946574a2a27f6fa85fe

Proof hash (hex)

d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19

Data to sign (hex)

d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19768d7015ae69e0210e1c2a45194d9c1d15d7a6022e52b946574a2a27f6fa85fe

Signature (hex)

0c220dadbcfcaa64ab8a8c5002dbe258e6c7746ca71c25e2ea3b7fbffd66568413f53b1d34f5655f3057864bd372bbf0d1e74ea2f8c72e2f4b5790f21a22b70a

Proof value (hex)

zF52sU1nfPAjcwCqtgxPNSor6SJnAzRBwZW5VNQXPt8xXCHkd39sgqj32DnMjhFCzbyHsLkhQ8HpBqQTkMgXy329

Proof

{
        "type": "DataIntegrityProof",
        "created": "2010-01-01T19:23:24Z",
        "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
        "cryptosuite": "eddsa-rdfc-2022",
        "proofPurpose": "assertionMethod",
        "proofValue": "zF52sU1nfPAjcwCqtgxPNSor6SJnAzRBwZW5VNQXPt8xXCHkd39sgqj32DnMjhFCzbyHsLkhQ8HpBqQTkMgXy329"
    }

Signed credential

{
        "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
        ],
        "id": "http://example.edu/credentials/3732",
        "type": [
            "VerifiableCredential",
            "ClrCredential"
        ],
        "issuer": {
            "id": "https://example.edu/issuers/565049",
            "type": "Profile",
            "name": "Example University"
        },
        "validFrom": "2010-01-01T00:00:00Z",
        "name": "Sample Transcript",
        "credentialSubject": {
            "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
            "type": "ClrSubject",
            "verifiableCredential": [
            {
                "@context": [
                "https://www.w3.org/ns/credentials/v2",
                "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
                "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json"
                ],
                "id": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002",
                "type": [
                "VerifiableCredential",
                "AchievementCredential"
                ],
                "issuer": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile",
                "name": "Example University"
                },
                "validFrom": "2010-01-01T00:00:00Z",
                "name": "Example University Degree",
                "credentialSubject": {
                "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
                "type": "AchievementSubject",
                "achievement": {
                    "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                    "type": "Achievement",
                    "creator": {
                    "id": "https://example.edu/issuers/565049",
                    "type": "Profile"
                    },
                    "name": "Achievement 1",
                    "criteria": {
                    "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
                    },
                    "description": "Achievement 1",
                    "image": {
                    "id": "https://example.edu/achievements/sample.png",
                    "type": "Image"
                    }
                }
                },
                "credentialSchema": [
                {
                    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json",
                    "type": "1EdTechJsonSchemaValidator2019"
                }
                ],
                "proof": [
                {
                    "type": "DataIntegrityProof",
                    "created": "2010-01-01T19:23:24Z",
                    "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
                    "cryptosuite": "eddsa-rdfc-2022",
                    "proofPurpose": "assertionMethod",
                    "proofValue": "z45QnLySMt2mWuW787G6cf3SLkP97ZkMZxLeXH5yaaTQPCtTup4GCV95tU8HEnQJSyGCokSj3AvUhmJtvveTmN4Vu"
                }
                ]
            }
            ],
            "achievement": [
            {
                "id": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                "type": "Achievement",
                "creator": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile"
                },
                "name": "Achievement 1",
                "criteria": {
                "id": "https://example.edu/achievements/a7467ef6-56cb-11ec-bf63-0242ac130002/criteria"
                },
                "description": "Achievement 1",
                "image": {
                "id": "https://example.edu/achievements/sample.png",
                "type": "Image"
                }
            },
            {
                "id": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002",
                "type": "Achievement",
                "creator": {
                "id": "https://example.edu/issuers/565049",
                "type": "Profile"
                },
                "name": "Achievement 2",
                "criteria": {
                "id": "https://example.edu/achievements/dd887f0a-56cb-11ec-bf63-0242ac130002/criteria"
                },
                "description": "Achievement 2",
                "image": {
                "id": "https://example.edu/achievements/sample.png",
                "type": "Image"
                }
            }
            ],
            "association": [
            {
                "type": "Association",
                "associationType": "isParentOf",
                "sourceId": "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002",
                "targetId": "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002"
            }
            ]
        },
        "credentialSchema": [
            {
            "id": "https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json",
            "type": "1EdTechJsonSchemaValidator2019"
            }
        ],
        "proof": [{
            "type": "DataIntegrityProof",
            "created": "2010-01-01T19:23:24Z",
            "verificationMethod": "https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi",
            "cryptosuite": "eddsa-rdfc-2022",
            "proofPurpose": "assertionMethod",
            "proofValue": "zF52sU1nfPAjcwCqtgxPNSor6SJnAzRBwZW5VNQXPt8xXCHkd39sgqj32DnMjhFCzbyHsLkhQ8HpBqQTkMgXy329"
        }]
    }

IP Disclosures

The following participating organizations have made explicit license commitments to this specification:

Organization Name	Date election made	Necessary claims	Type
Concentric Sky	2019-10-24	No	RF RAND (Required & Optional Elements)
Arizona State University	2022-06-21	No	RF RAND (Required & Optional Elements)
Temple University	2022-06-10	No	RF RAND (Required & Optional Elements)
Credly	2019-10-03	No	RF RAND (Required & Optional Elements)
Workday, Inc.	2022-06-10	No	RF RAND (Required & Optional Elements)
RANDA Solutions	2022-06-09	No	RF RAND (Required & Optional Elements)
Anthology	2024-04-16	No	RF RAND (Required & Optional Elements)
Unicon	2024-04-22	No	RF RAND (Required & Optional Elements)
Bowdoin College	2022-06-11	No	RF RAND (Required & Optional Elements)
American Association of Collegiate Registrars and Admissions Officers (AACARO)	2024-04-15	No	RF RAND (Required & Optional Elements)
Desire to Learn (D2L)	2024-04-16	No	RF RAND (Required & Optional Elements)
Digital Knowledge EdTech Lab Inc.	2024-04-24	No	RF RAND (Required & Optional Elements)
IQC Italian Quality Company	2024-04-19	No	RF RAND (Required & Optional Elements)
Skybridge Skills	2024-04-16	No	RF RAND (Required & Optional Elements)
Navigatr	2024-04-25	No	RF RAND (Required & Optional Elements)
T3 Innovation Network, US Chamber of Commerce Foundation	2024-04-25	No	RF RAND (Required & Optional Elements)
Territorium	2024-04-23	No	RF RAND (Required & Optional Elements)
Western Governors University (WGU)	2022-06-11	No	RF RAND (Required & Optional Elements)

List of Contributors

The following individuals contributed to the development of this document:

Name	Affiliation	Role
Nate Otto	Skybridge Skills	Invited Expert
Justin Pitcher	Anthology	Co-chair, OB
Xavi Aracil	1Edtech	Editor
Rob Coyle	1Edtech	Editor

Revision History

Version	Date	Comments
Version 3.0 IMS Candidate Final	2022-11-10	Covers Issuer, Displayer, and Host conformance and certification.
Version 3.0 IMS Candidate Final	2023-06-20	Updated Linked Data Proof to the new EdDSA Cryptosuite v2022 [[VC-DI-EDDSA]].
Version 3.0 IMS Candidate Final	2023-07-14	New version of the context.json (`context-3.0.2.json`) file. See [[OB-ERRATA-30]] for detailed changes
Version 3.0 IMS Candidate Final	2023-09-08	Reorganized some sections of the document to highlight Issuer, Displayer and Host roles.\nAdded recommended practice for including additional info of the recipient of a credential.\nAdded recommended practice for supporting old cryptosuites.\nAdded test vector data for signing Open Badges and Comprehensive Learner Record.
Version 3.0 IMS Candidate Final	2023-09-22	Added a section about including older Open Badges in CLR 2.0.
Version 3.0 IMS Candidate Final	2023-11-09	Added a section about issuer's key provenance.
Version 3.0 IMS Candidate Final	2023-12-13	New version of the context.json (`context-3.0.3.json`) file. See [[OB-ERRATA-30]] for detailed changes
Version 3.0 IMS Candidate Final	2023-12-15	Added sections about alignment of achievements with non-1EdTech vocabularies, such Credential Engine.
Version 3.0 IMS Candidate Final	2023-01-26	Language of related achievement now uses the new attribute `inLanguage` instead of `@language`.
Version 3.0 IMS Candidate Final	2024-04-02	Upgraded to [[VC-DATA-MODEL-2.0]]
Version 3.0 IMS Candidate Final	2024-10-01	Added section about extensions.\nAdded section about privacy.
Final Release	2024-12-23	Clarified proof mechanism and algorithm selection.
Final Release	2025-02-12	Reorganization.\nClarified some paragraphs.
Final Release	2025-04-07	Fixed some typos.

Open Badges Implementation Guide

Introduction

Overview

Spec documents (Normative References)

Audiences

OB Overview

CLR Overview

Use Cases

OB/CLR in the 1EdTech Ecosystem

Relationship between Verifiable Credentials and OB/CLR

Getting Started (for Developers)

Issuer quickstart

API quickstart

Consumer basics

Example: Sample getServiceDescription request

Example: Sample getServiceDescription response

Example: Sample registration request

Example: Sample ACG authorization request (line breaks for clarity)

Example: Sample ACG token request (line breaks for clarity)

Example: Sample ACG token response

User stories for an issuer (API consumer) and host (API provider)

Provider basics

Supporting Technical Resources

Recommended Practices

Issuer

Selecting recipient and issuer identifiers, such as DID methods

Selecting proof methods and crypto algorithms

Publishing Achievement definitions and selecting Achievement identifiers

Managing credential status and revocation

Alignment with CASE items

Example: Achievement alignment (CASE)

Alignment with a ceterms:Credential resource

Example: Achievement alignment to more information about the Credential (ceterms:Credential)

Alignment with a ceasn:Competency resource

Example: Achievement alignment to a competency (ceasn:Competency)

Alignment with a CTDL resource

Example: Achievement alignment to another type of entity (CTDL)

Skills

Example: Skill Assertion (Credential Registry)

Including additional recipient profile information

Example: Email identifier in credential subject

Example: Name identifier in credential subject

Example: Given name and family name credential subject with Profile

Embedding Evidences

Key provenance

Linked Data proof

External proof

Issuing platforms with multiple issuers

JWK Set endpoint

Privacy

Privacy of grades and evidence

Context of grades

Evidence documents

Displayer

Cryptosuites in Linked Data Proofs

Key provenance and issuer identity information

Linked Data proof

External proof

Verifiable Credentials v1.1

Changes

Verification

Host

Open Badges 3.0 API recommendations

CLR 2.0 API recommendations

Protocols for connection to Verifiable Credentials Wallets

Sharing Open Badges and CLR Links as URLs and to Social Media

Baked badges and iOS devices

Using Reference Implementations

Conformance and Certification

Certified Roles in Open Badges

Certified Roles in CLR

Conformance Testing Process

Migrating from OB 2.0, OB 2.1, and CLR 1.0

How to support both OB 2.0 and OB 3.0 as an Issuer

Example: OpenBadges 3.0 Achievement with linked OpenBadges 2.0 BadgeClass via related association

Example: OpenBadges 2.0 with related OpenBadges 3.0

Example: Issuer profile relation between Open Badges 3.0 and Open Badges 2.0

Example: Issuer profile relation between Open Badges 2.0 and Open Badges 3.0

Example: Upgraded OB 2.0 assertion included within CLR 2.0

How to migrate from CLR 1.0 to CLR 2.0

Publishing `Achievement` definitions and selecting `Achievement` identifiers