Open Badges 3.0 Implementation Guide | IMS Global Learning Consortium

Open Badges 3.0 Implementation Guide | IMS Global Learning Consortium
You are here
Specifications
Open Badges
Open Badges 3.0 Implementation Guide
Abstract
Conformance Statements
This document is an informative resource in the Document Set of the Open Badges Specification specification
OB-30
].
As such, it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance criteria for implementors of this specification.
1.
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.
1.1
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
1.1.1
Spec documents (Normative References)
The full set of documents is comprised of the following documents:
Open Badges Specification v3.0
Open Badges Specification Conformance and Certification Guide v3.0
Comprehensive Learner Record Standard v2.0
Comprehensive Learner Record Standard Conformance and Certification Guide v2.0
1.1.2
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.
1.2
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
1.3
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.
1.4
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 (not yet published)
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
1.5
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
IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0
'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-11
] or
Edu-API Specification Specification v1.0
EDUAPI-10
].
Moreover, the learner who the credential is issued to can have a relationship
with the
User
entity in [
OR-11
] or the
Person
entity in [
EDUAPI-10
], as
well.
Also, [
OR-11
] 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.
1.6
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.
2.
Getting Started (for Developers)
This section is non-normative.
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.
2.1
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
. 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
. 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
2.2
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.
2.2.1
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
RFC7591
]. 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 [
SEC-11
]. 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) [
RFC7636
] 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"
2.2.2
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 [
RFC7591
] 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
2.2.3
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).
2.3
Supporting Technical Resources
OpenAPI 3.0 JSON File for Open Badges API
OpenAPI 3.0 YAML File for Open Badges API
Open Badges 3.0 JSON-LD Context File
3.
Recommended Practices
This section is non-normative.
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.
3.1
Issuer
3.1.1
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.
3.1.2
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.
3.1.3
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.
3.1.4
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 Revocation List Status Method
accompanies the OB and CLR specifications. This enables
verifiers to query for status results without revealing to the issuer which
specific credential's status is being checked. It does reveal to the
requester a list of credential IDs claimed by the issuer to be associated
with it, though it is not assumed to be exhaustive or accurate except to
indicate the status of the credential known to the requester, because
issuers may use multiple lists concurrently, packaged with different sets of
credentials and red herrings may appear in some lists. The 1EdTech
certification process and validator software will support this status
checking method. A reason for revocation may be available for a revoked
credential.
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.
Another option in the space is the
Credential Status List 2021
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.
3.1.5
Alignment with CASE items
IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0
CASE-10
] specification defines how systems exchange and manage
information about learning standards and/or competencies in a consistent and
referenceable way.
CASE-10
] 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)
Credential
Verifiable Credential (with proof)
Verifiable Credential (as JWT)
"@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"
"@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": "2025-04-07T11:02:00Z",
"verificationMethod": "https://example.edu/issuers/565049#z6MkhaGm1fU59R83zabMW1n35AGRTDC2P7Po5d41EaBqLwaJ",
"cryptosuite": "eddsa-rdfc-2022",
"proofPurpose": "assertionMethod",
"proofValue": "z4zEob2HqUvRWJXbqb42RboG4MsirWpYUQZYCSMwvmE6MgsazofATUtK9GcXemqQttc3o9HcfaFTX4FFEb3NdUC71"
---------------- JWT header ---------------
"alg": "RS256",
"typ": "JWT",
"jwk": {
"e": "AQAB",
"kty": "RSA",
"n": "6Ea7QVymlZ75qc7XKidUPGGDCTOdTXubsYohbVpn07zmgFviCPLP6g7E447pFz-xWG1Uy9
1N2mltCRJSXjr45aYoy_T00B37sELRqVS4PgD5YDH0r1_FIMAmTL6cHEdV2ALAaUwnTqzVdf7duYxGig
wYQFNurr2kup-MGJL0T4JZOzKF1wqxbVGEN2eVVLYW8W7Xw8gVNsNXnn8yFEisClO2e74HcXMpi2t13Z
ArUcsRutFFxelydGbOYZ0mw_rG-IPE6VwYpd62SOPeB9lgsv5FqB1C1QJAME2HacJfD0XLb09f2IIWF1
GPa6_SYimfLcmGf1EGwvvUvwhuOhdljw"
--------------- 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 ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiI2RWE3UVZ5bWxaNzVxYzdYS2lkVVBHR0RDVE9kVFh1YnNZb2hiVnBuMDd6bWdGdmlDUExQNmc3RTQ0
N3BGei14V0cxVXk5MU4ybWx0Q1JKU1hqcjQ1YVlveV9UMDBCMzdzRUxScVZTNFBnRDVZREgwcjFfRklN
QW1UTDZjSEVkVjJBTEFhVXduVHF6VmRmN2R1WXhHaWd3WVFGTnVycjJrdXAtTUdKTDBUNEpaT3pLRjF3
cXhiVkdFTjJlVlZMWVc4VzdYdzhnVk5zTlhubjh5RkVpc0NsTzJlNzRIY1hNcGkydDEzWkFyVWNzUnV0
RkZ4ZWx5ZEdiT1laMG13X3JHLUlQRTZWd1lwZDYyU09QZUI5bGdzdjVGcUIxQzFRSkFNRTJIYWNKZkQw
WExiMDlmMklJV0YxR1BhNl9TWWltZkxjbUdmMUVHd3Z2VXZ3aHVPaGRsancifX0.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.PQVhdSV-fTv8xTP1Val747a1B_mqkEgJqPC7IYExSa9qZH9uhg6wAApyclFBqWkdTIB6W
iZZuzlFvfBTGDgb1bf1Il03-525K24IFaAZ-wwo4xKUzNbTpH7I4u21aUdt3Gzaj9qna-8ruHmuIY8wh
wTqc22-MhJgIFE0v3aRkcr1xnGJmpvDhSI_GJkwfcd25q0L-kUPQdAkESFw_JRB9A0uK8DlylT1gbF8k
9I9X1uSoSDMJdBC_O-trOzbbvlexsPDv0DH8I3ryEK-PqmEdCHTgtG6guQaZU2RFnAxod4tgCdUovpCL
JzENCamr7OYewMgbsadZaXzNryB8r5bSQ
3.1.6
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
), 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"
3.1.7
Alignment with a ceasn:Competency 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.
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"
3.1.8
Alignment with a CTDL 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.
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
10
: 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"
3.1.9
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
11
: Skill Assertion (Credential Registry)
Credential
Verifiable Credential (with proof)
Verifiable Credential (as JWT)
"@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"
"@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": "2025-04-07T11:02:00Z",
"verificationMethod": "https://1edtech.edu/issuers/565049#z6MkqCS8hzKxwozbB4km8XbthJ998iEZLSUzccqAF1FAR4Pf",
"cryptosuite": "eddsa-rdfc-2022",
"proofPurpose": "assertionMethod",
"proofValue": "z3N1KAXYCwdZpNqHZaYbBCakJBSPyKb9FBRuVAGNvRmrDWQCaXzd27kTPZu3f6cLY13PEYts3EkaiivM9pjk4iQBJ"
---------------- JWT header ---------------
"alg": "RS256",
"typ": "JWT",
"jwk": {
"e": "AQAB",
"kty": "RSA",
"n": "sDIIX5ZsMz8lvca8dzN8jR0L1noFgBLO-XoWQ_9F4vdlleDLpThcYDq_JIIhdrH81Z5tvn
KKE5HNx4ffXo_KKPGCukkIwDSvAyIzohKelxqoXOBqVnkjgAq4YVZEx2ksYC2Duvmm_582kSMevzNDdh
F80HWMrKbcyuc87d5WOXDlt5bKnBJ4tkFbXur_AHydHoKkGy5xaS8RWX1bJ2Isqp9MHO1eiDqMoav-S8
3EVXNjBaSXHrDEyKCM7sJILmMAoRLVFwIz3V7INh5FxqE0Jr2Hq2NNsvyJdI1vF_XRzThoIXbRrsI-8z
fjDv1r9q-PsM2ktgy7tJtC-2FAg1GViQ"
--------------- 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 ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiJzRElJWDVac016OGx2Y2E4ZHpOOGpSMEwxbm9GZ0JMTy1Yb1dRXzlGNHZkbGxlRExwVGhjWURxX0pJ
SWhkckg4MVo1dHZuS0tFNUhOeDRmZlhvX0tLUEdDdWtrSXdEU3ZBeUl6b2hLZWx4cW9YT0JxVm5ramdB
cTRZVlpFeDJrc1lDMkR1dm1tXzU4MmtTTWV2ek5EZGhGODBIV01yS2JjeXVjODdkNVdPWERsdDViS25C
SjR0a0ZiWHVyX0FIeWRIb0trR3k1eGFTOFJXWDFiSjJJc3FwOU1ITzFlaURxTW9hdi1TODNFVlhOakJh
U1hIckRFeUtDTTdzSklMbU1Bb1JMVkZ3SXozVjdJTmg1RnhxRTBKcjJIcTJOTnN2eUpkSTF2Rl9YUnpU
aG9JWGJScnNJLTh6ZmpEdjFyOXEtUHNNMmt0Z3k3dEp0Qy0yRkFnMUdWaVEifX0.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.H5q
EScAgcvXLovP3MEFvqHTC7-93ib-DBbta708Bm8C3TaRxJHwEa434vMgkFLnAQtX8XbUJAAQ0J8k-tGL
TvUNDkEbsRG6oNbzl9VxvCrm_6XFnSfDf0yL3058SulmgttGvYFSUf_dAVPKwiROaiQKeGlogBvLxXtO
M06xyxThN5GDhwx7ixBd-bgnGkRcYOo7zdXqUikNSOduYvMW6HJyZtPehtkIP5e6qnQ727QsUZ86wCiW
-ODyoDFn47AXXy4Z7ilXlBt7tUnBJCGGs8oJGD3ATJOXJ7WfgLbBfyXYNA2HiHgf_WXKsUSJd4oFocLi
XYHjR2XTfA_rgdf_0Ww
3.1.10
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
12
: 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
13
: 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
14
: Given name and family name credential subject with Profile
"credentialSubject"
"id"
"did:example:ebfeb1f712ebc6f1c276e12ec21"
"type"
"AchievementSubject"
"Profile"
"givenName"
"Albert"
"familyName"
"Exampleton"
3.1.11
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.
3.1.12
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.
3.1.12.1
Linked Data proof
Linked Data Proofs defines a method to get the public key (via
verificationMethod
) which, as defined by [
VC-DATA-INTEGRITY
], implies the
dereference of a controller document.
Section 2.6 of [
VC-DATA-INTEGRITY
] 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.
3.1.12.2
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)
RFC7517
]. This set, following this recommendation, should be publicly
accessible via the well-known url:
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 [
SEC-11
] 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.
3.1.12.2.1
Issuing platforms with multiple issuers
RFC7517
] 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
3.1.12.3
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.
3.2
3.2.1
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.
3.2.2
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.
3.2.3
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”).
3.3
Displayer
3.3.1
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
3.3.2
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.
3.3.2.1
Linked Data proof
Linked Data Proofs defines a method to get the public key (via
verificationMethod
) which, as defined by [
VC-DATA-INTEGRITY
], implies the
dereference of a controller document.
Section 2.6 of [
VC-DATA-INTEGRITY
] 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.
3.3.2.2
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.
Section 6.3.1 of [
VC-JOSE-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
RFC7515
].
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
([
RFC3986
]):
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
Note
The credential should be considered invalid and not trustworthy if the
key provenance cannot be verified via the method described above.
3.3.3
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 [
OB-30
] and [
CLR-20
], 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 [
OB-30
] and [
CLR-20
] 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 [
OB-30
] and
CLR-20
] 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.
3.3.3.1
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
, in version 2.0 is
. Also, when signing with Linked Data
Proofs, version 1.1 required the addition of the context
. 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.
Note
This chapter resumes the changes between versions of the W3C's VC specification
that have impact in [
OB-30
] and [
CLR-20
]. Please refer to official
documents for an exhausting list of changes between these versions.
3.3.3.2
Verification
Displayers must be able to verify
OpenBadgeCredential
s and
ClrCredential
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:
, for
Verifiable Credentials Data Model v1.1
, 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
VC-DATA-MODEL
] or [
VC-DATA-MODEL-2.0
].
These schemas are:
OB 3.0:
CLR 2.0:
The specifications also provide JSON schemas supporting this duality for
EndorsementCredential
's:
OB 3.0:
CLR 2.0:
3.4
Host
3.4.1
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.
3.4.2
CLR 2.0 API recommendations
As
ClrCredential
s 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.
3.4.3
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
OpenBadgeCredential
s. 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.
3.5
Sharing Open Badges and CLR Links as URLs and to Social Media
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.
3.5.1
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.
4.
Using Reference Implementations
This section is non-normative.
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.
5.
Conformance and Certification
This section is non-normative.
The [
OB-CERT-30
] 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.
5.1
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.
5.2
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
ClrCredential
s meeting the requirements displayed by the test system.
Issuer-only certification without API support is not listed as an option for
CLR.
5.3
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
6.
Migrating from OB 2.0, OB 2.1, and CLR 1.0
This section is non-normative.
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.
6.1
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
is used here).
Example
15
: OpenBadges 3.0 Achievement with linked OpenBadges 2.0 BadgeClass via related association
"@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
Implement the OB 3.0 serialization at an endpoint
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:
Example
16
: OpenBadges 2.0 with related OpenBadges 3.0
"@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
17
: 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
18
: 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
19
: Upgraded OB 2.0 assertion included within CLR 2.0
Credential
Verifiable Credential (with proof)
Verifiable Credential (as JWT)
"@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)."
undefined
---------------- JWT header ---------------
"alg": "RS256",
"typ": "JWT",
"jwk": {
"e": "AQAB",
"kty": "RSA",
"n": "tPjXXi8Zz2cs6TtpJ7MyLnxrn9PGeDaV_Gp9zKoBg4AFtU_f7WaWUyrRgOVRRYD6hlad2f
kq-0F767heXlmAPvvtZRfT77PN-9tgnZl79tbq01RhN1-q0r1mzpV6rFBiqHKXIyuFGSxCqFoL-bDKZ9
NiWufwt5qSFMt9eUaztuoIA0aSeB3FrlwMoQZV2cSLpTnAQhVCm8Sfw-1oa1PH4EBM_FZriuJbZFUen8
UX3b3JDOmqA4-h2YrHroV9Z6dMZyE54ZWWcKGhEHVAIYCMjt2MIyFimABEBKbVvGSlM3fCxGFE5juEhT
T3MF7B0aEbsS1ShUrF7vRQSx2-xKoirQ"
--------------- 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": "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-801
42801c774",
"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-0242ac13
0002/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-25de49c8
7933",
"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 Verifiabl
e Credentials wallets and verifiers or inclusion within a Comprehensive Learner
Record (CLR 2.0)."
],
"iss": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
"jti": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130004",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiJ0UGpYWGk4WnoyY3M2VHRwSjdNeUxueHJuOVBHZURhVl9HcDl6S29CZzRBRnRVX2Y3V2FXVXlyUmdP
VlJSWUQ2aGxhZDJma3EtMEY3NjdoZVhsbUFQdnZ0WlJmVDc3UE4tOXRnblpsNzl0YnEwMVJoTjEtcTBy
MW16cFY2ckZCaXFIS1hJeXVGR1N4Q3FGb0wtYkRLWjlOaVd1Znd0NXFTRk10OWVVYXp0dW9JQTBhU2VC
M0ZybHdNb1FaVjJjU0xwVG5BUWhWQ204U2Z3LTFvYTFQSDRFQk1fRlpyaXVKYlpGVWVuOFVYM2IzSkRP
bXFBNC1oMllySHJvVjlaNmRNWnlFNTRaV1djS0doRUhWQUlZQ01qdDJNSXlGaW1BQkVCS2JWdkdTbE0z
ZkN4R0ZFNWp1RWhUVDNNRjdCMGFFYnNTMVNoVXJGN3ZSUVN4Mi14S29pclEifX0.eyJAY29udGV4dCI6
WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3B1cmwuaW1zZ2xv
YmFsLm9yZy9zcGVjL29iL3YzcDAvY29udGV4dC0zLjAuMy5qc29uIl0sImlkIjoidXJuOnV1aWQ6OTE1
MzdkYmEtNTZjYi0xMWVjLWJmNjMtMDI0MmFjMTMwMDA0IiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVu
dGlhbCIsIk9wZW5CYWRnZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjp7ImlkIjoiZGlkOndlYjpleGFtcGxl
LmNvbTppc3N1ZXJzOjU0MGUzODhlLTI3MzUtNGMzZS05NzA5LTgwMTQyODAxYzc3NCIsInR5cGUiOlsi
UHJvZmlsZSJdLCJhbHNvS25vd25BcyI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy92MnAwLzU0
MGUzODhlLTI3MzUtNGMzZS05NzA5LTgwMTQyODAxYzc3NCIsIm90aGVySWRlbnRpZmllciI6W3sidHlw
ZSI6WyJJZGVudGlmaWVyRW50cnkiXSwiaWRlbnRpZmllciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNz
dWVycy92MnAwLzU0MGUzODhlLTI3MzUtNGMzZS05NzA5LTgwMTQyODAxYzc3NCIsImlkZW50aWZpZXJU
eXBlIjoiaWRlbnRpZmllciJ9XSwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmVkdSIsImVtYWlsIjoiaW5m
b0BleGFtcGxlLmVkdSJ9LCJ2YWxpZEZyb20iOiIyMDEwLTAxLTAxVDAwOjAwOjAwWiIsIm5hbWUiOiJF
eGFtcGxlIENvbXBldGVuY3kgQmFkZ2UgSXNzdWVkIHVuZGVyIE9CIDIuMCIsImNyZWRlbnRpYWxTdWJq
ZWN0Ijp7ImlkIjoiZGlkOmV4YW1wbGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwidHlwZSI6
IkFjaGlldmVtZW50U3ViamVjdCIsImFjaGlldmVtZW50Ijp7ImlkIjoidXJuOnV1aWQ6YTc0NjdlZjYt
NTZjYi0xMWVjLWJmNjMtMDI0MmFjMTMwMDAyIiwidHlwZSI6IkFjaGlldmVtZW50IiwiY3JlYXRvciI6
eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy81NjUwNDkiLCJ0eXBlIjoiUHJvZmlsZSJ9
LCJuYW1lIjoiRXhhbXBsZSBDb21wZXRlbmN5IEJhZGdlIElzc3VlZCB1bmRlciBPQiAyLjAiLCJjcml0
ZXJpYSI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvYWNoaWV2ZW1lbnRzL2E3NDY3ZWY2LTU2Y2It
MTFlYy1iZjYzLTAyNDJhYzEzMDAwMi9jcml0ZXJpYSJ9LCJkZXNjcmlwdGlvbiI6IlRoaXMgZXhhbXBs
ZSBiYWRnZSB3YXMgaXNzdWVkIG9yaWdpbmFsbHkgYXMgYW4gT3BlbiBCYWRnZXMgMi4wIGFzc2VydGlv
biIsImltYWdlIjp7ImlkIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9hY2hpZXZlbWVudHMvc2FtcGxlLnBu
ZyIsInR5cGUiOiJJbWFnZSJ9fX0sImV2aWRlbmNlIjpbeyJ0eXBlIjpbIkV2aWRlbmNlIiwiaHR0cHM6
Ly93M2lkLm9yZy9vcGVuYmFkZ2VzI0Fzc2VydGlvbiJdLCJpZCI6Imh0dHBzOi8vZXhhbXBsZS5vcmcv
b2IyL2Fzc2VydGlvbnMvMTA0ODE4MTAtZTA5NC00ZmZlLTgwNmYtMjVkZTQ5Yzg3OTMzIiwibmFtZSI6
Ik9yaWdpbmFsIE9wZW4gQmFkZ2VzIDIuMCBhc3NlcnRpb24gZm9yIHRoaXMgY3JlZGVudGlhbCIsImRl
c2NyaXB0aW9uIjoiVGhpcyBjcmVkZW50aWFsIHdhcyBvcmlnaW5hbGx5IGlzc3VlZCBhcyBhbiBPcGVu
IEJhZGdlcyAyLjAgYXNzZXJ0aW9uLiBJdCBoYXMgYmVlbiB1cGRhdGVkIHRvIHRoZSBsYXRlc3QgdmVy
c2lvbiBmb3IgZGVsaXZlcnkgdG8gVmVyaWZpYWJsZSBDcmVkZW50aWFscyB3YWxsZXRzIGFuZCB2ZXJp
ZmllcnMgb3IgaW5jbHVzaW9uIHdpdGhpbiBhIENvbXByZWhlbnNpdmUgTGVhcm5lciBSZWNvcmQgKENM
UiAyLjApLiJ9XSwiaXNzIjoiZGlkOndlYjpleGFtcGxlLmNvbTppc3N1ZXJzOjU0MGUzODhlLTI3MzUt
NGMzZS05NzA5LTgwMTQyODAxYzc3NCIsImp0aSI6InVybjp1dWlkOjkxNTM3ZGJhLTU2Y2ItMTFlYy1i
ZjYzLTAyNDJhYzEzMDAwNCIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEy
ZWMyMSJ9.do_vLXKp45-Vfr_F3sxAdWWCAEzRksFb8h_50yJPQyJdNvCLgUGC_TZECnt374rlHzBt9FR
ibx-6meXUT3AstOi2T0OIqKPOMLQw8ur9vgWQBhKE3QS-nIY4cC0E9oGcExtqlO-6feFypPRsaOthMS4
IGOFBLrLcsBzYdzKvL94Ahz3XZOMnh4JDbCcWY8Se8U36HpkzNRVFO_xthl47d3r7qMo2mN_sVnIeQWG
QoPRffsJ56AA1wS6Vf0t3cXVA-RhiNoGnonV6tCc2VQKe8enJZiPsVCxlzzUVLg9MHgaFWKfCoq4vOx9
sBQUqLFjG9IfWyUsge10tIqQKy2A7_Q
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
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.
6.2
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.
6.3
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.
7.
Open Badges Extensions
This section is non-normative.
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.
7.1
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).
7.1.1
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
20
: 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
21
: 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, “
resolves to the above JSON-LD context.
Also, the Achievement in your credentials
MUST
also be of your newly created type. i.e.:
Example
22
: Sample Credential with Extension type
...
"credentialSubject": {
...
"achievement": {
"type": ["Achievement", "MyCustomAchievement"]
...
...
7.1.2
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
23
: 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
24
: 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"
}]
...
7.1.3
Example Credential
Example
25
: Sample Credential with Extension
"@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"
8.
Getting Help
This section is non-normative.
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
9.
Linked Data Proof Test Vector for Open Badges 3.0
This section is non-normative.
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.
9.1
Key pair & Multikey
For this example we are using the following keypair:
Public key (hex):
4bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
Private key (hex):
6241a409e6707bb640a0140a8a32bc3d193c33a661747284d6adfa4ed4180be44bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
The
MultiKey
used in this example is as follows:
Example
26
: Multikey
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
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]
9.2
Test data
The credential used in the example is:
Example
27
: 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"
9.3
Document before signing
Example
28
: 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'
9.4
Proof before signing
Example
29
: Proof before signing
type: 'DataIntegrityProof',
created: '2010-01-01T19:23:24Z',
verificationMethod: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
cryptosuite: 'eddsa-rdfc-2022',
proofPurpose: 'assertionMethod'
9.5
Proof normalized
Example
30
: Proof normalized
_:c14n0 "2010-01-01T19:23:24Z"^^ .
_:c14n0 .
_:c14n0 "eddsa-rdfc-2022"^^ .
_:c14n0 .
_:c14n0 .
9.6
Document normalized
Example
31
: Document normalized
.
.
.
.
"Teamwork Badge" .
.
.
"2010-01-01T00:00:00Z"^^ .
.
_:c14n0 .
"This badge recognizes the development of the capacity to collaborate within a group environment." .
"Teamwork" .
.
"Example Corp" .
"https://www.imsglobal.org"^^ .
_:c14n0 "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management." .
9.7
Document hash (hex)
87f65a76d40146205e3b3e06cb0fbd153f97f9ce70372390f52566bb7f9e0773
9.8
Proof hash (hex)
d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19
9.9
Data to sign (hex)
d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d1987f65a76d40146205e3b3e06cb0fbd153f97f9ce70372390f52566bb7f9e0773
9.10
Signature (hex)
f7a017acf7d27983267ec362657c0fb08e955549f49dac5bf36a03c4f2c3a4f1e3738a6c5ecd7ffba7135cb9cd754e6196f4b73082ea8df8e703c8ecd4333503
9.11
Proof value (hex)
z5x9aCBYovW3CQCbKdNyhEm7ffYSw1YpEdPywQJoNbzDD2gkzQDKJ1sYKJaWvqZtkMtSbz35HcbgXVEDYHxCzgkCr
9.12
Proof
Example
32
: Proof
"type"
"DataIntegrityProof"
"created"
"2010-01-01T19:23:24Z"
"verificationMethod"
"https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi"
"cryptosuite"
"eddsa-rdfc-2022"
"proofPurpose"
"assertionMethod"
"proofValue"
"z5x9aCBYovW3CQCbKdNyhEm7ffYSw1YpEdPywQJoNbzDD2gkzQDKJ1sYKJaWvqZtkMtSbz35HcbgXVEDYHxCzgkCr"
9.13
Signed credential
Example
33
: 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"
10.
Linked Data Proof Test Vector for Comprehensive Learner Record 2.0
This section is non-normative.
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.
10.1
Key pair & Multikey
For this example we are using the following keypair:
Public key (hex):
4bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
Private key (hex):
6241a409e6707bb640a0140a8a32bc3d193c33a661747284d6adfa4ed4180be44bdeafde2ea8beefadd8c699b5c7e0704cf51154d52e17b20b71337ca04cc5a5
The
MultiKey
used in this example is as follows:
Example
34
: Multikey
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
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]
10.2
Test data
The credential used in the example is:
Example
35
: 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"
10.3
Document before signing
Example
36
: 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"
10.4
Proof before signing
Example
37
: Proof before signing
type: 'DataIntegrityProof',
created: '2010-01-01T19:23:24Z',
verificationMethod: 'https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi',
cryptosuite: 'eddsa-rdfc-2022',
proofPurpose: 'assertionMethod'
10.5
Proof normalized
Example
38
: Proof normalized
_:c14n0 "2010-01-01T19:23:24Z"^^ .
_:c14n0 .
_:c14n0 "eddsa-rdfc-2022"^^ .
_:c14n0 .
_:c14n0 .
10.6
Document normalized
Example
39
: Document normalized
.
.
.
.
_:c14n2 .
.
.
.
.
"Sample Transcript" .
.
.
.
"2010-01-01T00:00:00Z"^^ .
.
.
"Example University" .
.
.
.
.
"Example University Degree" .
_:c14n1 .
.
.
.
"2010-01-01T00:00:00Z"^^ .
.
.
.
.
"Achievement 1" .
"Achievement 1" .
.
.
.
.
"Achievement 2" .
"Achievement 2" .
_:c14n0 "2010-01-01T19:23:24Z"^^ _:c14n1 .
_:c14n0 _:c14n1 .
_:c14n0 "eddsa-rdfc-2022"^^ _:c14n1 .
_:c14n0 _:c14n1 .
_:c14n0 "z45QnLySMt2mWuW787G6cf3SLkP97ZkMZxLeXH5yaaTQPCtTup4GCV95tU8HEnQJSyGCokSj3AvUhmJtvveTmN4Vu"^^ _:c14n1 .
_:c14n0 _:c14n1 .
_:c14n2 .
_:c14n2 "isParentOf" .
_:c14n2 "urn:uuid:a7467ef6-56cb-11ec-bf63-0242ac130002"^^ .
_:c14n2 "urn:uuid:dd887f0a-56cb-11ec-bf63-0242ac130002"^^ .
10.7
Document hash (hex)
768d7015ae69e0210e1c2a45194d9c1d15d7a6022e52b946574a2a27f6fa85fe
10.8
Proof hash (hex)
d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19
10.9
Data to sign (hex)
d34009cea0dbc1ca941e09dc01c8c9d3e3ce3c5b853f67ee44698dcea10f5d19768d7015ae69e0210e1c2a45194d9c1d15d7a6022e52b946574a2a27f6fa85fe
10.10
Signature (hex)
0c220dadbcfcaa64ab8a8c5002dbe258e6c7746ca71c25e2ea3b7fbffd66568413f53b1d34f5655f3057864bd372bbf0d1e74ea2f8c72e2f4b5790f21a22b70a
10.10.1
Proof value (hex)
zF52sU1nfPAjcwCqtgxPNSor6SJnAzRBwZW5VNQXPt8xXCHkd39sgqj32DnMjhFCzbyHsLkhQ8HpBqQTkMgXy329
10.10.2
Proof
Example
40
: Proof
"type"
"DataIntegrityProof"
"created"
"2010-01-01T19:23:24Z"
"verificationMethod"
"https://example.edu/issuers/565049#z6MkjZRZv3aez3r18pB1RBFJR1kwUVJ5jHt92JmQwXbd5hwi"
"cryptosuite"
"eddsa-rdfc-2022"
"proofPurpose"
"assertionMethod"
"proofValue"
"zF52sU1nfPAjcwCqtgxPNSor6SJnAzRBwZW5VNQXPt8xXCHkd39sgqj32DnMjhFCzbyHsLkhQ8HpBqQTkMgXy329"
10.10.3
Signed credential
Example
41
: 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"
A.
Revision History
This section is non-normative.
Version No.
Document Version
Release Date
Comments
Version 3.0 IMS Candidate Final
1.0
November 10, 2022
Covers Issuer, Displayer, and Host conformance and
certification.
Version 3.0 IMS Candidate Final
1.1
June 20, 2023
Updated Linked Data Proof to the new EdDSA Cryptosuite v2022 [
VC-DI-EDDSA
].
Version 3.0 IMS Candidate Final
1.2
July 14, 2023
New version of the context.json (
context-3.0.2.json
) file. See
Open Badges Specification v3.0: Errata
for detailed changes
Version 3.0 IMS Candidate Final
1.3
September 8, 2023
Reorganized some sections of the document to highlight Issuer, Displayer and Host roles.
Added recommended practice for including additional info of the recipient of a credential.
Added recommended practice for supporting old cryptosuites.
Added test vector data for signing Open Badges and Comprehensive Learner Record.
Version 3.0 IMS Candidate Final
1.4
September 22, 2023
Added a section about including older Open Badges in CLR 2.0.
Version 3.0 IMS Candidate Final
1.5
November 9, 2023
Added a section about issuer's key provenance.
Version 3.0 IMS Candidate Final
1.6
December 13, 2023
New version of the context.json (
context-3.0.3.json
) file. See
Open Badges Specification v3.0: Errata
for detailed changes
Version 3.0 IMS Candidate Final
1.7
December 15, 2023
Added sections about alignment of achievements with non-1EdTech vocabularies, such Credential Engine.
Version 3.0 IMS Candidate Final
1.8
January 26, 2023
Language of related achievement now uses the new attribute
inLanguage
instead of
@language
Version 3.0 IMS Candidate Final
1.9
April 2, 2024
Upgraded to [
VC-DATA-MODEL-2.0
Version 3.0 IMS Candidate Final
1.10
October 1, 2024
Added section about extensions.
Added section about privacy.
Version 3.0 IMS Candidate Final
Final Release
1.0
December 23, 2024
Clarified proof mechanism and algorithm selection.
Version 3.0 IMS Candidate Final
Final Release
1.1
February 12, 2025
Reorganization.
Clarified some paragraphs.
Version 3.0 IMS Candidate Final
Final Release
2.0
April 7, 2025
Fixed some typos.
B.
References
B.1
Normative references
[CASE-10]
IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0
. IMS Global Learning Consortium. July 7, 2017. IMS Final Release. URL:
[CLR-20]
Comprehensive Learner Record Standard v2.0
. 1EdTech Consortium. February 26, 2025. 1EdTech Final Release. URL:
[CLR-CERT-20]
Comprehensive Learner Record Standard Conformance and Certification Guide v2.0
. 1EdTech Consortium. February 26, 2025. 1EdTech Final Release. URL:
[EDUAPI-10]
Edu-API Specification Specification v1.0
. 1EdTech. IMS Candidate Final. URL:
[LTI-13]
IMS Global Learning Tools Interoperability® Core Specification v1.3
. C. Vervoort; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL:
[OB-30]
Open Badges Specification v3.0
. 1EdTech. 1EdTech Final Release. URL:
[OB-CERT-30]
Open Badges Specification Conformance and Certification Guide v3.0
. 1EdTech. 1EdTech Final Release. URL:
[OR-11]
1EdTech OneRoster® Specification v1.1
. 1EdTech. 1EdTech Final Release. URL:
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels
. S. Bradner. IETF. March 1997. Best Current Practice. URL:
[VC-DATA-MODEL]
Verifiable Credentials Data Model v1.1
. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL:
[VC-DATA-MODEL-2.0]
Verifiable Credentials Data Model v2.0
. Ivan Herman; Michael Jones; Manu Sporny; Ted Thibodeau Jr; Gabe Cohen. W3C. 20 March 2025. W3C Proposed Recommendation. URL:
B.2
Informative references
[OB-ERRATA-30]
Open Badges Specification v3.0: Errata
. URL:
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax
. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL:
[RFC7515]
JSON Web Signature (JWS)
. M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL:
[RFC7517]
JSON Web Key (JWK)
. M. Jones. IETF. May 2015. Proposed Standard. URL:
[RFC7591]
OAuth 2.0 Dynamic Client Registration Protocol
. J. Richer, Ed.; M. Jones; J. Bradley; M. Machulak; P. Hunt. IETF. July 2015. Proposed Standard. URL:
[RFC7636]
Proof Key for Code Exchange by OAuth Public Clients
. N. Sakimura, Ed.; J. Bradley; N. Agarwal. IETF. September 2015. Proposed Standard. URL:
[SEC-11]
IMS Global Security Framework v1.1
. C. Smythe; C. Vervoort; M. McKell. IMS Global Learning Consortium. July 19th, 2021. IMS Final Release. URL:
[VC-DATA-INTEGRITY]
Verifiable Credential Data Integrity 1.0
. Ivan Herman; Manu Sporny; Ted Thibodeau Jr; Dave Longley; Greg Bernstein. W3C. 20 March 2025. W3C Proposed Recommendation. URL:
[VC-DI-EDDSA]
Data Integrity EdDSA Cryptosuites v1.0
. Manu Sporny; Ted Thibodeau Jr; Greg Bernstein. W3C. 20 March 2025. W3C Proposed Recommendation. URL:
[VC-DID-WEB-METHOD]
DID Web Method Specification
. Credentials Community Group. CG-DRAFT. URL:
[VC-JOSE-COSE]
Securing Verifiable Credentials using JOSE and COSE
. Michael Jones; Gabe Cohen; Michael Prorock. W3C. 20 March 2025. W3C Proposed Recommendation. URL:
[VC-STATUS-2021]
Credential Status List 2021
. W3C Credentials Community Group. W3C Working Draft. URL:
[VCCR-10]
1EdTech Credential Refresh Service
. 1EdTech. Candidate Final Public. URL:
[VCRL-10]
1EdTech Revocation List Status Method
. 1EdTech. Candidate Final Public. URL:
C.
List of Contributors
The following individuals contributed to the development of this document:
Name
Organization
Role
Nate Otto
Skybridge Skills
Invited Expert
Justin Pitcher
Anthology
Co-chair, OB
Xavi Aracil
1Edtech
Editor
Rob Coyle
1Edtech
Editor
Sharebar?