Open Badges Version 2.1 Conformance and Certification Guide
Open Badges Conformance and Certification Guide
Spec Version 2.1
| Document Version: | 6 |
| Date Issued: | November 27, 2023 |
| Status: | This document is made available for adoption by the public community at large. |
| This version: | https://www.imsglobal.org/spec/ob/v2p1/cert/ |
| Latest version: | https://www.imsglobal.org/spec/ob/latest/cert/ |
| Errata: | https://www.imsglobal.org/spec/ob/v2p1/errata/ |
IPR and Distribution Notice
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .
The following participating organizations have made explicit license commitments to this specification:
| Org name | Date election made | Necessary claims | Type |
|---|---|---|---|
| Concentric Sky | October 24, 2019 | No | RF RAND (Required & Optional Elements) |
| Digital Knowledge | October 11, 2019 | No | RF RAND (Required & Optional Elements) |
| Washington State Board for Community and Technical Colleges (WSBCTC) | October 4, 2019 | No | RF RAND (Required & Optional Elements) |
| Credly | October 3, 2019 | No | RF RAND (Required & Optional Elements) |
Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/speclicense.html.
Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.
The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .
© 2023 1EdTech™ Consortium, Inc. All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
Abstract
Open Badges are visual symbols of accomplishments packed with verifiable metadata according to the Open Badges specification. The Open Badges 2.0 specification [OB-20] defines the properties necessary to define an achievement and award it to a recipient, as well as procedures for verifying badge authenticity and “baking” badge information into portable image files. It includes term definitions for representations of data in Open Badges. The Open Badges 2.1 specification [OB-21] defines an API for exchanging badge information. These term definitions appear in the current context at https://purl.imsglobal.org/spec/ob/v2p1/context/ob_v2p1.jsonld.
1. Introduction
1.1 Conformance and Certification
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].
An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.
1.2 Specification Documents
This section is non-normative.
The full set of documents is comprised of the following documents:
OpenAPI 3.0 Files for the Badge Connect® API
From the OpenAPI Specification [OPENAPIS],
The Open API Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.
This standard has OpenAPI 3.0 files for the Badge Connect® API in both JSON and YAML format:
JSON Schema Files for Open Badges Badge Connect(TM) API v2.1
Badge Connect® API JSON-LD Context File
From the JSON-LD 1.1 Specification [json-ld11],
When two people communicate with one another, the conversation takes place in a shared environment, typically called "the context of the conversation". This shared context allows the individuals to use shortcut terms, like the first name of a mutual friend, to communicate more quickly but without losing accuracy. A context in JSON-LD works in the same way. It allows two applications to use shortcut terms to communicate with one another more efficiently, but without losing accuracy.
Simply speaking, a context is used to map terms to IRIs. Terms are case sensitive and any valid string that is not a reserved JSON-LD keyword can be used as a term.
This specification includes this JSON-LD Context file:
1.3 Terminology
This section is non-normative.
The following terms are used throughout this document.
- Assertion: A representation of an awarded badge, used to share information about a badge belonging to one recipient.
- Backpack: A term originally used to describe Open Badges services that provide importing, aggregation, and hosting features for recipients. These services match most closely with the role we now define as an Open Badge “Host” application. May also refer to the Mozilla Backpack.
- BadgeClass: A collection of information about the accomplishment recognized by the Open Badge. Many assertions may be created corresponding to one BadgeClass.
- Badge Connect® API: Name of the RESTful web service for transfering assertions and profiles between systems.
- Badge Issuer: A service that allows for the creation of BadgeClasses and the subsequent issuing of Assertions to recipients that conform to the Open Badges specification. Beginning with Open Badges 2.0, the candidate platform must issue a valid baked badge and demonstrate how the badge is retrieved by the recipient.
- Badge Displayer: An application that displays verified badges to viewers. Beginning with Open Badges 2.0, the candidate platform must display a minimum set of badge metadata and support viewer-initiated verification of a badge.
- Badge Host: An application that can import, aggregate, and publicly host Assertions for recipients. It also supports export of badges at user request. Beginning with Open Badges 2.0, the candidate platform must be able to import all formats of Open Badges as well as prove that badge metadata is not lost upon export of the badge.
- Baked badge: Badge Assertions may be “baked” into image files as portable credentials.
- Candidate platform: A platform implementing the Open Badges specification with the intent to obtain certification from IMS. They may be in the process to obtain certification.
- Criteria: Detailed information about what must be done in order to be recognized with an assertion of a particular BadgeClass. Potential recipients may use criteria to understand what they must do; consumers may use criteria to understand what recipients did in order to earn the badge.
- Evidence: Links to and descriptions of evidence related to the issuance of an Assertion, such as portfolio items or narratives that describe a badge recipient's work.
- Extensions: Extensions are a means for issuers to add additional functionality through the use of metadata on Badge Objects beyond what the standard specifies itself.
- Validation and verification (of badge assertions): Data validation is a procedure that ensures a cluster of data objects that form an Open Badge are appropriately formatted, published, and linked and that each data object conforms to requirements for its class. Validation of all data class instances used in an Open Badge is a part of badge verification. Verification is the process of ensuring the data that makes up an Open Badge is correct. It includes a number of data validation checks as well as procedures to ensure the badge is trustworthy. Verification is distinct from compliance certification for applications and services that implement the specification, though verification is typically a component of certification programs. See Verification in the current specification.
2. Open Badges Conformance
The goal of IMS certification for Open Badges [OB-21] is to ensure interoperable implementations of badging systems that generate and issue digital badges as well as those that host and display badges.
IMS certification for Open Badges demands features and capabilities beyond those that are strictly required by the specification. These additional features are defined in this document. The specification is intentionally left very flexible to allow it to be used for many purposes. Gaining this certification is expected to be more difficult than simply meeting the minimum requirements for producing a valid Open Badge.
Certification may be achieved for one or more of the following 4 features:
| Consumer (Initiates Requests) |
Provider (Responds to Requests) |
|---|---|
| Service Consumer (Read) | Service Provider (Read) |
| Service Consumer (Write) | Service Provider (Write) |
The features and associated certification tests are defined below.
2.1 The Conformance Process
The process for conformance testing role implementations of Open Badges includes the following:
- First, launch the IMS Conformance Test Suite for Open Badges 2.1 and follow the onscreen instructions to run the tests.
- Once the tests have been successfully run, submit your test results. A copy of your test results will be sent to your email address.
To pass certification, you must take the following steps:
- You must be an IMS Digital Credentials and Badges Alliance Member, an IMS Affiliate Member, or IMS Contributing Member.
- You must be certified for Open Badges 2.0.
- You must pass all the tests associated with the features you are applying for using the certification suite hosted on the IMS website.
- The tests must be completed by a designated representative of the IMS member organization, and you must agree that there is no misrepresentation or manipulation of results in the submitted information.
After IMS reviews your submitted information and notifies you that your application is approved, you can claim certification to Open Badges 2.1 and display the IMS certified logo on your website and in your software. The IMS Global Certified Products Directory will list your conformance details.
2.2 Service Consumer (Read) Conformance
A product that conforms to Service Consumer (Read) requirements can request badges from a product that conforms to Service Provider (Read) requirements. One example of such a product is a Host which requests your badges from another Host.
2.2.1 Required Service Consumer (Read) Endpoint Support
The service endpoints that MUST be supported for Service Consumer (Read) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| getManifest | as configured | GET | Initiate | No |
| OAuth 2.0 Registration | from manifest | GET | Initiate | No |
| OAuth 2.0 Authorize | from manifest | GET | Initiate | No |
| OAuth 2.0 Token | from manifest | POST | Initiate | No |
| getAssertions | /ims/ob/v2p1/assertions |
GET | Initiate | Yes |
| getProfile | /ims/ob/v2p1/profile |
GET | Initiate | Yes |
2.2.2 Service Consumer (Read) Compliance
The functional capabilities of such systems are:
- They MUST support the required service endpoints
- They MUST supply an access token with the appropriate scope to the service endpoints that require authorization
- They MUST supply or 'handle' all of the required data fields in payloads
- They MUST be capable of supplying or 'handling' all of the optional data fields in payloads
- They MUST NOT provide extension data fields in the payloads
- They MAY support the endpoint payload pagination query parameters. If supported, the corresponding response HTTP pagination headers MUST be supported
2.3 Service Consumer (Write) Conformance
A product that conforms to Service Consumer (Write) requirements can send an Assertion or a Profile to a product that conforms to Service Provider (Write) requirements. One example of such a product is an Issuer that sends an Assertion to a Host.
2.3.1 Required Service Consumer (Write) Endpoint Support
The service endpoints that MUST be supported for Service Consumer (Write) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| getManifest | as configured | GET | Initiate | No |
| OAuth 2.0 Registration | from manifest | GET | Initiate | No |
| OAuth 2.0 Authorize | from manifest | GET | Initiate | No |
| OAuth 2.0 Token | from manifest | POST | Initiate | No |
| postAssertion | /ims/ob/v2p1/assertions |
POST | Initiate | Yes |
2.3.2 Optional Service Consumer (Write) Endpoint Support
The service endpoints that MAY be supported for Service Consumer (Write) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| postProfile | /ims/ob/v2p1/profile |
POST | Initiate | Yes |
2.3.3 Service Consumer (Write) Compliance
The functional capabilities of such systems are:
- They MUST support the required endpoints
- They MAY support the optional endpoints
- They MUST supply an access token with the appropriate scope to the service endpoints that require authorization
- They MUST supply or 'handle' all of the required data fields in payloads
- They MUST be capable of supplying or 'handling' all of the optional data fields in payloads
- They MUST NOT provide extension data fields in the payloads
2.4 Service Provider (Read) Conformance
A product that conforms to Service Provider (Read) requirements can provide badges to a product that conforms to Service Consumer (Read) requirements. One example of such a product is a Host which provides your badges to another Host upon request.
2.4.1 Required Service Provider (Read) Endpoint Support
The service endpoints that MUST be supported for Service Provider (Read) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| getManifest | as configured | GET | Respond | No |
| OAuth 2.0 Registration | from manifest | Respond | Respond | No |
| OAuth 2.0 Authorize | from manifest | GET | Respond | No |
| OAuth 2.0 Token | from manifest | POST | Respond | No |
| getAssertions | /ims/ob/v2p1/assertions |
GET | Respond | Yes |
| getProfile | /ims/ob/v2p1/profile |
GET | Respond | Yes |
2.4.2 Service Provider (Read) Compliance
The functional capabilities of such systems are:
- They MUST support the required service endpoints
- They MUST require an access token with the appropriate scope for endpoints that require authorization
- They MUST supply or 'handle' all of the required data fields in payloads
- They MUST be capable of supplying or 'handling' all of the optional data fields in payloads
- They MUST NOT provide extension data fields in the payloads
- They MUST support the endpoint payload pagination query parameters, and the corresponding response HTTP pagination headers MUST be supported
2.5 Service Provider (Write) Conformance
A product that conforms to Service Provider (Write) requirements can accept an Assertion or a Profile from a product that conforms to Service Consumer (Write) requirements. One example of such a product is a Host that accepts Assertions from an Issuer.
2.5.1 Required Service Provider (Write) Endpoint Support
The service endpoints that MUST be supported for Service Provider (Write) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| getManifest | as configured | GET | Respond | No |
| OAuth 2.0 Registration | from manifest | GET | Respond | No |
| OAuth 2.0 Authorize | from manifest | GET | Respond | No |
| OAuth 2.0 Token | from manifest | POST | Respond | No |
| postAssertion | /ims/ob/v2p1/assertions |
POST | Respond | Yes |
2.5.2 Optional Service Provider (Write) Endpoint Support
The service endpoints that MAY be supported for Service Provider (Write) are listed in the table below:
| Service Call | Endpoint | HTTP Verb | Mode | Authorization Required |
|---|---|---|---|---|
| postProfile | /ims/ob/v2p1/profile |
POST | Respond | Yes |
2.5.3 Service Provider (Write) Compliance
The functional capabilities of such systems are:
- They MUST support the required endpoints
- They MAY support the optional endpoints
- They MUST require an access token with the appropriate scope for the endpoints that require authorization
- They MUST supply or 'handle' all of the required data fields in payloads
- They MUST be capable of supplying or 'handling' all of the optional data fields in payloads
- They MUST NOT provide extension data fields in the payloads
A. Revision History
This section is non-normative.
| Version No. | Document Version | Release Date | Comments |
|---|---|---|---|
| Version 2.1 IMS Candidate Final Public | 6 | October 25, 2021 | Service Provider (Read) MUST support the endpoint payload pagination query parameters. Previously MAY. Also fixed a number of specification and documentation issues. |
| Version 2.1 IMS Candidate Final Public | 5 | October 7, 2020 | Released as Candidate Final Public. |
| Version 2.1 IMS Candidate Final | 4 | July 24, 2020 | Fourth draft. Replaced roles with features. |
| Version 2.1 IMS Candidate Final | 3 | January 24, 2020 | Second coordinated release. |
| Version 2.1 IMS Candidate Final | 2 | August 29, 2019 | Added Badge Connect® API conformance tests. |
| Version 2.0 IMS Final | 1 | April 12, 2018 | Covers Issuer, Displayer, and Host conformance and certification. |
| v2.1 Final | 1 | November 27, 2023 | Open Badges 2.1 Final release. |
B. References
B.1 Normative references
- [OB-21]
- Open Badges Specification v2.1. Jeff Bohrer; Andy Miller. IMS Global Learning Consortium. November 27, 2023. IMS Final Release. URL: https://www.imsglobal.org/spec/ob/v2p1/
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
B.2 Informative references
- [json-ld11]
- JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
- [OB-20]
- Open Badges v2.0. Otto, Nate; Bohrer, Jeff; Cook, Timothy; Gylling, Markus; Hripak, Alexander; Pitcher, Justin. IMS Global Learning Consortium. April 2018. IMS Final Release. URL: https://www.imsglobal.org/spec/ob/v2p0/
- [OB-CERT-21]
- Open Badges Conformance and Certification Guide v2.1. Jeff Bohrer; Andy Miller. IMS Global Learning Consortium. November 27, 2023. IMS Final Release. URL: https://www.imsglobal.org/spec/ob/v2p1/cert/
- [OB-JSON-21]
- JSON Schema Files for Open Badges Badge Connect(TM) API v2.1. Jeff Bohrer; Andy Miller. IMS Global Learning Consortium. November 27, 2023. IMS Final Release. URL: https://purl.imsglobal.org/spec/ob/v2p1/schema/json/
- [OPENAPIS]
- OpenAPI Specification. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid; Tony Tam; Jason Harmon. OpenAPI Initiative. URL: https://www.openapis.org/
C. List of Contributors
The following individuals contributed to the development of this document:
| Name | Organization | Role |
|---|---|---|
| Alexander Hripak | Credly | Editor |
| Sara Arjona | Moodle | |
| Jeff Bohrer | IMS Global | |
| Viktor Haag | D2L | |
| Takahiro Hata | Digital Knowledge EdTech Lab | |
| Chris Houston | eLumen | |
| Mark Leuba | IMS Global | |
| Andy Miller | IMS Global | |
| Omid Mufeed | Digitalme | |
| Nate Otto | Concentric Sky | |
| Justin Pitcher | Campus Labs | |
| Alex Reis | D2L |