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

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

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.

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.

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.

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.

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.3.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.3.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).

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 still 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 specification identifies some specific options, which are used by the conformance test suite to check product implementations. 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).

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.

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 v1.1 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.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "OpenBadgeCredential"],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "issuanceDate": "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/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "OpenBadgeCredential"
  ],
  "issuer": {
    "id": "https://example.edu/issuers/565049",
    "type": "Profile",
    "name": "Example University"
  },
  "issuanceDate": "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": "2023-11-09T13:59:58Z",
      "verificationMethod": "https://example.edu/issuers/565049#z6MkjTUMoMcbxeFGZ7c89JKKJ2SsVqNbuxA9ZDZPLWvqSLzh",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "zheGx34BASzaK73MWY2rVJyjAuLjVqcedgniXnenhvcPcFkiD1FXFzeF6pZ61wqXPRBeMyoU1yB6efeERKAgn4zL"
    }
  ]
}

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "e": "AQAB",
    "kty": "RSA",
    "n": "0viIUTX2WQs2bINUjWAmgXNoI6376zo2aRpvsERkI-NKzFBvCek0fF90WmUgMKLYZKawpz
aWNYZTk6ioObfJRyV2TiSAqZWHznovv-_eJ1LRTMn-jYkH6oSLgQgJ2wnxwCdNq32jXw4S5Y-7yv7lU7
0wOg8U1a_jLETnXSMmL4hkCuTP2DMQmGNzCzGaWzYayxJhc11Vqss8dTehzKHplvZT--nQ2uudjBGFEB
C3vJV4rWmprO6VIL5kcwAueUbwH5udN01faYsHaLgvrbl5JTFj3ugLij3Ouq4KK1XD-6TQwsay5VRlVg
WSe-m_VUX1vbgJeMfgisULXW0B3orcPQ"
  }
}
--------------- 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.
{
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json"
    ],
    "id": "http://example.edu/credentials/3732",
    "type": [
      "VerifiableCredential",
      "OpenBadgeCredential"
    ],
    "issuer": {
      "id": "https://example.edu/issuers/565049",
      "type": "Profile",
      "name": "Example University"
    },
    "issuanceDate": "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 ana
lysis 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 t
ext, including determining where the text leaves matters uncertain",
            "targetType": "CFItem",
            "targetUrl": "https://caseregistry.imsglobal.org/uri/74f5bb7d-d7cc-1
1e8-824f-0242ac160002"
          }
        ]
      }
    }
  },
  "iss": "https://example.edu/issuers/565049",
  "nbf": 1262304000,
  "jti": "http://example.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiIwdmlJVVRYMldRczJiSU5ValdBbWdYTm9JNjM3NnpvMmFScHZzRVJrSS1OS3pGQnZDZWswZkY5MFdt
VWdNS0xZWkthd3B6YVdOWVpUazZpb09iZkpSeVYyVGlTQXFaV0h6bm92di1fZUoxTFJUTW4tallrSDZv
U0xnUWdKMndueHdDZE5xMzJqWHc0UzVZLTd5djdsVTcwd09nOFUxYV9qTEVUblhTTW1MNGhrQ3VUUDJE
TVFtR056Q3pHYVd6WWF5eEpoYzExVnFzczhkVGVoektIcGx2WlQtLW5RMnV1ZGpCR0ZFQkMzdkpWNHJX
bXByTzZWSUw1a2N3QXVlVWJ3SDV1ZE4wMWZhWXNIYUxndnJibDVKVEZqM3VnTGlqM091cTRLSzFYRC02
VFF3c2F5NVZSbFZnV1NlLW1fVlVYMXZiZ0plTWZnaXNVTFhXMEIzb3JjUFEifX0.eyJ2YyI6eyJAY29u
dGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vcHVy
bC5pbXNnbG9iYWwub3JnL3NwZWMvb2IvdjNwMC9jb250ZXh0LTMuMC4yLmpzb24iXSwiaWQiOiJodHRw
Oi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRp
YWwiLCJPcGVuQmFkZ2VDcmVkZW50aWFsIl0sImlzc3VlciI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5l
ZHUvaXNzdWVycy81NjUwNDkiLCJ0eXBlIjoiUHJvZmlsZSIsIm5hbWUiOiJFeGFtcGxlIFVuaXZlcnNp
dHkifSwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQwMDowMDowMFoiLCJuYW1lIjoiRXhhbXBsZSBV
bml2ZXJzaXR5IERlZ3JlZSIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmV4YW1wbGU6ZWJm
ZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwidHlwZSI6IkFjaGlldmVtZW50U3ViamVjdCIsImFjaGll
dmVtZW50Ijp7ImlkIjoiaHR0cHM6Ly8xZWR0ZWNoLmVkdS9hY2hpZXZlbWVudHMvMSIsInR5cGUiOiJB
Y2hpZXZlbWVudCIsImNyaXRlcmlhIjp7Im5hcnJhdGl2ZSI6IkNpdGUgc3Ryb25nIGFuZCB0aG9yb3Vn
aCB0ZXh0dWFsIGV2aWRlbmNlIHRvIHN1cHBvcnQgYW5hbHlzaXMgb2Ygd2hhdCB0aGUgdGV4dCBzYXlz
IGV4cGxpY2l0bHkgYXMgd2VsbCBhcyBpbmZlcmVuY2VzIGRyYXduIGZyb20gdGhlIHRleHQsIGluY2x1
ZGluZyBkZXRlcm1pbmluZyB3aGVyZSB0aGUgdGV4dCBsZWF2ZXMgbWF0dGVycyB1bmNlcnRhaW4ifSwi
ZGVzY3JpcHRpb24iOiJBbmFseXplIGEgc2FtcGxlIHRleHQiLCJuYW1lIjoiVGV4dCBhbmFseXNpcyIs
ImFsaWdubWVudCI6W3sidHlwZSI6IkFsaWdubWVudCIsInRhcmdldENvZGUiOiI3NGY1YmI3ZC1kN2Nj
LTExZTgtODI0Zi0wMjQyYWMxNjAwMDIiLCJ0YXJnZXRGcmFtZXdvcmsiOiJBbGFiYW1hIENvdXJzZSBv
ZiBTdHVkeTogRW5nbGlzaCBMYW5ndWFnZSBBcnRzIiwidGFyZ2V0TmFtZSI6IkNpdGUgc3Ryb25nIGFu
ZCB0aG9yb3VnaCB0ZXh0dWFsIGV2aWRlbmNlIHRvIHN1cHBvcnQgYW5hbHlzaXMgb2Ygd2hhdCB0aGUg
dGV4dCBzYXlzIGV4cGxpY2l0bHkgYXMgd2VsbCBhcyBpbmZlcmVuY2VzIGRyYXduIGZyb20gdGhlIHRl
eHQsIGluY2x1ZGluZyBkZXRlcm1pbmluZyB3aGVyZSB0aGUgdGV4dCBsZWF2ZXMgbWF0dGVycyB1bmNl
cnRhaW4iLCJ0YXJnZXRUeXBlIjoiQ0ZJdGVtIiwidGFyZ2V0VXJsIjoiaHR0cHM6Ly9jYXNlcmVnaXN0
cnkuaW1zZ2xvYmFsLm9yZy91cmkvNzRmNWJiN2QtZDdjYy0xMWU4LTgyNGYtMDI0MmFjMTYwMDAyIn1d
fX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNTY1MDQ5IiwibmJmIjoxMjYyMzA0
MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsInN1YiI6ImRpZDpl
eGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSJ9.w3O7KAlre4CdX7g_TKhD69H7Yq5DlCe
ZuDUV9SZGPzzTmb9pHaTzc-e8CuebNDV_qSXTpcSyQJ_FkTewCl6kuWY9LNFDbtX9e0pxpztF61YCb91
6is0767eeqkSk7ojpeBQv8NIK_ne2uhFVlDpaFB84bgPZJKzBL6ggzxw2KLDdbh7CojYt5Xk4juf0KDq
0Z72nLARUemEyPXeYnn-FIhwEQCZAXhv9kYUPQQc2nTQEIPQM1RAH0vmEhRGQmgQO46B_cJ37jKteLkc
k571aHGwiMJlHUzoPJ2TZy6vQkSbtl9t8mK7yRLmhjlMwGvHi0AsjoLJHBxdXP3v23JQ1SA

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

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.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"
    },
    "issuanceDate": "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/2018/credentials/v1",
    "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json",
    "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "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"
  },
  "issuanceDate": "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": "2023-11-09T13:59:58Z",
      "verificationMethod": "https://1edtech.edu/issuers/565049#z6Mkhp7dmNhneHpRXFwnMoro63Nt6pnGXh9kyTeT5Q79CRq4",
      "cryptosuite": "eddsa-rdfc-2022",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2TfHNHpuNyb5M9K8tkQxhB8jggo3g34WX9k93heGeCDz2CrUGZDsZfBTtJnvXhummVTcWxHA2gB1LS98dxFTUFMm"
    }
  ]
}

---------------- JWT header ---------------
{
  "alg": "RS256",
  "typ": "JWT",
  "jwk": {
    "e": "AQAB",
    "kty": "RSA",
    "n": "jMJUqfOo9i4srfwSj-eWMKJ_4yEt3dvJ2GEXJ1Cc-OMxCozBHuxNJcjJyQor5IovRiO97q
e6FHPfd3OwQiodzUmGRHHttmkubJDbKysSc3aaxJHwhrqjM5eC0pYXtCkgsGMHFRifQkzE9bzPeJoHtb
yRxSMvdkERn8fJqlcr7MtOCvvKIEsp7XzeyovmrmcM-pxvUr0WtOnp8L8eLZoXxPbK8iBv1hI0d1aHO3
Zn2GJU_yEdM8OXTQUD54rpy3b1GPeMXcly24e9spEZT6z68PUSG0XJ7H1CtdRcSVpWfVaDlms26rqT0j
0iA00cgE17e1S76F6Bfbv0LUJUEiPVIQ"
  }
}
--------------- 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.
{
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.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 w
ho publish skills data for common usage.",
          "email": "info@exammple.com"
        },
        "criteria": {
          "narrative": "Learners must demonstrate understanding of linear algebr
a and graphic representation of linear equations."
        },
        "description": "This achievement represents developing capability to sol
ve 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"
    },
    "issuanceDate": "2022-07-01T00:00:00Z",
    "credentialSchema": [
      {
        "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achie
vementcredential_schema.json",
        "type": "1EdTechJsonSchemaValidator2019"
      }
    ]
  },
  "iss": "https://1edtech.edu/issuers/565049",
  "nbf": 1656633600,
  "jti": "http://1edtech.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6eyJlIjoiQVFBQiIsImt0eSI6IlJTQSIsIm4i
OiJqTUpVcWZPbzlpNHNyZndTai1lV01LSl80eUV0M2R2SjJHRVhKMUNjLU9NeENvekJIdXhOSmNqSnlR
b3I1SW92UmlPOTdxZTZGSFBmZDNPd1Fpb2R6VW1HUkhIdHRta3ViSkRiS3lzU2MzYWF4Skh3aHJxak01
ZUMwcFlYdENrZ3NHTUhGUmlmUWt6RTlielBlSm9IdGJ5UnhTTXZka0VSbjhmSnFsY3I3TXRPQ3Z2S0lF
c3A3WHpleW92bXJtY00tcHh2VXIwV3RPbnA4TDhlTFpvWHhQYks4aUJ2MWhJMGQxYUhPM1puMkdKVV95
RWRNOE9YVFFVRDU0cnB5M2IxR1BlTVhjbHkyNGU5c3BFWlQ2ejY4UFVTRzBYSjdIMUN0ZFJjU1ZwV2ZW
YURsbXMyNnJxVDBqMGlBMDBjZ0UxN2UxUzc2RjZCZmJ2MExVSlVFaVBWSVEifX0.eyJ2YyI6eyJAY29u
dGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vcHVy
bC5pbXNnbG9iYWwub3JnL3NwZWMvb2IvdjNwMC9jb250ZXh0LTMuMC4yLmpzb24iLCJodHRwczovL3B1
cmwuaW1zZ2xvYmFsLm9yZy9zcGVjL29iL3YzcDAvZXh0ZW5zaW9ucy5qc29uIl0sImlkIjoiaHR0cDov
LzFlZHRlY2guZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFs
IiwiT3BlbkJhZGdlQ3JlZGVudGlhbCJdLCJuYW1lIjoiU29sdmUgYW5kIGdyYXBoIGxpbmVhciBlcXVh
dGlvbnMgYW5kIGluZXF1YWxpdGllcyIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmV4YW1w
bGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwidHlwZSI6IkFjaGlldmVtZW50U3ViamVjdCIs
ImFjaGlldmVtZW50Ijp7ImlkIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9hY2hpZXZlbWVudHMvbWF0aC9s
aW5lYXItMSIsInR5cGUiOiJBY2hpZXZlbWVudCIsImFjaGlldmVtZW50VHlwZSI6IkNvbXBldGVuY3ki
LCJjcmVhdG9yIjp7ImlkIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXJzLzEyMzc2NyIsInR5cGUi
OiJQcm9maWxlIiwibmFtZSI6IkV4YW1wbGUgSW5kdXN0cnkgR3JvdXAiLCJ1cmwiOiJodHRwczovL2V4
YW1wbGUuY29tIiwiZGVzY3JpcHRpb24iOiJFeGFtcGxlIEluZHVzdHJ5IEdyb3VwIGlzIGEgY29uc29y
dGl1bSBvZiBsdW1pbmFyaWVzIHdobyBwdWJsaXNoIHNraWxscyBkYXRhIGZvciBjb21tb24gdXNhZ2Uu
IiwiZW1haWwiOiJpbmZvQGV4YW1tcGxlLmNvbSJ9LCJjcml0ZXJpYSI6eyJuYXJyYXRpdmUiOiJMZWFy
bmVycyBtdXN0IGRlbW9uc3RyYXRlIHVuZGVyc3RhbmRpbmcgb2YgbGluZWFyIGFsZ2VicmEgYW5kIGdy
YXBoaWMgcmVwcmVzZW50YXRpb24gb2YgbGluZWFyIGVxdWF0aW9ucy4ifSwiZGVzY3JpcHRpb24iOiJU
aGlzIGFjaGlldmVtZW50IHJlcHJlc2VudHMgZGV2ZWxvcGluZyBjYXBhYmlsaXR5IHRvIHNvbHZlIGFu
ZCBncmFwaCBsaW5lYXIgZXF1YXRpb25zIGFuZCBpbmVxdWFsaXRpZXMiLCJpbWFnZSI6eyJpZCI6Imh0
dHBzOi8vZXhhbXBsZS5jb20vYWNoaWV2ZW1lbnRzL21hdGgvbGluZWFyLTEvaW1hZ2UiLCJ0eXBlIjoi
SW1hZ2UiLCJjYXB0aW9uIjoiQSBsaW5lLCBzbG9waW5nIHVwd2FyZCBvcHRpbWlzdGljYWxseSJ9LCJu
YW1lIjoiTGluZWFyIGVxdWF0aW9ucyBhbmQgaW5lcXVhbGl0aWVzIn19LCJpc3N1ZXIiOnsiaWQiOiJo
dHRwczovLzFlZHRlY2guZWR1L2lzc3VlcnMvNTY1MDQ5IiwidHlwZSI6IlByb2ZpbGUiLCJuYW1lIjoi
MUVkVGVjaCBVbml2ZXJzaXR5IiwidXJsIjoiaHR0cHM6Ly8xZWR0ZWNoLmVkdSIsInBob25lIjoiMS0y
MjItMzMzLTQ0NDQiLCJkZXNjcmlwdGlvbiI6IjFFZFRlY2ggVW5pdmVyc2l0eSBwcm92aWRlcyBvbmxp
bmUgZGVncmVlIHByb2dyYW1zLiIsImltYWdlIjp7ImlkIjoiaHR0cHM6Ly8xZWR0ZWNoLmVkdS9sb2dv
LnBuZyIsInR5cGUiOiJJbWFnZSIsImNhcHRpb24iOiIxRWRUZWNoIFVuaXZlcnNpdHkgbG9nbyJ9LCJl
bWFpbCI6InJlZ2lzdHJhckAxZWR0ZWNoLmVkdSJ9LCJpc3N1YW5jZURhdGUiOiIyMDIyLTA3LTAxVDAw
OjAwOjAwWiIsImNyZWRlbnRpYWxTY2hlbWEiOlt7ImlkIjoiaHR0cHM6Ly9wdXJsLmltc2dsb2JhbC5v
cmcvc3BlYy9vYi92M3AwL3NjaGVtYS9qc29uL29iX3YzcDBfYWNoaWV2ZW1lbnRjcmVkZW50aWFsX3Nj
aGVtYS5qc29uIiwidHlwZSI6IjFFZFRlY2hKc29uU2NoZW1hVmFsaWRhdG9yMjAxOSJ9XX0sImlzcyI6
Imh0dHBzOi8vMWVkdGVjaC5lZHUvaXNzdWVycy81NjUwNDkiLCJuYmYiOjE2NTY2MzM2MDAsImp0aSI6
Imh0dHA6Ly8xZWR0ZWNoLmVkdS9jcmVkZW50aWFscy8zNzMyIiwic3ViIjoiZGlkOmV4YW1wbGU6ZWJm
ZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIn0.IBaiwn2tj7pi6A3ctVSTdaaXmz6RvOdsnPCAa_eBcjXT
PFrreFG15F1Xd-Mp3OpQwsCeKyFOkhY8vlgqChUr0xu4stYU41OkMJxZAj7UlV1a2vgW6WIuvvgBa8Eg
IZYGheqIitg5usf0_o6T_a6e6Fr38h7f7v8KBkZZXI-jnKdAyukTRNNw1IYmRnjIENXjYtDHC8eL7iAq
zTjWtZAF2E0fJLawlxN3eFbjJuynR5Rz-h8K2MCM2oZ5aH5Nq1VX4V1aQGIC_Ctv6uHiM0FgInjJapli
Kf_XRZrgORWizhvmUxC-p106Nl9KEUQpCDwMgRrKcq3W7D2cSIK5M6Hjpg

3.1.7 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.)

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

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

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

3.1.8 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 fails 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:

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

3.1.9 Key provenance

Keys used in proof generation must belong to the issuer. However, there isn't a 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.2.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 the cryptosuite to use.

The change of the cryptosuite has impact in newly issued credentials. But there are already issued credentials with a proof generated using a now old cryptosuite. Verifiers should support prior cryptosuites, specially when the credential doesn't define the refresh service. In that case, is argually that the issuer will provide a refreshed version of the credential with a proof computed with the current designed cryptosuite.

Prior designed cryptosuites in both OB 3.0 and CLR 2.0 were:

• eddsa-2022
• Ed25519Signature2020

3.2.2 Key provenance

Keys used in proof generation must belong to the issuer. However, there isn't a 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.3.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.3.2 CLR 2.0 API recommendations

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

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

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

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

3.3.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 OpenBadgeCredentials. This issuer app seems to be compatible with a wide variety of web wallets, perhaps even through implementing multiple protocols used by these wallets with a variety of options. Some issuer services may be operating with connections to fewer or different wallet applications.

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

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

9.10.1 Proof value (hex)

9.10.2 Proof

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

9.10.3 Signed credential

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://purl.imsglobal.org/spec/clr/v2p0/context.json",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json",
        "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json",
        "https://w3id.org/security/data-integrity/v1"
    ],
    "id": "http://example.edu/credentials/3732",
    "type": [
        "VerifiableCredential",
        "ClrCredential"
    ],
    "issuer": {
        "id": "https://example.edu/issuers/565049",
        "type": "Profile",
        "name": "Example University"
    },
    "issuanceDate": "2010-01-01T00:00:00Z",
    "name": "Sample Transcript",
    "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "type": "ClrSubject",
        "verifiableCredential": [
        {
            "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json",
            "https://w3id.org/security/data-integrity/v1"
            ],
            "id": "urn:uuid:91537dba-56cb-11ec-bf63-0242ac130002",
            "type": [
            "VerifiableCredential",
            "AchievementCredential"
            ],
            "issuer": {
            "id": "https://example.edu/issuers/565049",
            "type": "Profile",
            "name": "Example University"
            },
            "issuanceDate": "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": "z2CGNmCgEmN68CWch6Kgg4vnjRDE896jnUqfQtJoG11qxC8ntxUPCQaGckoHG7BXW7KWZyUiSs5EkKX3gEiGYKrz"
            }
        }
        ],
        "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": "z2cNeK7UjuvWoNUHa8D7bbZuhryrgG3LjXmJSnY3R69mVJTAdX5yP1RCo9SH1aZwmyA76snohTwACQRFyrwGihsfr"
    }
}