A verifiable claim is a qualification, achievement, quality, or piece of information about an entity's background such as a name, government ID, payment provider, home address, or university degree. Such a claim describes a quality or qualities, property or properties of an entity which establish its existence and uniqueness. The use cases outlined here are provided in order to make progress toward possible future standardization and interoperability of both low- and high-stakes claims with the goals of storing, transmitting, and receiving digitally verifiable proof of attributes such as qualifications and achievements. The use cases in this document focus on concrete scenarios that the technology defined by the group should address.
This document represents a concise but limited collection of use cases readers should review alongside the Verifiable Credentials Data Model.
The work on this document was carried out under tight time constraints due to limitations of the W3C process and publishing deadlines. Under such conditions, errors are unavoidable and some of the ideas presented here are incomplete. The Working Group hopes that in the future, W3C process can be revised to better support the dynamic nature of standards work in a more consistent way across different groups.
Comments regarding this document are welcome. Please file directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).
The Verifiable Claims Working Group at the W3C is developing standards for expressing and exchanging "claims" that have been verified by a third party and to make them easier and more secure on the Web.
Entities (people, organizations, devices) need to make many kinds of claims as part of their everyday activities. As more and more of these important activities move to the Internet, entities need to be able to transmit instantly verifiable claims (e.g., about their location, accomplishments, value, what-have-you). From educational records to payment account access, the next generation of web applications will authorize entities to perform actions based on rich sets of credentials issued by trusted parties. Human- and machine-mediated decisions about job applications, account access, collaboration, and professional development will depend on filtering and analyzing growing amounts of data. It is essential that data be verifiable.
Standardization of digital claim technologies makes it possible for many stakeholders to issue, earn, and trust these essential records about their counterparties, without being locked into proprietary platforms.
This document presents an aggregate use case model, comprised of Needs, Roles, Tasks, and Sequences. Taken together, these models define the use cases that the Verifiable Claims Working Group has addressed.
User needs define the problem space addressed by verifiable credentials. User Roles specify the roles different entities play when interacting with verifiable credentials. Tasks define the functions users can accomplish, and sequences demonstrate how tasks might be realized, by interactions between entities over time.
As with all models, this use case model is neither exhaustive nor complete. The listed uses cannot capture all possible use cases. Similarly, the models do not completely characterize the use cases represented. However, the combined model is intended to provide specific, coherent guidance for the work ahead.
There are four roles supported by verifiable credentials: Issuer, Verifier, Subject, and Holder.
Verifiable credentials address user needs in a number of key domains:
The education domain includes all levels of the educational experience; from primary through professional continuing education.
The retail domain encompasses all things where there is an exchange of value on an individual level. This includes brick-and-mortar store fronts, web-only venues, and even person-to-person sales.
The Finance domain includes banking, brokerage, insurance, and other industries where there is a high value placed on knowing exactly with whom you are dealing.
Privacy is critically important in the healthcare industry. This domain looks at everything from physical interaction to connecting patients and providers with service organizations.
In many aspects of life it is important to know that entities are who they say they are, and that they can do what they say. Professional accreditation is one way of learning about the abilities of an entity. Being able to verify these credentials is essential to their value.
For many transactions, an entity must be able to prove some aspect of their identity in a way that can be quickly verified. Governments and other widely recognized entities are well positioned to provide such identification in a verifiable digital form.
Intelligence devices are created and deployed so that they can interact with other entities (people, organizations, devices). Establishing trust and maintaining secure relationships with these devices is especially critical.
Use cases are often used as a driver for requirements. While the users of verifiable credentials have needs across many domains, the tasks associated with those needs span the domains. This section summarizes those tasks, as well as requirements related to the tasks, and maps the tasks and requirements back to the associated needs.
It is worth noting that the subject may or may not be the same entity as the holder. There are no tasks in these examples that require participation of the subject.
Focal Use Cases are meant to provide examples where a blend of features from verifiable credentials standard may be used together to solve complex or challenging marketplace needs.
Sam wants to claim US citizenship because his mother is American. Sam has a digital birth certificate from Kenya, where he was born while his Mother was in the Peace corps. He also has a digital version of his mother's US passport. Because his mother’s name changed between his birth and the issuance of the passport, Sam also has a marriage license with her maiden and married names. Sam is applying for a new passport from the US Secretary of State.
This use case is challenging because the mother’s name changed, by marriage, between the issuance of the birth certificate and passport.
Sam’s mother emailed him the certificate, license, and passport as independent Verifiable Credentials. He then creates a verifiable presentation which includes those credentials, a statement of their relationship to each other and his relationship to his mother. He then visits the US Secretary of State website, creates an account, starts the application for a passport, and uploads his new verifiable presentation as supporting evidence. After processing the application, Sam is issued both a traditional passport and a new digital passport.
A verifiable presentation which includes those three credentials, adds his name, photo, and demographic data along with the assertions that —
Sam is legally liable for his claim to the rights of citizenship. The state department is on the hook for verifying the underlying credentials and Sam’s claims, including correlating against any additional data they might already have.
Pat earned multiple diving credentials while living and working in Fiji and Australia. Later, Pat is hired by NOAA as a Dive Instructor, which requires that they maintain certification as an instructor with additional specialist diver certifications in dry suit, night diving, and search and recovery. The dive instructor certification is public record, but the additional specialist certifications are private because they are for personal diving, not acting as an instructor.
Part of Pat's job is logging the certifications of fellow divers during NOAA sanctioned dives.
This use case is difficult because:
When Pat applied for his job at NOAA, he provided verifiable credentials issued by different dive schools licensed by PADI to do so. NOAA verifies cryptographically that the certifications were issued by PADI-approved dive schools and that the credentials were still in good standing by checking both the certifications' *and* the dive schools' revocation services.
Upon accepting the job, Pat issues NOAA a revocable token that allows NOAA to check the current status of all of his certifications — not just the status of a single verifiable credential. After any specific certification expires — and Pat renews it — NOAA's next check of Pat's certifications returns the status of the renewed certification, not just the status of the (now expired) verifiable credential.
When Pat takes a group of divers on NOAA sanctioned dives, he records the verifiable credentials for each diver (which demonstrate their diving certifications), creates a verifiable credential including those credentials; he signs and archives it on his laptop.
When Pat retires from NOAA, he revokes that token and NOAA staff is no longer able to monitor his non-public certification status.
Malathi is traveling internationally with her 8-month-old son, Anand. His father, Rajesh, is staying home. Malathi has enough frequent flyer miles to upgrade the ticket to first class.
This use case is difficult because:
Malathi obtains permission from Rajesh stating she is allowed to take the baby out of the country.
Prior to booking the trips, Malathi visits HappyAir.com to request an upgrade to first class. HappyAir issues a verifiable credential redeemable for a first class upgrade on an international flight.
She books the plane tickets through her travel agent who adds the lap child to the ticket.
HappyAir verifies that Malathi has a signed statement from Anand’s other parent stating that she may exit the country with him.
For details, refer to Example Verifiable Credentials in Appendix
Submitted to HappyAir, includes Malathi and Anand's passport, assertion of permission, birth certificate and Frequent Flyer coupon.
The transaction examples in this section show basic ways in which verifiable credentials might be used. They are not meant to be architecturally constraining. Instead, they are meant to help illustrate the basic way it could be done in a typical commerce situation. Again — please remember that it is just an example, and should not be thought of as the canonical way such a claims environment must be implemented.
In this first example, a user will request a verifiable credential—a confirmation of their identity. Consider this illustration:
Expanding on these steps:
In this example, a holder of a claim needs to use that claim in a typical commerce situation:
{ "@context": [ "https://w3id.org/credentials/v1", "https://example.com/travel-vocab/v1" ], "id": "urn:uuid:9f6878c8-73c7-11e8-ab37-23a1a3504fd0", "type": ["VerifiableCredential", "PassportCredential"], /* gov't DID */ "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV", "expires": "2028-01-01T00:00:00Z", "claim": { "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4", "givenName": "Malathi", "familyName": "Hamal", "citizenship": "US", /* any other claims made by gov't */ }, "proof": {/* signature by gov't */} }
{ "@context": [ "https://w3id.org/credentials/v1", "https://example.com/travel-vocab/v1" ], "id": "urn:uuid:9f6878c8-73c7-11e8-ab37-23a1a3504fd0", "type": ["VerifiableCredential", "PassportCredential"], /* gov't DID */ "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV", "expires": "2028-01-01T00:00:00Z", "claim": { "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4", "passport": { "id": "urn:uuid:79c181dc-73c7-11e8-8c1f-2bb1fd2d268a", "type": "Passport", "traveler": { "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4", "givenName": "Malathi", "familyName": "Hamal", "citizenship": "US" }, /* any other passport fields */ } }, "proof": {/* signature by gov't */} }
{ "@context": [ "https://w3id.org/credentials/v1", "https://example.com/travel-vocab/v1" ], "id": "urn:uuid:b306614c-73c7-11e8-b596-47e8c5ce9144", "type": ["VerifiableCredential", "PassportCredential"], /* gov't DID */ "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV", "expires": "2020-01-01T00:00:00Z", "claim": { "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu", "givenName": "Anand", "familyName": "Hamal" "citizenship": "US", /* any other claims made by gov't */ }, "proof": {/* signature by gov't */} }
{ "@context": [ "https://w3id.org/credentials/v1", "https://example.com/travel-vocab/v1" ], "id": "urn:uuid:05a47fe2-73c8-11e8-ac1e-7fe0051a1d75", "type": ["VerifiableCredential", "BirthCertificate"], "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV", "expires": "2020-01-01T00:00:00Z", "claim": { "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu", "citizenship": "US", "birthDate": "2017-10-01T00:00:00Z", "birthPlace": { "type": "Hospital", "address": { "type": "US address", "addressLocality": "Denver", "addressRegion": "CO", "postalCode": "80209", "streetAddress": "123 Main St." } }, "givenName": "Anand", "familyName": "Hamal", "parent": [{ "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4", "type": "Person", "givenName": "Malathi", "familyName": "Hamal", "maidenName": "Holla" }, { "id": "did:example:BgXRjB4RPrrsUVoVNaYNwzfznKsWep7AWrZkiyVcorEN", "type": "Person", "givenName": "Rajesh", "familyName": "Hamal" }] }, "proof": {/* signature by gov't */} }
{ "@context": [ "https://w3id.org/credentials/v1", "https://example.com/travel-vocab/v1" ], "id": "urn:uuid:58c08196-73c6-11e8-b030-3bd8a829a356", "type": ["VerifiableCredential", "ChildTravelPass"], "issuer": "did:example:BgXRjB4RPrrsUVoVNaYNwzfznKsWep7AWrZkiyVcorEN", "expires": "2018-07-01T00:00:00Z", "claim": { "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu", "potentialAction": { "type": "TravelAction", "agent": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu", "participant": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4", "location": { "type": "Country", "address": { "addressCountry": "CA" } } } }, "proof": {/* signature by Rajesh proving control of DID */} }
The editors are thankful to the contributions from the Web Payments Workshop, the Web Payments Community Group, the Web Payments Interest Group, the Credentials Community Group, the Verifiable Claims Task Force, and the Verifiable Claims Working Group.