W3C home > Mailing lists > Public > public-credentials@w3.org > August 2021

Re: Diagrams for VC HTTP API work [was Re: [AGENDA] VC HTTP API Work Item - August 17th 2021]

From: Moses Ma <moses.ma@futurelabconsulting.com>
Date: Fri, 20 Aug 2021 22:18:26 -0700
To: Joe Andrieu <joe@legreq.com>, Credentials Community Group <public-credentials@w3.org>
Message-ID: <66cf991f-0b9d-dcb6-8cf5-54df4ceffb2f@futurelabconsulting.com>
Hi Joe,

Thanks for sending these diagrams. I actually had a suggestion for a new 
kind of diagram, but first, let me explain why...

1) When I was in college, I majored in physics and took this class from 
this amazing physicist, Richard Feynman. He had this great story about 
the time his college math professor decided to assign an unsolvable 
problem to see what would happen. Feynman said he realized that none of 
what he was taught would work to solve it, so he invented - on the spot 
- a new mathematics of fractional bases to solve the problem.

2) Later in that lecture, he described how he came up with Feynman 
diagrams, and the reason was because a simple diagram could replace a 
page of equations. He created a new method of diagramming to figure out 
what was going on, so he could totally understand it.

3) He finished by saying that if a professor couldn't explain something 
so a freshman (like us) could understand it, in really simple terms, 
s/he probably didn't really understand it completely himself. 
Understanding comes with the ability to simplify its explanation.

Now, DIDs and VCs are a bit like quantum physics in terms of their 
complexity, and I'd really like to come up with a different kind of 
diagramming to explain how they work in terms that a "freshman" could 
understand them, without a mastery of software engineering and cryptography.

What I came up with is what I call "user experience causality 
diagramming", that tries to explain as simply as possible, how something 
like a VC would work. For example, if I have to explain it to a cruise 
ship operator, they have to feel like they understand it before they'd 
be willing to pilot it, never mind staking their career on it.

Here's a sample of what one might look like, which is supposed to be 
very simple:
If you, or any of the others, think this might have some potential for 
better explaining how VCs would work than the more "programmer centric" 
diagrams you produced, I'd love to participate in a small work project 
with a small number of us to figure out a meaningful standardized 
approach to visualizing VC processes.

Moses

PS, sorry for bloviating again, it's a side effect of aging...




On 8/16/21 2:16 PM, Joe Andrieu wrote:
> Howdy folks,
>
> Based on conversations with the use case team, I've put together the 
> attached diagrams, illustrating a minimum conceptual model based on 
> the USCIS Green Card use case, as implemented using CHAPI.
>
> I'm sure this model is lacking some elements for folks who have a 
> slightly different configuration. I chose this use case because it is 
> the one I'm most familiar with, making it easiest to be complete. I'd 
> like to speak to folks with different scenarios and see if we can't 
> come up with a variation that covers your requirements.
>
> A few notes.
>
> 1. There are sequence and communications diagrams for both issuance 
> and verification, plus a class diagram.
>
> 2. All of the components are "owned" by one of the core roles (Holder, 
> Issuer, Verifier) are color coded.
>
> 3. The class diagram aggregates the method calls on each of the 
> lifelines in the other diagrams.
>
> 4. The components are
>   a. *Holder* The entity who holds the VC once issued and later 
> presents it for verification.
>   b. *Holder Application *The software or service that allows holders 
> to manage their credentials. Often called a wallet. For symmetry, it 
> could be called a Holder Service.
>   c. *Storage Service *The software or service that actually stores 
> VCs long term (on behalf of the holder)
>   d. *Issuer Role* The website or software that provides issuing 
> functionality to a holder on behalf of that issuer)
>   e. *Issuer Service* Software or service that actually signs VCs and 
> VPs) This component is used by both the issuer  (to mint VCs) and the 
> holder (to create VPs for presentation)
>   f. *Verifier Role* The website or software that uses a Verification 
> Service as part of its decision making process for providing services 
> to holders.
>   g. *Verifier Service *The software or service that verifies VCs and 
> VPs by checking proofs and checking status.
>
> Note that there are more components than had previously been itemized 
> in the vc-http-api work, because storage and status services had not 
> be broken out as distinct capabilities. This sometimes caused 
> confusion. Some implementations will bundle all or some of these 
> components into a full-stack credential platform, however, the APIs, 
> IMO, must support interoperability between these components. So, yes, 
> a Holder Application will need to have a way to get VPs created. 
> Instead of assuming that's a subcomponent of the Holder Application, 
> breaking it out illustrates, for example, the API that might be useful 
> at an Issuer when acting on behalf of a holder.
>
> 5. The class diagram is a distillation across all component instances 
> in all sequence and communications diagrams, so it starts to suggest 
> an API for each of those components. Since I have only modeled one 
> scenario's issuance and verification, I expect the API is not full 
> coverage. However, it is nice to see that I only have the messages 
> indicated by the USCIS, CHAPI-based flow (where, for example, VCs are 
> always delivered in VPs, so the Verifier Service doesn't need a Verify 
> VC method).
>
> 6. The message names are chosen for logical consistency in "normal 
> English"; they should likely be turned into camel case or something 
> and we can have a bikeshed festival.
>
> 7. The dance between roles and services matches the architecture for 
> the services operating SaaS style for a front-end that is providing 
> the "role" functionality on behalf of the actual entity in that role. 
> For example, the USCIS plugfest had mock-up USCIS websites that 
> beneficiaries interacted with, and which, in turn, it interacted with 
> Issuer services. It is understood that the enterprising organization 
> could run both the role and service software using its own bespoke 
> custom software.
>
> 8. It is worth noting that all of the user tasks from the VC Use Cases 
> document, except two, are accomodated. 
> https://w3c.github.io/vc-use-cases/#user-tasks 
> <https://w3c.github.io/vc-use-cases/#user-tasks> In particular, "move 
> claim" and "amend claim" don't really have much support: neither the 
> spec nor any implementation I know of addressed these use cases. "Move 
> claim" feels like it gets addressed by "store", "retrieve", and 
> "delete". Notably, the "delete" is not in the VC use case document, 
> but probably should be; It almost certainly needs to be a feature in 
> at least the storage service API. For the "amend" claim, I believe the 
> only real way to do that today (given cryptographic proofs) is to 
> revoke and re-issue. FWIW, I think we should remove "move" and "amend" 
> the VC Use Cases document.
>
> 9. The "revoke" capability is not modelled yet, but it makes sense to 
> add it to the status service (we just have the verifier service 
> checking status). I just didn't build out that diagram.
>
> That's it for now.
>
> Plenty of fodder for discussion.
>
> Comments and feedback welcome.
>
> -j
>
>
> On Sun, Aug 15, 2021, at 4:41 PM, Manu Sporny wrote:
>> VC HTTP API Work Item - August 17th 2021
>> Time: Tue 4pm ET, 1pm PT, 10pm CET, 8am NZDT (Wed)
>>
>> Text Chat:
>> http://irc.w3.org/?channels=ccg <http://irc.w3.org/?channels=ccg>
>>       irc://irc.w3.org:6665/#ccg
>>
>> Jitsi Teleconf:
>> https://meet.w3c-ccg.org/vchttpapi <https://meet.w3c-ccg.org/vchttpapi>
>>
>> Duration: 60 minutes
>>
>> MEETING MODERATOR: Manu Sporny
>>
>> AGENDA:
>>
>> 1. Agenda Review, Introductions (5 minutes)
>>
>> 2. VC HTTP API Renaming Poll Reminder (5 minutes)
>> https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0124.html 
>> <https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0124.html>
>>
>> 3. Simple Majority Objection w/ GNAP-KBAT (30 minutes)
>> https://github.com/w3c-ccg/vc-http-api/pull/224/files#r682106281 
>> <https://github.com/w3c-ccg/vc-http-api/pull/224/files#r682106281>
>> https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0110.html 
>> <https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0110.html>
>>
>> 4. Feature Scoping (15 minutes)
>> https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0122.html 
>> <https://lists.w3.org/Archives/Public/public-credentials/2021Aug/0122.html>
>>
>> 5. Pull Requests (5 minutes)
>> https://github.com/w3c-ccg/vc-http-api/pull/224 
>> <https://github.com/w3c-ccg/vc-http-api/pull/224>
>>
>> -- manu
>>
>> -- 
>> Manu Sporny - https://www.linkedin.com/in/manusporny/ 
>> <https://www.linkedin.com/in/manusporny/>
>> Founder/CEO - Digital Bazaar, Inc.
>> News: Digital Bazaar Announces New Case Studies (2021)
>> https://www.digitalbazaar.com/ <https://www.digitalbazaar.com/>
>>
>>
>
> --
> Joe Andrieu, PMP joe@legreq.com <mailto:joe@legreq.com>
> LEGENDARY REQUIREMENTS                        +1(805)705-8651
> Do what matters. http://legreq.com <http://www.legendaryrequirements.com>
>
>

-- 

*Moses Ma | Managing Partner*

moses.ma@futurelabconsulting.com | moses@futurelab.ventures | 
moses@ngenven.com

v+1.415.568.1068 | skype mosesma | /linktr.ee/moses.tao/ 
<http://linktr.ee/moses.tao>

FutureLab provides strategy, ideation and technology for breakthrough 
innovation and third generation blockchains.

Learn more at /www.futurelabconsulting.com/ 
<http://futurelabconsulting.com>. For calendar invites, please cc: 
mosesma@gmail.com


Or whet your appetite by reading /Agile Innovation/ 
<http://www.amazon.com/Agile-Innovation-Revolutionary-Accelerate-Engagement/dp/B00SSRSZ9A> 
| /Quantum Design Sprint/ 
<https://www.amazon.com/Quantum-Design-Sprint-Application-Disruptive/dp/1799143864> 
| my blog at /psychologytoday.com/ 
<http://www.psychologytoday.com/blog/the-tao-innovation>.

NOTICE TO RECIPIENT: THIS E-MAIL IS MEANT FOR ONLY THE INTENDED 
RECIPIENT OF THE TRANSMISSION. IF YOU RECEIVED THIS E-MAIL IN ERROR, ANY 
REVIEW, USE, DISSEMINATION, DISTRIBUTION, OR COPYING OF THIS E-MAIL IS 
STRICTLY PROHIBITED. PLEASE NOTIFY THE SENDER IMMEDIATELY OF THE ERROR 
BY RETURN E-MAIL AND PLEASE DELETE THIS MESSAGE FROM YOUR SYSTEM. THIS 
EMAIL SHOULD NOT BE CONSIDERED BINDING; HARD COPY DOCUMENTS ARE REQUIRED 
TO CREATE LEGALLY BINDING COMMITMENTS. FOR CALENDAR INVITES, PLEASE CC: 
MOSESMA@GMAIL.COM
Received on Saturday, 21 August 2021 05:19:19 UTC

This archive was generated by hypermail 2.4.0 : Saturday, 21 August 2021 05:19:22 UTC