IMS Final Release

Open Badges v2.0
IMS Final Release

Status of this Document

Introduction

This specification describes a method for packaging information about accomplishments, embedding it into portable image files as digital badges, and establishing resources for its validation. It includes term definitions for representations of data in Open Badges. These term definitions appear in the current JSON-LD context (v2.0) for the Open Badges Specification.

In other words, Open Badges contain detailed metadata about achievements. Who earned a badge, who issued it, and what does it mean? The data is all inside. A simple example:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/assertions/123",
  "type": "Assertion",
  "recipient": {
    "type": "email",
    "identity": "alice@example.org"
  },
  "issuedOn": "2016-12-31T23:59:59+00:00",
  "verification": {
    "type": "hosted"
  },
  "badge": {
    "type": "BadgeClass",
    "id": "https://example.org/badges/5",
    "name": "3-D Printmaster",
    "description": "This badge is awarded for passing the 3-D printing knowledge and safety test.",
    "image": "https://example.org/badges/5/image",
    "criteria": {
      "narrative": "Students are tested on knowledge and safety, both through a paper test and a supervised performance evaluation on live equipment"
    },
    "issuer": {
      "id": "https://example.org/issuer",
      "type": "Profile",
      "name": "Example Maker Society",
      "url": "https://example.org",
      "email": "contact@example.org",
      "verification": {
         "allowedOrigins": "example.org"
      }
    }
  }
}

Open Badges in Linked Data

Linked Data is a method of publishing data so that it can be understood in a variety of contexts. Open Badges are expressed in JSON-LD so that they can include and be included in documents outside the purposes considered in this specification. Open Badges take advantage of JSON-LD’s features for internationalization/localization, identifying objects by unique IRIs, and extensibility.

Open Badges are expressed as linked data so that badge resources can be connected. The issuer’s Profile in the above example is identified by the “id” https://example.org/issuer, which is a URL at which the profile can be discovered. Badge Objects, the instances of the data classes in the Open Badges Vocabulary, can link to one another’s hosted URLs or can embed representations of their connected resources for increased portability. See Linked Data examples.

Internationalization and Multilingual Badges

Open Badges are used by thousands of issuers around the world, and users of those badges speak many languages. Because Open Badges is a Linked Data vocabulary expressed in JSON-LD, there are some excellent features available to issuers and platforms to use Open Badges in their preferred language. See String internationalization in JSON-LD. Issuers can:

• Declare which language a Badge Object is expressed in using language tags compliant with BCP47.
• List multiple versions of Badge Objects to make available multiple equivalent versions of the same entity.

Additionally, developers who wish to write code in a language other than English can build a JSON-LD context file in their preferred language and then encounter badge property names familiar to them and their teams.

See Internationalization Examples.

Open Badges Vocabulary

The Open Badges Vocabulary defines several data classes used to express achievements that is understandable in software and services that implement Open Badges. There are three core data classes: Assertions, BadgeClasses, and Profiles. A set of one expression of each of these may be constructed into a valid Open Badge. Each data class is a collection of properties and values, and each defines which are mandatory and optional as well as the restrictions on the values those properties may take. They are published as JSON-LD for interoperability. If properties are included in JSON that cannot be mapped to JSON-LD terms defined in the object’s @context, they are not considered part of the badge object’s meaning.

Extensions:

Each Badge Object may have additional properties beyond those defined here. Some of these additional properties may take the form of an Open Badges Extension, a structure that follows a standard format for collaboratively extending Badge Objects so that any issuer, earner, or consumer can understand the information added to badges. (More…)

Assertion (example)

Assertions are representations of an awarded badge, used to share information about a badge belonging to one earner. Assertions are packaged for transmission as JSON objects with a set of mandatory and optional properties. Fields marked in bold letters are mandatory.

Deprecated properties still in use by some implementations:

• uid – String – Unique Identifier for the badge. This is expected to be locally unique on a per-issuer basis and for hosted badges on a per-origin basis. It may not be necessarily globally unique. uid has been replaced by the IRI-based id property. It should not be used in v2.0+ Assertions.

BadgeClass (example)

A collection of information about the accomplishment recognized by the Open Badge. Many assertions may be created corresponding to one BadgeClass

Profile (example)

A Profile is a collection of information that describes the entity or organization using Open Badges. Issuers must be represented as Profiles, and recipients, endorsers, or other entities may also be represented using this vocabulary. Each Profile that represents an Issuer may be referenced in many BadgeClasses that it has defined. Anyone can create and host an Issuer file to start issuing Open Badges. Issuers may also serve as recipients of Open Badges, often identified within an Assertion by specific properties, like their url or contact email address. An Issuer Profile is a subclass of the general Profile with some additional requirements.

Extensions

The 1.1 version of the Open Badges Specification introduces Extensions as a means for issuers to add additional metadata to Badge Objects beyond what the standard specifies itself. Additional properties are allowed without using Extensions, but Extensions allow issuers to declare how they are adding information so that it can be understood by others and other issuers can add the same sort of information in a compatible way.

See the Extensions page for specific examples and extensions ready to use in Badge Objects.

Extension authors define and host a new JSON-LD context file describing all the terms the extension covers. These context files may further define any JSON-schema that implementations of the extension should pass. If used, each schema is linked from the context and hosted as a separate JSON-schema files. Extensions are implemented in Open Badges as JSON objects inside an Assertion, BadgeClass or Issuer with their own link to the extension context and declaration of type.

An extension value should be included as a JSON object containing the @context and @type properties and any new properties whose names are mapped in the context file referenced by @context.

The property name for the extension should map to an IRI within the @context defined at the root of the extended Badge Object. It is possible to use a fully qualified IRI (e.g. http://example.org/newBadgeExtension) or a compact IRI within the extension namespace defined in the OBI context, like extension:newBadgeExtension. In either case, the IRI should correspond to where a human-readable definition of the extension resides. For extensions using the extension namespace, this definition may be contributed to the community extensions repository on this site.

See example extensions.

Extension Validation

Open Badges v1.1 implements an optional JSON-schema based mechanism of ensuring badge objects conform to syntactic requirements of the specification. JSON-schema can ensure that required properties exist and that expected data types are used. From the contexts for badge objects and extensions, a validation array may contain links to various JSON-schema against which badge objects may be tested. There are two proposed methods of specifying which component of a badge object should be matched against the JSON-schema validator: TypeValidation and FrameValidation. As of 1.1, only TypeValidation is implemented.

For example, this portion of the current Open Badges context links to a validator for Assertions. It indicates through TypeValidation that it should be run against JSON objects with the JSON-LD type of Assertion ([https://w3id.org/openbadges#Assertion]).

{
  ...
  "validation": [
    {
      "type": "TypeValidation",
      "validatesType": "Assertion",
      "validationSchema": "https://openbadgespec.org/v1/schema/assertion.json"
    },
    ...
  ]
}

Type Validation

Validators using the TypeValidation method match the schema indicated by the validator’s validationSchema property against a JSON badge object document or portion of such a document that matches the validator’s validatesType JSON-LD type.

It is important that the value of the validatesType property be a valid JSON-LD type (an IRI), as that IRI appears when compacted into the Open Badges context, because validation matches this type value here against compacted values as they appear in an extension implementation. In order to correctly identify the extension within the badge object that includes it, an exact match here is expected.

Frame Validation

status: proposed Validators that someday use the proposed FrameValidation method pass JSON-LD objects through the JSON-LD Frame indicated by the validationFrame property and test the result against the JSON-schema indicated by the validator’s validationSchema property.

Endorsement (example)

Open Badges are trustworthy records of achievement. The vocabulary defined above, combined with the validation and verification procedures for badge Assertions, establish Open Badges as a reliable method for expressing and verifying achievements online. However, these procedures don’t answer questions like, “Who trusts this BadgeClass to be a good certification of the competency it describes?” or, “Is this Profile’s email address verified?” For these questions, there is Endorsement.

Endorsement leans on the Verifiable Claims work prototyped by members of the Verifiable Claims Task Force at the W3C and the theoretical backing developed by the 2014 Endorsement Working Group.

The Endorsement Class is very similar to Assertion, except that there is no defined badge property. Instead, a claim property allows endorsers to make specific claims about other Profiles, BadgeClasses, or Assertions.

Within the claim property, the endorsed entity may be of any type (though only Open Badges Vocabulary classes are expected to be understood by Open Badges-specific tools. While Endorsement is a very flexible data structure, its usefulness will be limited not by the creativity of endorsers, but by the ability for other tools to discover and understand those endorsements.

There is one special property for use in endorsement, the endorsementComment, which allows endorsers to make a simple claim in writing about the entity.

Endorsements use the claim property to identify another entity by its id and declare properties about it. For example, the following allows an issuer to offer their own claim that an email address belongs to the profile identified as https://otherissuer.example/1 and make a comment about the quality of their badges.

{
 "@context": "https://w3id.org/openbadges/v2",
 "type": "Endorsement",
 "id": "https://example.org/assertions/123",
 "issuer": "https://example.org/issuer",
 "issuedOn": "2016-12-31T23:59:59+00:00",
 "claim": {
   "id": "https://otherissuer.example/1",
   "email": "contact@otherissuer.example",
   "endorsementComment": "A great provider of badged learning."
 },
 "verification": {
   "type": "hosted"
 }
}

See more examples

Additional Properties

Badges consist of sets of claims, properties with values that apply to Profiles, all earners of a badge, or individual badge recipients. Outside of extensions, additional properties may be added to these claim sets so long as they are mapped to an IRI as JSON-LD. For example, publishers of Badge Objects may:

1. Add individual mappings to the Badge Object’s context: "@context":["https://w3id.org/openbadges/v2", {"foo": "http://example.org/foo"}]
2. Link to additional context files in the Badge Object’s context: "@context":["https://w3id.org/openbadges/v2", "http://example.org/context"]
3. Add new properties using full IRIs as keys (or with compact IRIs valid in the existing context): "http://example.org/foo":"bar" or "schema:comment":"baz" where the IRI leads to the vocabulary definition for the term.

Processors should preserve properties that are valid data when rehosting or retransmitting, but it is permissible to perform valid JSON-LD transformations. Such transformations include “expanding”, “compacting” and modifying the context. Transformations are assumed to be equivalent if the expanded or normalized RDF value of the new version is semantically equivalent to the expanded value of the original.

If a property would be useful beyond a publisher’s internal use, an Extension is a recommended way to establish common practice for adding certain sets of information to badge objects.

Primitive datatypes

• Boolean - A JSON boolean value as defined in RFC4627)
• Text - A JSON string value as defined in RFC4627)
• Array - A JSON array as defined in RFC4627). Arrays are used for all properties where multiple values are allowed when multiple values are used. Each entry in the array must match the type requirement specified for that property.
• DateTime - Open Badges must express timestamps as strings compatible with ISO 8601 guidelines, including the time and a time zone indicator. It is recommended to publish all timestamps in UTC. Previous versions of Open Badges allowed Unix timestamps as integers. Open Badges v2.0 requires string ISO 8601 values with time zone indicators. For example, 2016-12-31T23:59:59+00:00 is a valid ISO 8601 timestamp. It contains the year, month, day, T separator, hour number 0-23, minute, optional seconds and decimal microsecond, and a time zone indicator (+/- an offset from UTC or the Z designator for UTC).
• URL - Fully qualified URL, including protocol, host, port if applicable, and path. Interpreters are only expected to interpret URLs in either the http or https schemes.
• IRI - In JSON-LD and Linked Data, IRIs (Internationalized Resource Identifiers) may look like fully qualified URLs or be namespaced within the JSON-LD context to be expanded to a full IRI. The only known supported IRI schemes are http and https.
• IdentityHash - A hash string containing an algorithm identifier and a resulting hash of an identifier, separated by a dollar sign (“$”) and the algorithm used to generate the hash. The only supported algorithms are MD5 and SHA-256, identified by the strings md5 and sha256 respectively. Resulting hash for each of these algorithms MUST be expressed in hexadecimal using uppercase (A-F, 0-9) or lowercase character (a-f, 0-9) sets. For example: sha256$7a1a1b3f7d40552e4299180e346e3add12bf9a751a43d9c4ca4518febc2c60c6 represents the result of calculating a SHA-256 hash on the string “mayze”. For more information, see how to hash & salt in various languages.
• Markdown Text - Text that may contain formatting according to Markdown syntax. Due to uneven support in displayers, publishers are encouraged to limit usage to simple elements like links, emphasis, and lists. Displayers may choose a subset of Markdown formatting to support or how to render this field. Images and tables may or may not be supported.

Implementation

Publishing Badge Objects

Open Badges data is published as JSON-LD documents made up of the above data classes. These link together via use of common identification strings and properties. They rely on other data, including image files that are often hosted on HTTP(s) URIs outside of the JSON-LD documents that describe them.

Setting Content-Type

Badge Objects encoded in JSON-LD should be served with the application/ld+json content type by default. If the request indicates only application/json as the Accept type, responses should include application/json in the response content type. If request is made for text/html or other content-type above application/ld+json or application/json, the requested content-type may be returned.

Badge Baking

Badge assertions may be “baked” into image files as portable credentials. Baking is currently supported for PNG and SVG formats. (See Baking Specification for implementation)

Data Validation

Data Validation is a procedure that ensures a cluster of Badge Objects that make up an Open Badge are appropriately published and linked, and that each particular instance of a Badge Object conforms to requirements for its class. Validation of all data class instances used in an Open Badge is a part of badge verification.

Validation includes tests to ensure that:

• All required Badge Objects are appropriately linked and available to the validator with an eventual 200 OK.
• Any relevant optional Badge Objects that are linked (such as RevocationLists) are available.
• Each Badge Object is a valid JSON-LD (Linked Data) document.
• Each Badge Object contains all required properties for its class.
• Each Badge Object contains values of the expected data type for all declared properties defined in the Vocabulary.

The use of the term “eventual 200 OK” is meant to mean that 3xx redirects are allowed, as long as the request eventually terminates on an appropriate resource that returns a 200 OK.

Verification

Verification is the process of ensuring the data that makes up an Open Badge is correct for the purpose at hand. 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.

Verification includes tests to ensure that:

• All Badge Objects pass data validation. See Data Validation above.
• All Badge Objects were created by the appropriate issuer Profile(s) according to rules declared in their VerificationObjects.
• The Assertion was awarded to a valid property value of the expected recipient. (For example, that the Asssertion was awarded to a known email address value for email type recipient IdentityObject.)
• The Assertion issuer is authorized to award Assertions of the declared BadgeClass (typically by being the issuer of the BadgeClass.)
• The Assertion has not expired.
• The Assertion has not been revoked by the issuer.

Additional checks may ensure that:

• The issuer Profile awarding the Assertion is trusted to have declared accurate information about its identity (typically via Endorsement).

HostedBadge Verification

A hosted Assertion is a file containing validated Assertion data in JSON-LD served with the content-type application/ld+json and/or application/json. This should be available to anyone who the recipient would like to be able to verify it at a stable URI on your server (for example, https://example.org/assertions/robotics-badge/123.json). This URI is the source of truth for the badge, and any verification attempt will request it to make sure the Assertion exists and describes the expected achievement. Redirects are permissible as long as appropriate Assertion content is eventually returned. The hosting application must properly set the content-type.

The Assertion id must be within the permitted scope for hosted verification declared in issuer Profile. See VerificationObject. This defaults to requiring the Assertion and BadgeClass to be hosted on the same origin as the issuer Profile id if there is no verification property declared in the issuer Profile. For domain origins that host multiple applications and websites, startsWith path may be used, in which case, the verificationProperty (id) must start with the value found in the issuer Profile’s VerificationObject startsWith declaration.

Steps to verify a hosted badge Assertion: Verification of hosted assertions may be performed starting with the verification URL or with a full Assertion instance in hand. If starting with a full assertion that indicates HostedBadge verification, the input data should only be trusted to identify the URI of the hosted verification file, and upon loading the hosted verification file, the retrieved data should be used as the Assertion value.

Revoking Hosted Assertions (example)

To mark a hosted assertion as revoked, respond with an HTTP Status of 410 Gone. The response may include an Assertion body containing some additional metadata, such as a revocationReason, but it is not required to meet all normal property presence requirements. For revoked Assertions, only id and revoked are required.

If either the 410 Gone status or a response body declaring revoked true is returned, the Assertion should be treated as revoked and thus invalid.

SignedBadge Verification (example)

A signed badge may be published in the form of a JSON Web Signature. If so, the JSON representation of the badge assertion should be used as the JWS payload.

A JWS has three components separated by dots (.):

header.payload.signature

The JSON-LD representation of the Assertion should be used as the JWS payload. For compatibility purposes, using RSA-SHA256 is recommended.

The public key corresponding to the private key used to the sign the badge should be publicly accessible via HTTP and specified in the issuer Profile’s publicKey property. If there are multiple keys declared in the issuer Profile, the Assertion’s VerificationObject may specify the id of the public key that should be used for verification with its creator property.

Steps to verify a JWS-signed badge Assertion:

1. Base64 decode the JWS payload. This will be a JSON string representation of the badge assertion.
2. Parse the decoded JWS body into a JSON object. If the parsing operation fails, assertion MUST be treated as invalid.
3. Perform data validation on the Assertion and the (embedded or linked) BadgeClass and issuer Profile, as well as any other relevant present data.
4. Determine the correct signing key id(s) to test against the signature from the valid issuer Profile and Assertion VerificationObject. Do not trust a key that is not properly linked from the issuer Profile.
5. Perform an HTTP GET request on the trusted keys. If it is impossible to get a usable public key, the Assertion cannot be verified.
6. With each trusted public key, perform a JWS verification on the JWS object. If the verification fails, assertion MUST be treated as invalid.
7. Retrieve the revocation list from the Issuer Profile object if present and ensure the id of the badge does not appear in the revokedAssertions list. Legacy v1.x badges that lack a id property may be identified in this list by their uid.
8. If the above steps pass, assertion may be treated as valid.

Other signature suites may be later included in this document if they are investigated and approved.

Revoking a Signed Badge

To mark a badge as revoked, add an entry to the resource pointed at by the Issuer Profile revocationList URL with the id of the Assertion and, optionally, a reason why the badge is being revoked. See an example.

History

• From 1.1 to 2.0 (includes 2.0 errata)
• From 1.0 to 1.1
• From 0.5 to 1.0
• Early history of the specification

List of Contributors

• Jeff Bohrer, IMS Global
• Timothy F. Cook, LRNG
• Maria Esquela, eNABLE Community
• Steve Gance, Washington State Board of Community and Technical Colleges
• Jim Goodell, QIP/CEDS
• Markus Gylling, IMS Global
• Viktor Haag, D2L
• Alex Hripak, Credly
• Kerrie Lemoie, OpenWorks Group
• Mark Leuba, IMS Global
• Randy Macdonald, Innovation Academy / InnovateOregon
• Nate Otto, Concentric Sky
• Justin Pitcher, Chalk & Wire
• Serge Ravet, ADPIOS, BadgeEU
• Alex Reis, D2L
• Jarin Schmidt, Pearson Acclaim
• Attila Szabo-Nagy, Erasmus+