# Peer Claims with Open Badges and Verifiable Credentials.
by Nate Otto, Kim Hamilton Duffy, and Kerri Lemoie

Contributors:
* Serge Ravet

Licensed CC-BY. The authors of this document commit to sign and abide by the W3C Community Group IPR Policy to facilitate this work being used in the web standards process.

## Abstract
Peer Claims, or Peer Endorsements, are a type of Open Badges Assertion with an emphasis on light reusable credential descriptions to be awarded by many different issuers. We will describe this notion of peer claims using capabilities defined in the [Open Badges are Verifiable Claims paper](TODO: link) for Rebooting Web of Trust 6. This paper will inform the development of proofs of concept for peer claims use cases. We will then analyze the new capabilities and required updates relative to Open Badges software in the roles of Issuer, Host/Backpack, Displayer and Validator.

## Table of Contents
> [TOC]

## Introduction
Peer Claims are what members of a community use to recognize one another. Assertions of these claims are Open Badges Assertions of a particular BadgeClass made by one or more entities who are peers of one another. A peer claims ecosystem may be bootstrapped by a privileged BadgeClass creator, in which the creator establishes the capability for peers to award Assertions. However, the peer claims ecosystem is not governed by centralized authorities.

In a companion paper, [Open Badges are Verifiable Claims](https://bit.ly/openbadges-rwot6), developed for the [Rebooting Web of Trust workshop in Spring 2018](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/), examples were presented showing Open Badges Assertions delivered using the [Verifiable Credentials Data Model](https://w3c.github.io/vc-data-model/). This paper extends that work to illustrate a method of making lightweight claims for peers to recognize one another.

## Use Cases
### Publish BadgeClass available with universal Award capability
**As an Issuer, I would like to grant a capability to anybody to Award an instance of a BadgeClass I publish.** As part of a competency recognition program in their institution, the issuer would like to publish a 21st Century Skills framework with associated BadgeClasses that may be awarded by anybody in recognition of a peer claim.

### Publish an Assertion of a open-award BadgeClass as a peer endorsement of another entity.
Students will be able to award each other Endorsements that assert competence in one of the elements of the institution's framework with a little narrative about the award. These Endorsements will be Verifiable Claims asserting other students hold the institution-defined BadgeClasses with narratives describing what they had done to demonstrate the competency. Their proofs should invoke the capability granted by an issuer.

### Grant a capability to anyone who holds a particular BadgeClass award
**As an Issuer, I would like to allow anybody who holds the BadgeClass to award it to anybody else.** I can grant a capability to anyone, but attenuated to only those who hold a valid Assertion of the BadgeClass to be awarded. (This works to identify any BadgeClass as the prerequisite, not just the specific one to be awarded.)

### Multiple peers publish an Assertion of a minimal ad-hoc BadgeClass that can be related by other properties than a resolvable ID
Issuers and consumers/inspectors/verifiers of badge Assertions may wish to use concepts from BadgeClass without need for all the properties. For instance, the above competency framework use cases could be recast to use a BadgeClass made up of only an alignment:

{
  "claim": {
      "id": "did:example:bob",
      "obi:holds": {
          "alignment": {"targetUrl": "https://example.com/competencies/teamwork"}
      }
  }
  // ...
}

Relaxing requirement list on BadgeClass, including removing `image`, `criteria`, and `issuer` makes it possible to publish and consume very targeted claims. However, there is some power in consistent implementation of the BadgeClass model, so "fully defined" implementations of BadgeClass, which may still be referenced by resolvable ID in Assertions, still have a strong purpose in the ecosystem.

### Publish an assertion for a credential defined in the Credential Engine Registry
The [Credential Engine Registry (CER)](http://credreg.net/) is a database with open APIs that stores and shares metadata about credentials, credentialing organizations, quality assurance organizations, and competency frameworks. The Credential Transparency Description Language (CTDL) describes each credential and associated entities. Organizations publishing to the CER are human-verified prior to publishing credential data.

Each credential stored in the CER contains a unique resource link which returns a JSON payload of the credential's properties as [required or reccomended](http://credreg.net/registry/policy) by the CTDL. By referencing this resource link in an assertion the metadata for this credential is accessible as part of the verifiable credential. An example of a resource:

{
	"@id": "https://credentialengineregistry.org/resources/ce-c4ccf4c4-76d5-4a6e-9ca0-2cd7a8937ee6",
	"@type": "ceterms:DigitalBadge",
	"@context": "http://credreg.net/ctdl/schema/context/json",
	"ceterms:ctid": "ce-c4ccf4c4-76d5-4a6e-9ca0-2cd7a8937ee6",
	"ceterms:name": "Medical Assistant Patient Interviewing/Intake",
	"ceterms:keyword": ["Medical Assistant", "Patient Intake", "Patient Medical History"],
	"ceterms:ownedBy": [{
		"@id": "https://credentialengineregistry.org/resources/ce-67C45100-B6D7-413D-9924-F0D5ADB825F1"
	}],
	"ceterms:subject": [{
		"@type": "ceterms:CredentialAlignmentObject",
		"ceterms:targetNodeName": "Medical Assistant"
	}, {
		"@type": "ceterms:CredentialAlignmentObject",
		"ceterms:targetNodeName": "Patient Intake"
	}],
	"ceterms:isPartOf": [{
		"@id": "https://credentialengineregistry.org/resources/ce-4fa8dc4b-ef12-4a44-be7c-7397f8ef0421"
	}],
	"ceterms:offeredBy": [{
		"@id": "https://credentialengineregistry.org/resources/ce-67C45100-B6D7-413D-9924-F0D5ADB825F1"
	}],
	"ceterms:revokedBy": [{
		"@id": "https://credentialengineregistry.org/resources/ce-67C45100-B6D7-413D-9924-F0D5ADB825F1"
	}],
	"ceterms:inLanguage": ["English"],
	"ceterms:availableAt": [{
		"@type": "ceterms:Place",
		"ceterms:name": "Madison",
		"ceterms:latitude": 43.12171550000001,
		"ceterms:longitude": -89.3285843,
		"ceterms:postalCode": "53704",
		"ceterms:addressRegion": "WI",
		"ceterms:streetAddress": "1701 Wright St.",
		"ceterms:addressCountry": "United States",
		"ceterms:addressLocality": "Madison"
	}],
	"ceterms:description": "CAAHEP accreditation requires 100% of all medical assistant graduates to pass 100% of all competencies.  In addition to passing 100% of all competencies, to earn this badge a student performed a mock rooming exercise at an exceptional level.  Additionally the student successfully completed the psychomotor, affective, and cognitive domain assessments at a 93% or above.",
	"ceterms:dateEffective": "2016-09-01",
	"ceterms:occupationType": [{
		"@type": "ceterms:CredentialAlignmentObject",
		"ceterms:framework": "https://www.bls.gov/soc/",
		"ceterms:codedNotation": "31-9092.00",
		"ceterms:frameworkName": "Standard Occupational Classification",
		"ceterms:targetNodeName": "Medical Assistants",
		"ceterms:targetNodeDescription": "Perform administrative and certain clinical duties under the direction of a physician. Administrative duties may include scheduling appointments, maintaining medical records, billing, and coding information for insurance purposes. Clinical duties may include taking and recording vital signs and medical histories, preparing patients for examination, drawing blood, and administering medications as directed by physician."
	}],
	"ceterms:subjectWebpage": "https://www.youracclaim.com/org/madison-college-school-of-health-education/badge/medical-assistant-patient-interviewing-intake",
	"ceterms:copyrightHolder": [{
		"@id": "https://credentialengineregistry.org/resources/ce-67C45100-B6D7-413D-9924-F0D5ADB825F1"
	}],
	"ceterms:audienceLevelType": [{
		"@type": "ceterms:CredentialAlignmentObject",
		"ceterms:targetNode": "audLevel:AssociatesDegreeLevel",
		"ceterms:frameworkName": "AudienceLevel",
		"ceterms:targetNodeName": "Associates Degree Level"
	}],
	"ceterms:availableOnlineAt": ["https://madisoncollege.edu/program/medical-assistant"],
	"ceterms:estimatedDuration": [{
		"@type": "ceterms:DurationProfile",
		"ceterms:description": "This credential can be earned within one course within the Medical Assistant program.",
		"ceterms:maximumDuration": "P3M",
		"ceterms:minimumDuration": "P1M"
	}],
	"ceterms:availabilityListing": ["https://madisoncollege.edu/program/medical-assistant"],
	"ceterms:credentialStatusType": {
		"@type": "ceterms:CredentialAlignmentObject",
		"ceterms:targetNode": "credentialStat:Active",
		"ceterms:frameworkName": "CredentialStatus",
		"ceterms:targetNodeName": "Active"
	}
}

It is required that each credential contains at least an [`ceterms:ownedBy`](http://credreg.net/ctdl/terms#ownedBy) or [`ceterms:offeredBy`](http://credreg.net/ctdl/terms/offeredBy) property. A credential may contain multiples of each property. When the resource is linked to from an assertion,`ceterms:ownedBy` or `ceterms:offeredBy` data may be the verified issuer(s) of a credential. While it can't be assumed that `ceterms:ownedBy` is the "creator" of the credential. It is arguable that the organization(s) referenced in the `ceterms:ownedBy` property is the arbitrator of which organization(s) are referenced in the `ceterms:offeredBy` property.

At this stage of CER, organizations are the main providers of the credentials. However, the CER has made accomodations for individuals to be providers as well.

### Supporting Kirkpatrick Level 3 evaluation
The Kirkpatrick model of learning/training evaluation comprises four levels:
* __Level 1: Reaction__ — The degree to which participants find the training favorable, engaging and/or relevant to their jobs (usually referred to as the "smile sheet")

* __Level 2: Learning__ — The degree to which participants acquire the intended knowledge, skills, attitude, confidence and commitment

* __Level 3: Behavior__ — The degree to which participants apply what they learned during training when they are back on the job

* __Level 4: Results__ — The degree to which the training has an impact on the organisation's results, e.g. turnover

To support the transfer to the workplace of what participants have learned during a training intervention the suggestion is to have a verifiable claim with an embedded signature workflow:

1. __The learner__: before going to training signs the badge. The signature of the badge is like _signing a learning contract_;
2. __The trainer__: once the training intervention is over and the trainer is satisfied that the learner is competent, the trainer signs the badge;
3. __The line manager__: once back to work, and when the line manager is satisfied that the learner/worker has transfered the learning into the workplace, the line manager signs the badge.

This means that the VC is like a small automaton with 3 different states and the transition from one state to the next is triggered by the signature of one of the parties. This is a very specific use case linked to training, though the roles may be generalized to apply to a broader range as well. The role of the trainer here may be filled by any assessor, including any peer expert. The states are:

1. ready to learn — _I want to learn_
2. ready to apply — _I want to apply my learning_
3. competent — _I want my competencies to be recognised_

This simple workflow could be augmented by adding the signature of the HR department, or that of an awarding body, etc. The great advantage of this way of working is that it is the way we do when we use a simple sheet of paper signed by the different parties. Moreover, there is a whole literature on "learning contracts" that reports their benefits on learners' engagement.

This supposes a number of features that do not (yet) exist currently with Open Badges:

* The learner can get the badge at the start of the learning journey, not just at the end;
* The badge is only "valid" once the line manager has signed it;
* The state of the badge should be reflected in its picture.

The solution using current badge systems would be to implement the workflow within badge issuing platforms, with 3 different assertions, ther first one being used as evidence of the next one. The idea with VC would be to embed the rules within the claim so it is independent from any kind of platform, but the simple ability of the parties to _sign_ the claim in the right order.

When the badge is issued it contains a condition relative the three parties engaged into the workflow. The condition could be:
* The IDs of the parties allowed to sign the badge; or
* A condition related to the IDs of the parties allowed to sign, like `ID_Trainer owns credential "XWZ"`

It also contains a rule for the signature order, so that if the line manager signs before the trainer, the badge is declared invalid (and the reputation of the line manager decreases!). We could also add a time condition, something like `ID_LineManager signature time > ID_Trainer signature time`. It would be the task of the verification to check that the badge is well formed according to the rules.

The verification process could also be the process that replaces the image in which the claim is embedded as the worlflow progresses. Which means that the verification process should then sign the badge, so one would be able to _verify the verifier_.

### Recommending someone for a credential
This is based on a real use case from the Université de Normandie. Students have the ability to recommend other students for a particular badge. They don't issue it, just make a recommendation that is later validated by a jury. The value of a recommendation is that it can be performed by someone who is not an expert in the domain, it is less _engaging_ than the issuing of a badge and it involves the community of peers in the recommendation process. It can be read as a _pre-endorsement_ of a particular credential or badge instance.

In the life cycle of a credential, _recommendations_ and _endorsements_ are at the two ends: _recommendations_ are an invitation to issue a credential while _endorsements_ is a confirmation of the merit of the credential's holder.

While an _endorsement_ makes reference to two entities (the _endorser_ and a BadgeClass, an assertion, or anything bearing an identifier) a _recommendation_ makes reference to 3 entities: the _recommender_, the BadgeClass (with the issuer ID) and the recipient.

The difference between a _recommendation_ and a regular _credential_ is who is at the origin of the recognition cycle.

### Skill Assessment & Recognition (*bilan de compétences*)
Marie wants to have her competencies in [permaculture](https://en.wikipedia.org/wiki/Permaculture) recognised. For that, after checking that it does not already exist, she creates a "permaculture professional" badge and signs it. She then collects evidence of her work into a portfolio and uses the link to the "permaculture portfolio" as evidence of her skills. In parallel she collects testimonies, testimonials and endorsements of her skills (people add their signatures to the badge created by Marie or to the evidence collected in the portfolio).

As Marie is in contact with other people involved in permaculture, she invites them to claim their own permaculture badges — "permaculture trainer," "permaculture supplies provider," "permaculture journalist," etc. To address the diversity of permaculture badges, she decides to create an overarching permaculture badge "permaculture community member" that everyone can claim—to be issued, the badge needs to be reviewed by 5 people who already have that badge.

As the community of practice grows, the leaders of the community ask for their badges to be endorsed (recognised) by the ministry of agriculture, the ministry of labour and ministry of education.

The products of the permaculture have their own badges eliciting their provenance and the value chain between producers, distributors and consumers.

#### Key elements in the use case
A badge is representative of a community and therefore it can be used to make a community visible (not just a skill). It is the community that gives credibility to the badge and then is in a position to ask for a formal recognition by public authorities. Global recognition starts with *hyperlocal* recognition.

It is therefore critical to associate badges with social/community spaces where badges are produced and consumed. "Permaculture Badges" are not just useful to elicit skills (the initial intention of Marie) but also as an attribute attached to the product/service produced by such skills. The *permaculture badge ecosystem* as an echo of the extended *permaculture ecosystem*.

## Questions/Considerations
- How will open badges validator correlate issuer property to `ceterms:ownedBy` and `ceterms:offeredBy`. Reference: [CER Organization property](http://credreg.net/registry/policy#mindata_organization) CER resources may contain multiple values for these properties (confirm) whereas an open badge conatins a single issuer property.
- If a CER property is in an assertion as well as an issuer property, is a BadgeClass necessary?
- Can the BadgeClass be optional?
- If the BadgeClass is optional and the CER resource is not an Open Badge but another type of credential, is the verifiable credential still an Open Badge?

## Scenarios (assuming Issuer property is in the assertion, not in the badge class and that the assertion links to a CER resource)
- CER resource is [`ceterms:OpenBadge`](http://credreg.net/ctdl/terms#OpenBadge); CER resource contains a single `ceterms:ownedBy` but not `ceterms:offeredBy`; Issuer property correlates with `ceterms:ownedBy`. BadgeClass is not present in the assertion.
- CER resource is [`ceterms:OpenBadge`](http://credreg.net/ctdl/terms#OpenBadge); CER resource contains a single `ceterms:ownedBy` as well as a single `ceterms:offeredBy`; Issuer property correlates with `ceterms:offeredBy`. BadgeClass is not present in the assertion.
- CER resource is [`ceterms:OpenBadge`](http://credreg.net/ctdl/terms#OpenBadge); CER resource contains multiple `ceterms:ownedBy` as well as a single `ceterms:offeredBy`; Issuer property does not correlates with `ceterms:ownedBy` or `ceterms:offeredBy`. BadgeClass is not present in the assertion.
- CER resource is [`ceterms:Certification`](http://credreg.net/ctdl/terms#Certification); CER resource contains a single `ceterms:ownedBy` but not `ceterms:offeredBy`; Issuer property correlates with `ceterms:ownedBy`. BadgeClass is not present in the assertion.
- CER resource is [`ceterms:Certification`](http://credreg.net/ctdl/terms#Certification); CER resource contains a single `ceterms:ownedBy` but not `ceterms:offeredBy`; Issuer property correlates with `ceterms:ownedBy`. BadgeClass is present in the assertion.
- CER resource is [`ceterms:OpenBadge`] (http://credreg.net/ctdl/terms#OpenBadge); CER resource contains a single `ceterms:ownedBy` but not `ceterms:offeredBy`; Issuer property correlates with `ceterms:ownedBy`. BadgeClass is present in the assertion but the badge class description does not match the CER resource `ceterms:description`](http://credreg.net/ctdl/terms#description ). Note that description is a required property for both badge class and CER.

## Examples

### A BadgeClass with universal award capability grant
The BadgeClass may include a capability grant

{
    "@context": ["https://w3id.org/credentials/v2", "https://w3id.org/openbadges/v2", "https://example.org/ocap/v1"],
    "id": "https://example.com/freebadges/teamwork",
    "issuer": "did:example:program_organizer",
    "name": "Teamwork Badge",
    "description": "A badge awarded by the Example Institution community to recognize great teamwork.",
    "criteria": {"narrative": "Perform random acts of teaming."},
    "alignment": {
        "targetUrl": "https://example.com/competencies/teamwork",
        "targetName": "Teamwork"
    },
    "image": "data:image/png;base64,..."
    "ocap:grantCapabilitySuite": {
        "id": "urn:uuid:167fd864-9fa5-4669-828a-1f4964eeb207",
        "type": "Capability",
        "invocationTarget": ["https://example.com/freebadges/1", "https://examp.e.com/freebadges/2"],
        "invoker": "*",
        "action": "obiActions:Award",
        "proof": {
            "type": "RsaSignature2016",
            "created": "2018-01-08T16:02:20Z",
            "creator": "did:example:program_organizer#keys-1",
            "signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="
        }
    },
    "proof": {
         "type": "RsaSignature2016",
            "created": "2018-01-08T16:02:20Z",
            "creator": "did:example:program_organizer#keys-1",
            "signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="
    }
}

### A Peer Claim invoking universal award capability
A student could sign a very lightweight piece of data in order to make a lightweight claim about a peer. In this claim, they would invoke the capability granted by the issuer of the BadgeClass.

{
	"@context": ["https://w3id.org/credentials/v2", "https://w3id.org/ocap/v1", "https://w3id.org/openbadges/v2"],
	"id": "urn:uuid:01f0bb90-86ee-4469-9655-7ca6f4d591af",
	"type": ["Credential"],
	"issuer": "did:example:alice",
	"issued": "2018-02-28T14:58:57.461422+00:00",
	"claim": [{
		"@context": "https://w3id.org/openbadges/v2",
		"id": "did:example:bob",
		"badge": "https://example.com/freebadges/teamwork"
	}],
	"obi:evidence": {
		"narrative": "Bob was very helpful today when I was reticulating the splines."
	},
	"proof": {
		"type": "sec:RsaSignature2018",
		"created": "2018-03-07T22:26:57Z",
		"creator": "did:example:alice#keys-1",
		"proofPurpose": "invokeCapability",
        "action": "obiActions:Award",
		"capability": {
			"id": "urn:uuid:167fd864-9fa5-4669-828a-1f4964eeb207",
			"type": "Capability",
			"invocationTarget": ["https://example.com/freebadges/1", "https://examp.e.com/freebadges/2"],
			"invoker": "*",
			"action": "obiActions:Award",
			"proof": {
				"type": "RsaSignature2016",
				"created": "2018-01-08T16:02:20Z",
				"creator": "did:example:program_organizer#keys-1",
				"signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="
			}
		},
		"sec:jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..GMPdCXn-qQcZHPoO6qHn6hBiysMNaZ7nSBx_e27LuDxJvRsCLbR1n7LGG7i8NVW1SVMwRjs8aJ3H2XXFphCZF_dGaueTsaehTzLQgh9n5imPgrQFsAKsRAKTJ_zpVL8JpsbPcrXbb-fkAcD52oDuYJg1uVr3MOhe4BzibDUKaFg5-cXZ-Gs8KcXrh_Ddqtd8CWw0zS3fRvI3SKbO6op6hNB1Jha4mfAn49Q0BRiSuCxbyPNy5MtX7FGoimvLhsluM7UAtPWHBi6iW8Nh57fk4uS5ZywHJSYS9-HPcvbDUGPHPHOnwq4qq7xc47yXveMmyo2VX4YSYe3LM-_9w1TnGc"
	}
}

Alternately, if the granting capability were available the URI http://www.issuer.org/167fd864-9fa5-4669-828a-1f4964eeb207, the invocation could be expressed as linked data as follows:

{
	"@context": ["https://w3id.org/credentials/v2", "https://w3id.org/ocap/v1", "https://w3id.org/openbadges/v2"],
	"id": "urn:uuid:01f0bb90-86ee-4469-9655-7ca6f4d591af",
	"type": ["Credential"],
	"issuer": "did:example:alice",
	"issued": "2018-02-28T14:58:57.461422+00:00",
	"claim": [{
		"@context": "https://w3id.org/openbadges/v2",
		"id": "did:example:bob",
		"badge": "https://example.com/freebadges/teamwork"
	}],
	"obi:evidence": {
		"narrative": "Bob was very helpful today when I was reticulating the splines."
	},
	"proof": {
		"type": "sec:RsaSignature2018",
		"created": "2018-03-07T22:26:57Z",
		"creator": "did:example:alice#keys-1",
		"proofPurpose": "invokeCapability",
        "action": "obiActions:Award",
		"capability": "http://www.issuer.org/167fd864-9fa5-4669-828a-1f4964eeb207",
		"sec:jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..GMPdCXn-qQcZHPoO6qHn6hBiysMNaZ7nSBx_e27LuDxJvRsCLbR1n7LGG7i8NVW1SVMwRjs8aJ3H2XXFphCZF_dGaueTsaehTzLQgh9n5imPgrQFsAKsRAKTJ_zpVL8JpsbPcrXbb-fkAcD52oDuYJg1uVr3MOhe4BzibDUKaFg5-cXZ-Gs8KcXrh_Ddqtd8CWw0zS3fRvI3SKbO6op6hNB1Jha4mfAn49Q0BRiSuCxbyPNy5MtX7FGoimvLhsluM7UAtPWHBi6iW8Nh57fk4uS5ZywHJSYS9-HPcvbDUGPHPHOnwq4qq7xc47yXveMmyo2VX4YSYe3LM-_9w1TnGc"
	}
}

In this example, three entities are identified just by a resolvable ID.
* The first `did:example:alice` resolves to the issuer's DID Document, which contains the signing key used in the proof.
* The second `did:example:bob` resolves to the recipient's DID Document, which can be correlated with other claims issued and received by the entity who is the recipient of this award.
* The third `https://example.com/freebadges/teamwork` resolves to a BadgeClass published by another creator.

The BadgeClass or its issuer Profile DID Document would contain a capability grant using [Linked Data Capabilities](https://w3c-ccg.github.io/ld-ocap/) to grant to anyone (or anyone who holds a particular BadgeClass, for instance) the capability to award these peer assertions.

### Example of a BadgeClass that may be awarded by anyone who holds it ("viral")

A BadgeClass might contain a capability grant like the example above, but attenuated with a caveat that the invoker of the capability must hold a certain BadgeClass.

{
	"@context": ["https://w3id.org/ocap/v1", "https://w3id.org/openbadges/v2"],
	"id": "urn:uuid:167fd864-9fa5-4669-828a-1f4964eeb207",
	"type": "Capability",
	"invocationTarget": "https://example.com/freebadges/1",
	"invoker": "*",
	"action": "obiActions:Award",
	"caveat": {
		"obi:holds": {
			"id": "https://example.com/freebadges/teamwork"
		}
	},
	"proof": {
		"type": "RsaSignature2016",
		"created": "2018-01-08T16:02:20Z",
		"creator": "did:example:program_organizer#keys-1",
		"signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="
	}
}

This could be invoked by presenting evidence verifiable by an inspector to match the caveat in the Capability:

{
	"@context": ["https://w3id.org/ocap/v1", "https://w3id.org/openbadges/v2"],
	"claim": {
		"...": "..."
	},
	"proof": {
		"type": "sec:RsaSignature2018",
		"created": "2018-03-07T22:26:57Z",
		"creator": "did:example:alice#keys-1",
		"proofPurpose": "invokeCapability",
		"action": "obiActions:Award",
		"evidence": {
			"type": "Assertion",
			"id": "https://example.com/assertions/alices-teamwork-badge",
			"badge": "https://example.com/freebadges/teamwork"
		},
		"capability": {
			"id": "urn:uuid:167fd864-9fa5-4669-828a-1f4964eeb207",
			"type": "Capability",
			"invocationTarget": ["https://example.com/freebadges/1", "https://examp.e.com/freebadges/2"],
			"invoker": "*",
			"action": "obiActions:Award",
			"proof": {
				"type": "RsaSignature2016",
				"created": "2018-01-08T16:02:20Z",
				"creator": "did:example:program_organizer#keys-1",
				"signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="
			}
		},
		"sec:jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..GMPdCXn-qQcZHPoO6qHn6hBiysMNaZ7nSBx_e27LuDxJvRsCLbR1n7LGG7i8NVW1SVMwRjs8aJ3H2XXFphCZF_dGaueTsaehTzLQgh9n5imPgrQFsAKsRAKTJ_zpVL8JpsbPcrXbb-fkAcD52oDuYJg1uVr3MOhe4BzibDUKaFg5-cXZ-Gs8KcXrh_Ddqtd8CWw0zS3fRvI3SKbO6op6hNB1Jha4mfAn49Q0BRiSuCxbyPNy5MtX7FGoimvLhsluM7UAtPWHBi6iW8Nh57fk4uS5ZywHJSYS9-HPcvbDUGPHPHOnwq4qq7xc47yXveMmyo2VX4YSYe3LM-_9w1TnGc"
	}
}

Alternately, if the granting capability were available the URI http://www.issuer.org/167fd864-9fa5-4669-828a-1f4964eeb207, the invocation could be expressed as linked data as follows:

{
	"@context": ["https://w3id.org/ocap/v1", "https://w3id.org/openbadges/v2"],
	"claim": {
		"...": "..."
	},
	"proof": {
		"type": "sec:RsaSignature2018",
		"created": "2018-03-07T22:26:57Z",
		"creator": "did:example:alice#keys-1",
		"proofPurpose": "invokeCapability",
		"action": "obiActions:Award",
		"evidence": {
			"type": "Assertion",
			"id": "https://example.com/assertions/alices-teamwork-badge",
			"badge": "https://example.com/freebadges/teamwork"
		},
		"capability": "http://www.issuer.org/167fd864-9fa5-4669-828a-1f4964eeb207",
		"sec:jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..GMPdCXn-qQcZHPoO6qHn6hBiysMNaZ7nSBx_e27LuDxJvRsCLbR1n7LGG7i8NVW1SVMwRjs8aJ3H2XXFphCZF_dGaueTsaehTzLQgh9n5imPgrQFsAKsRAKTJ_zpVL8JpsbPcrXbb-fkAcD52oDuYJg1uVr3MOhe4BzibDUKaFg5-cXZ-Gs8KcXrh_Ddqtd8CWw0zS3fRvI3SKbO6op6hNB1Jha4mfAn49Q0BRiSuCxbyPNy5MtX7FGoimvLhsluM7UAtPWHBi6iW8Nh57fk4uS5ZywHJSYS9-HPcvbDUGPHPHOnwq4qq7xc47yXveMmyo2VX4YSYe3LM-_9w1TnGc"
	}
}

## TODO: Implementation User Stories for Open Badges software
### Issuer
TODO: anything else required for issuers?

To support peer claims, the Issuer would define and host specifications for:
- BadgeClasses with universal award capability grant
- BadgeClasses with attenuated capabilities

In the latter case, our example restricted that capability invocations must hold a claim with id "https://example.com/freebadges/teamwork". To do this, the issuer must ensure issued claims match the id in the hosted attenuated BadgeClass.

### Host/Backpack
TODO: not sure

### Displayer
TODO: not sure

### Verifier
The Verifier ensures the capability is valid by following the steps defined in [LD Capabilities Invocation](https://w3c-ccg.github.io/ld-ocap/#invocation).

To summarize that process, the Verifier ensures the claim contains a `proof` property where:
- `proofPurpose` equals `invokeCapability`
- `capability` property links to the capability document or describes the capability inline
- TODO: since we are not using `invoker`, the child claim doesn't need to be signed with a parent's invoker field, so it only needs to be signed with a child key

The Verifier must also ensure:
- the `capability` document grants authority to invoke this capability
- the top-level capability document is signed by one of the `invocationTarget`'s keys
- the restrictions of all caveats are fulfilled. In the attenuated example presented here, the verifier must ensure the child claim holds an instance of a BadgeClass with id "https://example.com/freebadges/teamwork".

At this point, the invocation is considered valid and any relevant action may be performed.

Notes:
- The examples presented in this paper do not use the `invoker` field; if so, additional steps apply, as described in [LD Capabilities Invocation](https://w3c-ccg.github.io/ld-ocap/#invocation).
- Should we provide details about any other kinds of caveats?

## Next Steps
Contributors to this paper and their outside collaborators intend to build several prototypes that demonstrate proofs of the concepts discussed.

### Peer Recognition Network Proof of Concept
Particularly, one system we are sketching out for development involves:

* Learners registering a DID and signing up for a community
* Automatically awarded membership badge upon join, awarded to their DID from the community maintainer DID.
* A set of free-to-award BadgeClasses with universal Award capability grants.
* An interface for community members to see one another's DIDs (and probably their nicknames for these DIDs) with ability to award peer claims to one another and sign them with their own keys.

# Parking Lot (meta notes for editors)
* Serge, can we rename to "A Bit of Trust: Peer Claims with Open Badges and Verifiable Credentials"?

## TODOs
* [x] An example of a peer attestation ("endorsement") from a DID-identified issuer to a DID-identified recipient.
* [x] Create JSON-LD Verifiable Credential samples of peer claims: "I read through Kim's code and know she writes good clear comments." - these samples should make sense to the Open Badges community.
* [ ] Implementation user stories