Re: VC HTTP API Use Cases

Manu,

Thanks for the contributions. Everything helps.

We didn't quite get the template right, however. So let me give some feedback so folks can see what we are looking for.


*Issue Verifiable Credential*

Author: Manu Sporny

Author Email: _msporny@digitalbazaar.com_ Github: @msporny 

Description: A developer that is creating a back-end system would like to easily issue a verifiable credential by providing the unsigned credential and a few options that are sent to an HTTP API endpoint.


Requirements: Issue Verifiable Credential


Four issues jump out from reviewing this.
1. Name
2. Specific value created
3. Actor
4. Task v Problem

*Name*. First, as requested in the template, please identify a specific person. "A developer" is not a specific person. From the template: "Please use unique, optimally unisex, names (no “Bob” and “Alice”, please) for the people named in the description and the title."

*Value*. Sadly, issuing a VC does not inherently create value. To wit: I can sit here in my office creating arbitrary VCs all day, and no value would be created. *Why* is the developer creating a VC?

*Actor*. I doubt the real value in this scenario is going to be the developer issuing a VC. More likely, it is an organization that is issuing a VC to further some organizational mandate.

*Task*. We should provide better guidance for this. Let me take a few sentences to flesh it out.

When I work with clients doing use case development, we separate the use cases into two distinct diagrams: a Domain Map and a Task Map.

The domain map illustrates a sampling of real-world problems that can be addressed with effective use of the system. A Task map illustrates the tasks that one would expect to be able to accomplish, given the system.

For example, recovering from a credential loss does not create innate value, but it is a task that people need to be able to do.

You can see these two distinctions in the VC Use Case Document [1] and the DID Use Case & Requirements document [2].

In the VC Use Case document the Domain Map is in Section 3 User Needs [3], where we list all of the "Problem Domains", followed by a brief description of each. The Task Map is presented in Section 4 User Task [4].

In the DID Use Case & Requirements document, the Domain Map is at the top of Section 2 Use Cases [5] and the Task Map is across the entirety of Section 5 DID Actions [6]

So, this particular suggestion quoted above is a reasonable candidate for a Task-based Use Case. However, I think we still have a mismatch of narrative. Seems to me it isn't that the developer gets to issue a credential, its that they use the API from the web app they have developed to request the issuance of a VC with a particular set of claims, which is delivered server-to-server to the site running the web app, which then gives it to the subject/holder.

You can see that even this modest rewrite shifts focus to some interesting questions that weren't obvious from the previous description.
1. Is it a server-to-server exchange? Or does the web app directly contact the issuer endpoint via AJAX? Or peharps via a redirect?
2. Who is the ultimate recipient and how are they getting the credential? Is it, as described, through the web app then downloaded? How is it downloaded? Does the credential get into a wallet somehow? How is the end-user's wallet involved?
3. Is there a proof-of-control performed for the subject ID? Who does this? Is this a function provided by the API or is it a step presumed to have been completed by the web app before talking with the API?
4. What is the VC? What claims are being made?
5. Who is the issuer? Almost certainly not the developer

This might be rewritten to say

Carol is the technical administrator of the Digital Permanent Residence Card system operating under the authority of the United States Citizens and Immigration Service. She configures the USCIS Digital PRC website to dynamically trigger the issuance of Verifiable Credentials containing claims defined in to the Citizenship Vocabulary v0.3 [7] using information provided in real-time. Prior to requesting issuance, the website asks the beneficiary to provide a DID and performs a cryptographic proof of control using that DID. These VCs are minted in response to server-side requests from the website and delivered to the end-user's wallet through CHAPI. The VC is minted and returned to the website, which then delivers it to beneficiaries wallets, again using CHAPI.

This narrative puts some stakes in the ground about how the system actually needs to work. I'm sure others have different workflows to support other use cases.

With ALL OF THAT said, let me add that I'm picking on Manu because most of us in this space know he is competent, knowledgeable, and a continued source of contribution to the collective work. Plus, I know he won't take it personally.

Meanwhile, for everyone else, please consider submitting use cases, using the template.

They are GOLD, even if we end up polishing a bit.

Highlights from this exercise:
1. Name a unique specific person 
2. Identify the specific value that is created by the interaction
3. Illustrated the steps taken to create that value
4. (Bonus) Come up with a compelling title!

Thanks again for the input.

I'll work with Juan and Eric to distill all of these and tease out the Problem Domain cases from the Tasks.

-j

[1] https://w3c.github.io/vc-use-cases/
[2] https://w3c.github.io/did-use-cases/
[3] https://w3c.github.io/vc-use-cases/#user-needs
[4] https://w3c.github.io/vc-use-cases/#user-tasks
[5] https://w3c.github.io/did-use-cases/#uc
[6] https://w3c.github.io/did-use-cases/#actions
[7] https://w3c-ccg.github.io/citizenship-vocab/


On Mon, May 3, 2021, at 5:50 PM, Manu Sporny wrote:
> Hi all, I dropped a few use cases into the VC HTTP API Use Cases document
> using the template that TallTed provided (see pages 2 and 3):
> 
> https://docs.google.com/document/d/1-u0_Ub6feiX6DH3jXFJFjt6n3CwKGpkmC3VISqDkWL4/edit#heading=h.x59zaj4pqxo1
> 
> The template works well; others should try it out.
> 
> -- manu
> 
> -- 
> Manu Sporny - https://www.linkedin.com/in/manusporny/
> Founder/CEO - Digital Bazaar, Inc.
> blog: Veres One Decentralized Identifier Blockchain Launches
> https://tinyurl.com/veres-one-launches
> 
> 
> 

--
Joe Andrieu, PMP                                                                              joe@legreq.com
LEGENDARY REQUIREMENTS                                                        +1(805)705-8651
Do what matters.                                                                            http://legreq.com <http://www.legendaryrequirements.com/>