IMS Final Release
Open Badges Examples
IMS Final Release
Date Issued: | 12 April 2018 |
Status | IMS Final Release |
Latest version: | https://www.imsglobal.org/spec/ob/v2p0/examples/ |
IPR and Distribution Notices
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.
IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the 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 IMS’s procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: 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 |
Campus Labs | March 20, 2019 | No | RF RAND (Required & Optional Elements) |
Credly | March 14, 2019 | No | RF RAND (Required & Optional Elements) |
Mozilla Foundation | March 14, 2019 | No | RF RAND (Required & Optional Elements) |
Digitalme | March 11, 2019 | No | RF RAND (Required & Optional Elements) |
D2L Corporation | March 10, 2019 | No | RF RAND (Required & Optional Elements) |
Credly | March 18, 2018 | No | RF RAND (Required Elements) |
Pearson | November 21, 2017 | No | RF RAND (Required Elements) |
Copyright © 2018 IMS Global Learning Consortium. All Rights Reserved.
If you wish to distribute this document or use this document to implement a product or service, you must complete a valid license registration with IMS and receive an email from IMS granting the license. To register, follow the instructions on the IMS website: http://www.imsglobal.org/specificationdownload.cfm
This document may be copied and furnished to others by Licensee organizations registered on the IMS website provided that the above copyright notice and this paragraph are included on all such copies. However, this document itself may not be modified in any way, such as by changing the details of the specification, removing the copyright notice or references to IMS, except as needed for the purpose of developing IMS specifications under the auspices of a chartered IMS work group.
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 IMS 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: https://www.imsglobal.org/forums/ims-glc-public-forums-and-resources/open-badges-community-forum.
The IMS Logo is a trademark of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
For more information: https://www.imsglobal.org/trademarks
Documents Name: Open Badges Examples
Status of this Document
This document is made available for adoption by the public community at large.
Examples of Core Open Badges objects
Information is divided between badge objects that describe an individual earner’s accomplishment (Assertion), the general features of the achievement (BadgeClass), and the entity or organization issuing the badge (Issuer)
Assertion Example (definition)
An example of a badge Assertion using the hosted
verification method. This JSON object is “baked” into a badge image (optionally linked at the Assertion’s image
property) and also hosted at the location specified by the @id
and verify.url
properties.
BadgeClass Example (definition)
The BadgeClass is hosted at the URI identified in associated Assertions’ badge
property.
Notes:
- The JSON-LD data model treats
"property": ["value"]
as equivalent to"property": "value"
. An example of this is thatalignment
takes one or multiple AlignmentObjects. If only one value is present, it may or may not be included in[]
. Not all of the Open Badges properties accept multiple values. For instance,issuer
may only have one value. - Many
@id
-type fields may have a property that appears as an IRI/URI or as an embedded JSON object (with{}
). For example,issuer
may include an embedded copy of the issuer Profile. Verifiers should fetch the issuer Profile from its HTTPid
and in most cases treat the hosted value as the most up-to-date representation. In the case of signed-verification Assertions, an embeddedBadgeClass
or issuerProfile
can be interpreted to be the value claimed at the time of issue, thoughpublicKeys
referenced in an embedded issuerProfile
should not be trusted to belong to the issuer without checking the hosted Profile.
Issuer/Profile Example (definition)
Metadata about the issuer is defined in JSON at a URL/IRI defined by the BadgeClass’s issuer
property.
Extension Examples (definition)
Extensions are formal sets of properties issuers and platforms add to the Open Badges Vocabulary. A number of community-developed extensions are published on the Extensions page with embedded examples of each.
Open Badges in Linked Data
Because Open Badges are Linked Data objects often hosted at HTTP IRIs, we can use the methods of identifying connections using Badge Objects can identify their connected resources either by their string IRI or by embedding a copy of the related document into the source document. For example, an Assertion may include its BadgeClass definition for portability instead of just linking to the URI of the BadgeClass object. Here, the BadgeClass and its issuer Profile record have been included in the Assertion. Each has its “id” property set to the URI where it is published, the unique identifier for that object. Displayer platforms can use that value to index these records.
Notes:
- In this example, the
badge
property in the Assertion is expanded to offer a full BadgeClass record, but not all identifying URIs (@id
-type fields) are represented here as this type of expanded document. For example,criteria
andimage
properties just use a URI here instead of taking advantage of linked data classes for these items in the Specification. You may publish badge objects with a mix of URI references and expanded document formats that have indexableid
s. Properties that in v1.1 expected a String URI datatype may now encounter a{}
object containing anid
property and other metadata. All such properties are now listed in the spec as expecting an @id (linked data subject) expecting the IRI or document representation of a certain data class. - Because the properties describing the BadgeClass and issuer Profile are within the same context that’s included at the top of the JSON-LD document, you don’t need to include a new reference to the “@context” each time.
- Because this Assertion uses “hosted” verification, and there is no cryptographic signature to verify that the full document here is the exact one published by the issuer, verifier and displayer platforms will likely discard the embedded BadgeClass and issuer Profile here and replace them with the values discovered at their
id
URIs, because only those hosted documents can be trusted to be the creation of the issuer. If the Assertion uses “signed” verification, the validator may accept the embedded values as the intended BadgeClass and issuer Profile, and if they have multiple records for those entities that use the declaredid
, the validator may choose how to index and present that information. Issuers should change theid
s of their BadgeClasses when they make edits if they wish the edits to essentially be understood as a different achievement than the one published under the originalid
.
Additional Vocabulary Classes Examples
While the Assertion, BadgeClass, and Profile are the minimal set of JSON-LD resources necessary for a valid badge, there are several secondary data classes that extend the usefulness, security, and portability of Open Badges. The examples below are often abbreviated to highlight a specific feature, so not all examples contain all the required properties to constitute a valid Badge Object of their type.
Signed Badges Example (definition)
JSON Web Signatures, a branch of the JSON Object Signing and Encryption (JOSE) group of standards is a signature method accepted for Open Badges objects. A JSON Web Signature (JWS) for a signed Assertion is made up of three components, packaged as a string with .
s used as separators. (Space has been added here around the .
separators for clarity.) This example is not a valid JWS, as the referenced key on example.org does not exist.
When base64 decoded this corresponds to the three JSON objects below for a signed 2.0 Open Badge:
Claims:
Signature:
Using Cryptographic Keys
In the above example, a keypair with publicKey
identifier https://example.org/publicKey.json
was used to sign a badge Assertion. The following resources should exist for this to be a functional example:
Type | id | Description |
---|---|---|
Assertion | urn:uuid:a953081a-4bbd-4927-9653-7219bca00e3b |
There is no HTTP(s) id for this Assertion , because it was delivered as a JWS. It links to the BadgeClass document with the badge property. See immediately above. |
BadgeClass | https://example.org/robotics-badge.json |
A BadgeClass document that links to the Issuer. See above. |
Profile | https://example.org/organization.json |
A issuer Profile document that links to the CryptographicKey document with its publicKey property. See above |
PublicKey | https://example.org/publicKey.json |
A CryptographicKey document that links to the issuer Profile with its owner property. See below](#CryptographicKey). |
CryptographicKey Example (definition)
A public key document should describe an Open Badges issuer’s public key. For maximum compatibility, it should have its own HTTP(S) identifier, and should identify its issuer using the owner
property. The publicKeyPem
shown below has been abbreviated with ...
for readability.
RevocationList Example (definition)
Issuers may have a RevocationList if they use SignedBadge
verification. Checking this list is intended as part of the verification process for signed badges, just as checking for the hosted assertion is part of verifying a hosted badge. It is published as a JSON-LD document with type RevocationList
. RevocationLists are linked from an issuer Profile via the revocationList
property. The RevocationList identifies its issuer with the issuer
property.
RevocationLists may identify revoked Assertions through their revokedAssertions
property. Individual assertions are identified either by their id
or (legacy) uid
properties. id
-identified Assertions may appear in a RevocationList as that id string or as an object with an id
property and other metadata, usually just a revocationReason
. The below example shows id
s in the urn:uuid
namespace, which is a recommended namespace for signed Assertions that do not have a hosted (HTTP) id
.
Revoked Hosted Assertion Example (see more about Hosted Verification)
Revoked hosted Assertions should be returned with the HTTP status 410 Gone
. The response body may contain an Assertion document with "revoked": true
that contains additional metadata. It does not need to meet the full requirements of the Assertion
class. Only id
and revoked
properties must be present
Criteria Example (definition)
A BadgeClass’s criteria
field may be populated with a HTTP(s) URI string or an instance of the Criteria
class. Here, a URI is used:
Embedding criteria into the badge allows display platforms to render criteria information to viewers without directing them to an external website. It may be used in parallel to a criteria URI as follows:
The Criteria class may also appear without using an external URI to increase portability, as fewer information dependencies then exist outside of the JSON-LD metadata. Additionally, the narrative can be used to make complex links with the BadgeClass’s alignment targets.
Evidence Example (definition)
Metadata related to evidence may be included in Assertions in several ways.
The issuer may provide a text/Markdown narrative
describing the evidence:
Evidence may be referenced by URI id
:
Evidence may be more fully described by using the Evidence class:
It is possible to include multiple values for evidence in an Assertion. Evidence may be more fully described by using the Evidence class:
Image Example (definition)
In order to provide extra useful information for rendering images, sometimes additional metadata about images is included in Badge Objects using the Image
class.
Images are often referenced by their HTTP URI where they may be accessed. Displayers usually render this as the image source in HTML.
However, additional properties are available, and can be referenced wherever images appear in Badge Objects. For example, a caption
can aid in rendering alt text in browsers. If author
is used, it may be the id
of an Open Badges Profile, but it may be another id
that represents the author. Displayers should not assume this is a URI that will resolve to a compatible instance of a Profile
.
Social Media URLs in Profiles
When using the url
property of a profile to denote a social media account, use the canonical url of the account. For example, for a Twitter account, use https://twitter.com/OpenBadges
. For a Facebook page or account, the URL is in the format https://www.facebook.com/OpenBadges
.
BadgeClass Versioning
The version
property allows issuers to set a version number or string for a BadgeClass. This is particularly useful when replacing a previous version with an update.
Internationalization Examples
The string internationalization features of JSON-LD make it possible for issuers to declare which language a Badge Object is expressed in:
It is also possible to list multiple versions of Badge Objects to make available multiple equivalent versions of the same entity.
Notes:
- Language codes must be compatible with BCP47. Think “en” or “es-MX”.
- JSON-LD allows much more expressive combinations of multiple languages in one document. It is likely that you may be able to produce Badge Objects taking advantage of these features that will not be understood by some or all validators or display tools. It is recommended to keep implementations as simple as possible and communicate with the standards group when you want to move beyond the example techniques expressed here.
Endorsement Examples
An endorser can use an Endorsement
to indicate trust in an email address. Suppose the issuer Profile record above exists, but inspectors are unsure whether it is a trustworthy record that truly represents the organization it describes. Endorsements can show that an external party has verified one or more properties of the Issuer. Automated services could be developed to verify properties like email
or telephone
, and human verification services could provide more in-depth verification.
Here, an endorser claims to have verified the email address published in the Profile.
Another prominent use of Endorsements is to provide a comment expressing approval of a BadgeClass, that it is a good representation of the achievement it describes. The endorser could publish the following about the above BadgeClass.
The same method could be used to support a single recipient’s achievement through endorsing an Assertion
. Here the endorser also offers an addition to the evidence to be considered associated with the badge.
An Endorsement
may also be revoked by the Issuer. Here is an example of