diff --git a/ob_v2p0/examples/index.md b/ob_v2p0/examples/index.md index 2f3ae110..e261590e 100644 --- a/ob_v2p0/examples/index.md +++ b/ob_v2p0/examples/index.md @@ -557,6 +557,7 @@ Here, an endorser claims to have verified the email address published in the Pro "type": "Endorsement", "id": "https://example.org/endorsement-123.json", "issuer": "https://example.org/issuer-5.json", + "issuedOn": "2016-12-31T23:59:59+00:00", "claim": { "id": "https://example.org/organization.json", "email": "contact@example.org", @@ -574,6 +575,7 @@ Another prominent use of Endorsements is to provide a comment expressing approva "type": "Endorsement", "id": "https://example.org/endorsement-124.json", "issuer": "https://example.org/issuer-5.json", + "issuedOn": "2016-12-31T23:59:59+00:00", "claim": { "id": "https://example.org/robotics-badge.json", "endorsementComment": "This badge and its associated learning material are great examples of beginning robotics education." @@ -591,6 +593,7 @@ The same method could be used to support a single recipient's achievement throug "type": "Endorsement", "id": "https://example.org/endorsement-125.json", "issuer": "https://example.org/issuer-5.json", + "issuedOn": "2016-12-31T23:59:59+00:00", "claim": { "id": "https://example.org/beths-robotics-badge.json", "endorsementComment": "This student built a great robot.", @@ -601,3 +604,15 @@ The same method could be used to support a single recipient's achievement throug } } {% endhighlight %} + +An `Endorsement` may also be revoked by the Issuer. Here is an example of +{% highlight json %} +{ + "@context": "https://w3id.org/openbadges/v2", + "type": "Endorsement", + "id": "https://example.org/endorsement-125.json", + "issuer": "https://example.org/issuer-5.json", + "revoked": true, + "revocationReason": "Issued in error." +} +{% endhighlight %} diff --git a/ob_v2p0/extensions/endorsement/index.md b/ob_v2p0/extensions/endorsement/index.md index 4df0ba61..a3dd507b 100644 --- a/ob_v2p0/extensions/endorsement/index.md +++ b/ob_v2p0/extensions/endorsement/index.md @@ -9,7 +9,7 @@ The Endorsement extension is deprecated since v2.0, with the addition of [Endors ### Endorsement _Author: [Nate Otto](http://ottonomy.net)_ -Any organization that is set up to issue badges may provide endorsements of other issuers' badge objects (Assertion, Badge Class or Issuer). For example, a school district may issue an endorsement to indicate approval of a specific Badge Class corresponding to professional development credits acceptable by the district. See the Badge Alliance Endorsement Working Group [framework paper](https://docs.google.com/document/d/1VVf19d72KmGMh1ywrLe7HCKEOqGSI0WjvwfGN_8Q2M4/edit) for background. +Any organization that is set up to issue badges may provide endorsements of other issuers' badge objects (Assertion, Badge Class or Issuer). For example, a school district may issue an endorsement to indicate approval of a specific Badge Class corresponding to professional development credits acceptable by the district. Endorsement of a Badge Class serves to publicly acknowledge the value of a badge as *designed, assessed, and issued by a badge issuer*. Endorsements of an Issuer are presumed to apply to all Badge Classes and Assertions created by that Issuer. See the [context](./endorsement/context.json) and [schema](./endorsement/schema.json) for endorsement. diff --git a/ob_v2p0/faq/index.md b/ob_v2p0/faq/index.md index 0e122db9..ddf91054 100644 --- a/ob_v2p0/faq/index.md +++ b/ob_v2p0/faq/index.md @@ -171,7 +171,7 @@ Join the [Badge Alliance Standard Working Group](https://groups.google.com/forum Official proposals are made by contributing a pull request on GitHub. Pull requests let you tell others about changes you've pushed to a GitHub repository. -Go to the [Open Badges spec repository](https://github.com/openbadges/openbadges-specification), then fork the code, modify it, and save it back to your forked repository. Submit a pull request to the origin repository master branch to initiate a review of the proposed changes. +Go to the [Open Badges spec repository](https://github.com/openbadges/openbadges-specification), then fork the code, modify it, and save it back to your forked repository. Submit a pull request to the origin repository main branch to initiate a review of the proposed changes. Once a pull request is sent, interested parties can review the set of changes and discuss potential modifications before deciding whether and how to integrate them. The Standard Working Group makes a call for consensus, and if successful, merges the proposed changes. diff --git a/ob_v2p0/history/2.0.md b/ob_v2p0/history/2.0.md index 1b069670..834bbd43 100644 --- a/ob_v2p0/history/2.0.md +++ b/ob_v2p0/history/2.0.md @@ -38,11 +38,14 @@ Open Badges 2.0 contains a minimal set of breaking changes. For issuers, it will Since the 2.0 specification was published on January 1st 2017, a few errors and typos have been discovered and corrected in-place on [openbadgespec.org](http://www.openbadgespec.org). -For full transparency, these edits can be reviewed at the [GitHub Open Badges master branch commit history page](https://github.com/openbadges/openbadges-specification/commits/master). The first in-place edit was committed on January 10th of 2017. +For full transparency, these edits can be reviewed at the [GitHub Open Badges main branch commit history page](https://github.com/openbadges/openbadges-specification/commits/master). The first in-place edit was committed on January 10th of 2017. Additional errata: * April 9th of 2020 the work group decided to require usage of PNG or SVG for all images under this specification. +* In October 2020, the work group indicated that an error with the `targetFramework` term in the [V2 Context](https://w3id.org/openbadges/v2) should be corrected in place. This term previously referenced a non-existent `schema:targetFramework` term when the appropriate term in schema.org's vocabulary is [educationalFramework](http://schema.org/educationalFramework). An impact analysis was performed resulting in a conclusion that there would be very little effect on implementations in any role. +* February 11th of 2021 the work group updated the Endorsement examples to include the required issuedOn property for completeness. +* February 11th of 2021 the work group decided to transition to a "main" branch as part of a [larger initiative](https://github.com/github/renaming). +* In February 2021, the description of `validatesType` was improved to indicate how exact matching is handled. +* March 11th of 2021 the work group updated the Endorsement documentation to include revocation funtionality that had already been possible. Please note that the IMS Global version of the Open Badges specification, which contains additional formatting and layout changes, are not reflected in the master repository commit history. - - diff --git a/ob_v2p0/index.md b/ob_v2p0/index.md index 8163ac25..a9d7e133 100644 --- a/ob_v2p0/index.md +++ b/ob_v2p0/index.md @@ -1,5 +1,5 @@ --- -title: Open Badges v2.0 +title: Open Badges v2.0 subtitle: A vocabulary for portable digital credentials developed by IMS Global show_sidebar: false --- @@ -33,7 +33,7 @@ show_sidebar: false
- + **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. @@ -95,7 +95,7 @@ The following participating organizations have made explicit license commitments Copyright © 2018 IMS Global Learning Consortium. All Rights Reserved. - + 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. @@ -112,7 +112,7 @@ Public contributions, comments and questions can be posted here: [https://www.im _Documents Name: {{page.title}}_ -_Revision: 12 April 2018_ +_Revision: 21 May 2021_
@@ -127,11 +127,11 @@ This document is made available for adoption by the public community at large.
- + ## Contents * [Introduction](#intro-example) - [Linked Data](#LinkedData) - - [Internationalization and Multilingual Badges](#Internationalization) + - [Internationalization and Multilingual Badges](#Internationalization) * [Open Badges Vocabulary](#BadgeObjects) - [Assertion](#Assertion) - [BadgeClass](#BadgeClass) @@ -208,7 +208,7 @@ Open Badges are expressed as linked data so that badge resources can be connecte ### 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](http://json-ld.org/spec/latest/json-ld/#string-internationalization). Issuers can: +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](http://json-ld.org/spec/latest/json-ld/#string-internationalization). Issuers can: * Declare which language a Badge Object is expressed in using language tags compliant with [BCP47](https://tools.ietf.org/html/bcp47). * List multiple versions of Badge Objects to make available multiple equivalent versions of the same entity. @@ -222,7 +222,7 @@ See [Internationalization Examples](./examples/index.html#Internationalization). 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](#Assertion)**, **[BadgeClasses](#BadgeClass)**, and **[Profiles](#Profile)**. 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](http://www.w3.org/TR/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](#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...](#Extensions)) ### Assertion ([example](./examples/index.html#Assertion)) @@ -239,15 +239,15 @@ Assertions are representations of an awarded badge, used to share information ab | **verification** | [VerificationObject](#VerificationObject) | Instructions for third parties to verify this assertion. (Alias "verify" may be used in [context](v2/context.json).) | **issuedOn** | [DateTime](#dateTime) | Timestamp of when the achievement was awarded. | image | @id: [Image](#Image) | IRI or document representing an image representing this user's achievement. This must be a PNG or SVG image, and should be prepared via the [Baking specification](./baking/index.html). An 'unbaked' image for the badge is defined in the [BadgeClass](#BadgeClass) and should not be duplicated here. -| evidence | @id: [Evidence](#Evidence) ([Multiple values allowed](#array)) | IRI or document describing the work that the recipient did to earn the achievement. This can be a page that links out to other pages if linking directly to the work is infeasible. -| narrative | Text or [Markdown Text](#MarkdownText) | A narrative that connects multiple pieces of evidence. Likely only present at this location if `evidence` is a multi-value array. +| evidence | @id: [Evidence](#Evidence) ([Multiple values allowed](#array)) | IRI or document describing the work that the recipient did to earn the achievement. This can be a page that links out to other pages if linking directly to the work is infeasible. +| narrative | Text or [Markdown Text](#MarkdownText) | A narrative that connects multiple pieces of evidence. Likely only present at this location if `evidence` is a multi-value array. | expires | [DateTime](#dateTime) | If the achievement has some notion of expiry, this indicates a timestamp when a badge should no longer be considered valid. After this time, the badge should be considered expired. | revoked | Boolean | Defaults to `false` if Assertion is not referenced from a [`revokedAssertions`](#revokedAssertions) list and may be omitted. See [RevocationList](#RevocationList). If `revoked` is true, only `revoked` and `id` are required properties, and many issuers strip a hosted Assertion down to only those properties when revoked. -| revocationReason | Text | Optional published reason for revocation, if revoked. +| revocationReason | Text | Optional published reason for revocation, if revoked.
-**Deprecated properties still in use by some implementations**: +**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. @@ -309,7 +309,7 @@ A collection of information about the recipient of a badge. Property | Expected Type | Description --------|------------|----------- **identity** | [identityHash](#identityHash) or Text | Either the hash of the identity or the plaintext value. If it's possible that the plaintext transmission and storage of the identity value would leak personally identifiable information where there is an expectation of privacy, it is strongly recommended that an IdentityHash be used. -**type** | property IRI | The property by which the recipient of a badge is identified. This value should be an IRI mapped in the present context. For example, `email` maps to `http://schema.org/email` and indicates that the `identity` of the `IdentityObject` will represent a value of a [Profile's](#Profile) `email` property. Currently the only supported value for many platforms that implement Open Badges is `email`, but other properties are available. See [Profile Identifier Properties](#ProfileIdentifierProperties). +**type** | property IRI | The property by which the recipient of a badge is identified. This value should be an IRI mapped in the present context. For example, `email` maps to `http://schema.org/email` and indicates that the `identity` of the `IdentityObject` will represent a value of a [Profile's](#Profile) `email` property. See [Profile Identifier Properties](#ProfileIdentifierProperties). **hashed** | Boolean | Whether or not the `identity` value is hashed. salt | Text | If the recipient is hashed, this should contain the string used to salt the hash. If this value is not provided, it should be assumed that the hash was not salted. @@ -354,7 +354,7 @@ If both the `description` and `narrative` properties are present, displayers can Property | Expected Type | Description ---------|---------------|----------- type | JSON-LD Type ([Multiple values allowed](#array)) | Defaults to [Evidence](#Evidence). -id | IRI | The URI of a webpage presenting evidence of achievement. +id | IRI | The URI of a webpage presenting evidence of achievement. narrative | Text or Markdown Text | A narrative that describes the evidence and process of achievement that led to an Assertion. name | Text | A descriptive title of the evidence. description | Text | A longer description of the evidence. @@ -363,7 +363,7 @@ audience | Text | A description of the intended audience for a piece of -For evidence that is ephemeral or completely described within an Assertion via use of the Evidence class, if it is necessary to identify this evidence piece uniquely in an overall narrative, an `id` of type `urn:uuid` or otherwise outside the HTTP scheme may be used, but displayers may have less success displaying this usage meaningfully. +For evidence that is ephemeral or completely described within an Assertion via use of the Evidence class, if it is necessary to identify this evidence piece uniquely in an overall narrative, an `id` of type `urn:uuid` or otherwise outside the HTTP scheme may be used, but displayers may have less success displaying this usage meaningfully. ### Image ([example](./examples/index.html#Image)) @@ -382,7 +382,7 @@ author | @id: Profile | The author of the image, if desired. ### Criteria ([example](./examples/index.html#Criteria)) -Descriptive metadata about the achievements necessary to be recognized with an `Assertion` of a particular `BadgeClass`. This data is added to the `BadgeClass` so that it may be rendered when that `BadgeClass` is displayed, instead of simply a link to human-readable criteria external to the badge. Embedding criteria allows either enhancement of an external criteria page or increased portability and ease of use by allowing issuers to skip hosting the formerly-required external criteria page altogether. +Descriptive metadata about the achievements necessary to be recognized with an `Assertion` of a particular `BadgeClass`. This data is added to the `BadgeClass` so that it may be rendered when that `BadgeClass` is displayed, instead of simply a link to human-readable criteria external to the badge. Embedding criteria allows either enhancement of an external criteria page or increased portability and ease of use by allowing issuers to skip hosting the formerly-required external criteria page altogether. Criteria is used to allow would-be recipients to learn what is required of them to be recognized with an `Assertion` of a particular `BadgeClass`. It is also used after the `Assertion` is awarded to a recipient to let those inspecting earned badges know the general requirements that the recipients met in order to earn it. @@ -392,7 +392,7 @@ Property | Expected Type | Description ----------|---------------|----------- type | JSON-LD Type ([Multiple values allowed](#array))| Defaults to [Criteria](#Criteria). id | IRI | The URI of a webpage that describes in a human-readable format the criteria for the BadgeClass. -narrative | Text or [Markdown Text](#MarkdownText) | A narrative of what is needed to earn the badge. +narrative | Text or [Markdown Text](#MarkdownText) | A narrative of what is needed to earn the badge. @@ -410,18 +410,18 @@ Property | Expected Type | Description **targetUrl** | URL | URL linking to the official description of the alignment target, for example an individual standard within an educational framework. targetDescription | Text | Short description of the alignment target. targetFramework | Text | Name of the framework the alignment target. -targetCode | Text | If applicable, a locally unique string identifier that identifies the alignment target within its framework and/or `targetUrl`. +targetCode | Text | If applicable, a locally unique string identifier that identifies the alignment target within its framework and/or `targetUrl`. In order to render displays of alignment within badge services, `targetName` is required. In order to accurately identify targets, `targetUrl` is required. In the event that `targetUrl` cannot be specific enough to identify the item, `targetCode` may be used to indicate specifically which item within the targetUrl is the alignment target. -**Note:** Open badges v1.x used `schema:name`, `schema:description, and `schema:url`. v2.0 updates the AlignmentObject to use the proper linked data IRIs from the Schema.org vocabulary. +**Note:** Open badges v1.x used `schema:name`, `schema:description, and `schema:url`. v2.0 updates the AlignmentObject to use the proper linked data IRIs from the Schema.org vocabulary. ### Revocation List ([example](./examples/index.html#RevocationList)) -The Revocation List is a document that describes badges an Issuer has revoked that used the `signed` verification method. If you find the badge in the `revokedAssertions` list, it has been revoked. +The Revocation List is a document that describes Assertions or Endorsements that an Issuer has revoked that used the `signed` verification method. If you find the badge in the `revokedAssertions` list, it has been revoked. -An assertion reference may look like `{"id": "https://example.org/1", "revocationReason": "Violation of policy"}` or simply the string `"https://example.org/1"`. A UID-based reference may look like `{"uid": "abc123", "revocationReason": "Awarded in error"}` +An revoked reference may look like `{"id": "https://example.org/1", "revocationReason": "Violation of policy"}` or simply the string `"https://example.org/1"`. A UID-based reference may look like `{"uid": "abc123", "revocationReason": "Awarded in error"}`
@@ -432,12 +432,12 @@ id | IRI | The `id` of the RevocationList. issuer | IRI: Profile | The `id` of the Issuer. **revokedAssertions** | `Assertion` ([Multiple values allowed](#array)) | A string `id` or UID-based identification of a badge object that has been revoked. -**Revoked Assertions referenced by revokedAssertions array:** Properties from [Assertion](#Assertion) in scope for those that have been revoked. Implementers generally only include these properties, clearing out the values that were in place before revocation. An identifying property must be used, either `id` or (legacy) `uid`. If the issuer does not wish to declare a revocation reason or additional metadata, the `id` of the `Assertion` may be included alone either as a single string entry to the list or in an object that defines an `id` property. +**Revoked Assertions referenced by revokedAssertions array:** Properties from [Assertion](#Assertion) or [Endorsement](#Endorsement) in scope for those that have been revoked. Implementers generally only include these properties, clearing out the values that were in place before revocation. An identifying property must be used, either `id` or (legacy) `uid`. If the issuer does not wish to declare a revocation reason or additional metadata, the `id` of the `Assertion` may be included alone either as a single string entry to the list or in an object that defines an `id` property. Property | Expected Type | Description ---------|---------------|----------- type | JSON-LD Type ([Multiple values allowed](#array)) | Defaults to `Assertion`. May be omitted. -id | IRI | The `id` of the revoked Assertion. +id | IRI | The `id` of the revoked Assertion or Endorsement. uid | Text | Legacy identifier for pre-1.1 badges that did not use an IRI-based `id`. revoked | Boolean | `true` if the Assertion is revoked. Defaults to true if present in a `revokedAssertions` list and may be omitted. revocationReason | Text | The published reason for revocation if desired. @@ -446,7 +446,7 @@ uid | Text | Legacy identifier for pre-1.1 badges that did not use ### CryptographicKey ([example](./examples/index.html#CryptographicKey)) -Alias for the [Key](https://web-payments.org/vocabs/security#Key) class from the [W3C Web Payments Community Group Security Vocabulary](https://web-payments.org/vocabs/security). A CryptographicKey document identifies and describes a Key used for signing Open Badges documents. +Alias for the [Key](https://web-payments.org/vocabs/security#Key) class from the [W3C Web Payments Community Group Security Vocabulary](https://web-payments.org/vocabs/security). A CryptographicKey document identifies and describes a Key used for signing Open Badges documents. For best compatibility with verification procedures, the `Profile` should be hosted at its HTTPS `id` and should identify a `publicKey` by the HTTPS `id` of a `CryptographicKey` document that identifies its issuer by the issuer's `id` using the `owner` property. This allows convenient and robust usage of these `id`s to identify both the issuer and the key used. @@ -484,14 +484,14 @@ endorsement | @id: [Endorsement](#Endorsement) [Multiple values allowed](#array) ## Profile Identifier Properties When profiles are referenced elsewhere in the Open Badges Specification, they may be identified precisely by dereferencable id, such as when a BadgeClass links to an issuer Profile by its `id` URL. Other times, such as when identifying the [recipient](#recipient) of an [Assertion](#Assertion), Profiles may be identified by the value of a specific property unique to the individual or organization represented in a Profile. All properties that serve as profile identifiers must have values with a string datatype. +While not restricted to just `email`, currently most platforms that allow badge issuers and recipients to establish their identities as Profiles only support `email` (`https://schema.org/email`) as an identifier property. + **Properties considered serviceable identifiers include:** * `email` * `url` * `telephone` -Many platforms that allow badge issuers and recipients to establish their identities as Profiles support only `email` (`https://schema.org/email`) as an identifier property. -
@@ -509,11 +509,11 @@ Property | Expected Type | Description --------|------------|----------- **@context** | URL | JSON-LD context file shared among all implementations of the extension. **type** | IRI ([Multiple values allowed](#array)) | IRI or compact IRI within the OBI or extension context that describe the type of data contained in the extension. The IRI is used to map optional JSON-schema validation to the extension. Must include 'extension' as one element. -\*anyProperties | Any | Any property names defined in the extension context may be used with any valid JSON value. +\*anyProperties | Any | Any property names defined in the extension context may be used with any valid JSON value. -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`. +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](./v2/context.json), 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](./extensions/index.html) on this site. @@ -538,16 +538,17 @@ For example, this portion of the current Open Badges context links to a validato } {% endhighlight %} -#### Type Validation +#### 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.
Property | Expected Type | Description/expected value --------|------------|----------- **type** | string/compact IRI ([Multiple values allowed](#array)) | `TypeValidation`. -**validatesType** | string/compact IRI | Valid JSON-LD type for a badge component, such as `Assertion`, `extensions:ApplyLink`, or `https://w3id.org/openbadges/extensions#ApplyLink`. Compact forms preferred. +**validatesType** | string/compact IRI | JSON-LD type as it appears compacted into the Open Badges context. **validationSchema** | URL | Location of a hosted JSON-schema.
@@ -560,7 +561,7 @@ Validators that someday use the proposed FrameValidation method pass JSON-LD obj ## Endorsement ([example](./examples/index.html#Endorsement)) 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](https://w3c.github.io/vctf/) at the [W3C](https://www.w3.org/) and the theoretical backing developed by the 2014 Endorsement Working Group. See [Endorsement Framework Paper](https://docs.google.com/document/d/1VVf19d72KmGMh1ywrLe7HCKEOqGSI0WjvwfGN_8Q2M4/edit#heading=h.xyxfmzqz2vqb). +Endorsement leans on the Verifiable Claims work prototyped by members of the [Verifiable Claims Task Force](https://w3c.github.io/vctf/) at the [W3C](https://www.w3.org/) 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`. @@ -574,6 +575,8 @@ Property | Expected Type | Description/expected value **issuer** | @id: Profile | The profile of the Endorsement's issuer. **issuedOn** | [DateTime](#dateTime) | Timestamp of when the endorsement was published. **verification** | [VerificationObject](#VerificationObject) | Instructions for third parties to verify this assertion of endorsement. +revoked | Boolean | Defaults to `false` if `Endorsement` is not referenced from a [`revokedAssertions`](#revokedAssertions) list and may be omitted. See [RevocationList](#RevocationList). If `revoked` is true, only `revoked`, `issuer`, and `id` are required properties, and many issuers strip a hosted Assertion down to only those properties when revoked. +revocationReason | Text | Optional published reason for revocation, if revoked. @@ -596,6 +599,7 @@ Endorsements use the `claim` property to identify another entity by its `id` and "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", @@ -693,9 +697,9 @@ To mark a hosted assertion as revoked, respond with an HTTP Status of `410 Gone` 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](./examples/index.html#SignedBadge)) +### SignedBadge Verification ([example](./examples/index.html#SignedBadge)) -A signed badge may be published in the form of a [JSON Web Signature](http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html). If so, the JSON representation of the badge assertion should be used as the JWS payload. +A signed badge may be published in the form of a [JSON Web Signature](http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html). If so, the JSON representation of the badge assertion should be used as the JWS payload. A JWS has three components separated by dots (`.`): {% highlight html %} @@ -726,7 +730,7 @@ To mark a badge as revoked, add an entry to the resource pointed at by the Issue # History * [From 1.1 to 2.0](history/2.0.html) (includes 2.0 errata) - * [From 1.0 to 1.1](history/1.1.html) + * [From 1.0 to 1.1](history/1.1.html) * [From 0.5 to 1.0](https://github.com/mozilla/openbadges/wiki/Assertion-Specification-Changes) * [Early history of the specification](https://github.com/mozilla/openbadges-backpack/wiki/Assertions/_history) diff --git a/ob_v2p0/v2/context.json b/ob_v2p0/v2/context.json index 84c3f375..4fbe042a 100644 --- a/ob_v2p0/v2/context.json +++ b/ob_v2p0/v2/context.json @@ -54,7 +54,7 @@ "startsWith": { "@id": "http://purl.org/dqm-vocabulary/v1/dqm#startsWith" }, "tags": { "@id": "schema:keywords" }, "targetDescription": { "@id": "schema:targetDescription" }, - "targetFramework": { "@id": "schema:targetFramework" }, + "targetFramework": { "@id": "schema:educationalFramework" }, "targetName": { "@id": "schema:targetName" }, "targetUrl": { "@id": "schema:targetUrl" }, "telephone": { "@id": "schema:telephone" },