Add VC-JWT diagrams to core specification

[msporny]

@OR13 suggested that VC-JWT diagrams should be added to the core specification. I'm assigning the VC-JWT Editors to do that given that they are the experts on the matter.

The tooling used to generate the diagrams in the specification was Google Draw. Post processing was done in Inkscape with an export optimized SVG. Further editing was made on the SVG to make them accessible by Chaals, and then further refinement on text placement was done by hand editing the SVG.

[selfissued]

Boy, that sounds straightforward...

[OR13]

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#DDDDDD',
      'primaryTextColor': '#000000',
      'nodeBorder': '#000000',
      'edgeLabelBackground': '#DDDDDD',
      'clusterBkg': '#DDDDDD',
      'clusterBorder': '#000000',
      'lineColor': '#000000',
      'fontFamily': 'monospace',
      'darkmode': true
    }
  }
}%%
graph 
    subgraph 0 [&nbsp Verifiable Credential  &nbsp ]
        n4("Metadata")
        n5("Claim(s)")
        n6("Proof(s)")
	end
    
    subgraph 1 [&nbsp JSON Web Token &nbsp ]
        n1("Header")
        n2("Claimset")
        n3("Signature")
	end
    
    subgraph 2 [&nbsp Claimset &nbsp ]
        subgraph 3 [&nbsp Metadata &nbsp ]
            n7("AlumniCredential")
            n8("Credential 123")
            n9("ExampleUniversity")
            n10("2023-05-21T19:16:35.495Z")
        end
        subgraph 4 [&nbsp Claims &nbsp ]
            n11("Pat")
            n12("ExampleUniversity")
        end
    end
    subgraph 5 [&nbsp Protected Header &nbsp ]
        n13("iss: did:example:123")
        n14("kid: #key-42")
        n15("alg: ES384")
        n16("typ: vc+ld+jwt")
        n17("cty: vc+ld+json")
	end
	0 -- &nbsp representation &nbsp  --> 1
    n8 -- type --> n7
    n8 -- validFrom --> n10
    n8 -- issuer --> n9
    n8 -- subject --> n11
    n11 -- AlumniOf --> n12
    n2 --> 2
    n1 --> 5

class n1,n4,n7,n8,n9,n10,n13,n14,n15,n16,n17 RedNode;
class n2,n5,n11,n12 YellowNode;
class n3,n6 GreenNode;

classDef RedNode text-align: center, color:#000, fill:#DDAABB, stroke:#000, stroke-width:1px;
classDef YellowNode color:#000, fill:#FFEE99, stroke:#000, stroke-width:1px;
classDef GreenNode color:#000, fill:#BBDDAA, stroke:#000, stroke-width:1px;

Loading

🌶️ view source

[OR13]

With "proof tunneling"

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#DDDDDD',
      'primaryTextColor': '#000000',
      'nodeBorder': '#000000',
      'edgeLabelBackground': '#DDDDDD',
      'clusterBkg': '#DDDDDD',
      'clusterBorder': '#000000',
      'lineColor': '#000000',
      'fontFamily': 'monospace',
      'darkmode': true
    }
  }
}%%
graph 

        
    subgraph 1 [&nbsp JSON Web Token &nbsp ]
        n1("Header")
        n2("Claimset")
        n3("Signature")
    end
    
    subgraph 7 [&nbsp Verifiable Credential &nbsp ]
        subgraph 2 [&nbsp Credential Graph &nbsp ]
            subgraph 3 [&nbsp Metadata &nbsp ]
                n7("AlumniCredential")
                n8("Credential 123")
                n9("ExampleUniversity")
                n10("2023-05-21T19:16:35.495Z")
            end
            subgraph 4 [&nbsp Claims &nbsp ]
                n11("Pat")
                n12("ExampleUniversity")
            end
        end
        subgraph 6 [&nbsp Proof Graph &nbsp ]
            n18("Signature 456")
            n19("DataIntegrityProof")
            n20("2023-05-21T20:09:37.988Z")
            n21("zu4oey5q...eV6")
            n22("Example University Public Key 7")
        end
    end
        
        
    subgraph 5 [&nbsp Protected Header &nbsp ]
        n13("iss: did:example:123")
        n14("kid: #key-42")
        n15("alg: ES384")
        n16("typ: vc+ld+jwt")
        n17("cty: vc+ld+json")
    end
        

    2 -- &nbsp proof &nbsp  --> 6

    n8 -- type --> n7
    n8 -- validFrom --> n10
    n8 -- issuer --> n9
    n8 -- subject --> n11
    n11 -- AlumniOf --> n12
    n2 --> 7
    n1 --> 5

    n18 -- type --> n19
    n18 -- created --> n20
    n18 -- proofValue --> n21
    n18 -- verificationMethod --> n22

class n1,n4,n7,n8,n9,n10,n13,n14,n15,n16,n17 RedNode;
class n2,n5,n11,n12 YellowNode;
class n3,n6,n18,n19,n20,n21,n22 GreenNode;

classDef RedNode text-align: center, color:#000, fill:#DDAABB, stroke:#000, stroke-width:1px;
classDef YellowNode color:#000, fill:#FFEE99, stroke:#000, stroke-width:1px;
classDef GreenNode color:#000, fill:#BBDDAA, stroke:#000, stroke-width:1px;

Loading

[OR13]

Related PR is the digital bazaar tooling which is powering the current examples rendered in the spec... w3c/respec-vc#8

[iherman]

The issue was discussed in a meeting on 2023-06-28

• no resolutions were taken

View the transcript

2.10. Add VC-JWT diagrams to core specification (issue vc-data-model#1135)

See github issue vc-data-model#1135.

Brent Zundel: #1135 - Add VC JWT diagrams to core specification.

Manu Sporny: yes, this can be a post-CR thing.

Michael Prorock: +1 post cr.

Brent Zundel: as diagrams are non-normative this is a post-CR.

Orie Steele: related to date integrity proofs in the core context and need to be understood by implementers. The pictures are one of the most important information we offer.

Shigeya Suzuki: Is it possible to add "diagram" tag for any issues requests diagrams?

Manu Sporny: +1 for diagrams visualizing both securing mechanisms.

Orie Steele: prefer to see the diagrams upgraded include proof specs that define securing mechanisms.

Manu Sporny: (PRs welcome) :).

Brent Zundel: w3c/vc-data-integrity#107.

Orie Steele: anyone working on JWT want diagrams to show up in the core data model? open a PR.

Brent Zundel: PRs are welcomed! (Manu encouraged that).

Orie Steele: You can always put your text in an issue, and ask an editor to do the PR for it.

Brent Zundel: if anyone has a problem raising a PR ask for help of Brent or anyone to learn how.

Michael Jones: reinforced Orie's comment about stuff that should be in the securing spec.

Orie Steele: +1 selfissued.

Manu Sporny: -1 to not talking about securing in the core spec.

Dave Longley: of course, philosophies around external vs. internal securing mechanisms are at odds there -- we should remember they are different things and that may influence approaches.

[OR13]

I have tooling that generates similar graphs for JWT headers, which serve the same purpose...

I can take the action to produce svg diagrams for JWT headers.

[iherman]

I have created an alternative diagram for the simple case (based on the sketches of @OR13 above); it is in the create-jwt-diagram branch of the repo at:

https://raw.githubusercontent.com/w3c/vc-data-model/create-jwt-diagram/diagrams/vc-jwt.svg

But it is also reproduced below.

My goals were to make it as close to the existing diagram in the spec, meaning it reuses exactly the same graph for the credential graph itself (not only content-wise but also visually; I just made a copy/paste using the same drawing program). This also means that the diagram is also "dark-mode-safe".

I made it also a bit simpler then what is in #1135 (comment), and I also tried to make it "narrow" so that it would fit into the spec area.

I am not sure it is worth adding the (DI) proof into the diagram (as on #1135 (comment)), I would think it just muddles the information at that point.

I am happy

• reproducing the diagram for a VP if we think it is important
• come up with a PR that incorporates these diagrams into §3.2 and §3.3. Note that the diagram descriptions may need some modification, making use of the external vs. embedded proof terminology, but that is fine.

However, before getting into a PR, I wanted to see if the direction is acceptable...

cc @OR13 @msporny @decentralgabe

(@decentralgabe, I made you a promise in #1326 (comment) to do this...)

[OR13]

Thanks! This looks excellent, I would remove iss from the header and make kid an absolute URL.

[decentralgabe]

This is awesome work @iherman. Greatly appreciate you taking the time and effort to do this. It looks really good.

[iherman]

I have updated the vc-jwt example, and I have also created a vp-jwt one, see below.

Specific questions:

• Is it o.k. to use "JWS (Decoded)" as a label? Specifically, should it say "JWT" or "JWS". My understanding is that "S" stands for the signature, but the VCDM spec uses JWT everywhere, so I am not sure.
• Is it o.k. to use vp+ld+jwt for typ in the Presentation version?

Specific questions to @msporny as the "main" editor: should I simply add the new diagram, preceded with an explanation text, after Figure 6 (resp. Figure 8)? I was wondering whether it is possible to do the same trick as in, for example, Example 5, but I see that this is done via a JS script, and it is not 100% how I would put this into the spec for figures (and whether it is a good idea).

I also cc this to @TallTed explicitly, who always locates the possible problems in these things... :-). Would appreciate your remarks, Ted.

Here are the two diagrams as they look now:

[TallTed]

[@iherman] I also cc this to @TallTed explicitly, who always locates the possible problems in these things... :-). Would appreciate your remarks, Ted.

The pressure's on!

Overall, I really like these.

In no particular order ...

• I would put propertyNames and literals into code/monospace font
• since the ellipses aren't all the same size anyway, I would make most (if not all) of them a bit larger — so there's always a visible gap between the text and the border
• as I understand things, both diagrams should have header typ of JWT (application/ omitted per RFC 7515; all caps per RFC 7519)
• as I understand things, the second diagram should have header cty of vp+ld+json (not vc+...) (being JWS shorthand for application/vp+ld+json)
• it seems odd to have a verifiableCredential (and its verifiable credential graph) in the collection of verifiable presentation graphs

If any of the above disagrees with the current body text, I think that text is in error and needs re-review.

[iherman]

The pressure's on!

😀

• I would put propertyNames and literals into code/monospace font
• since the ellipses aren't all the same size anyway, I would make most (if not all) of them a bit larger — so there's always a visible gap between the text and the border

I see what you mean and I agree. However, if you agree, I would prefer to postpone these changes into a separate future (strictly editorial) PR. The reason is that these changes should then be made on Figures 6 and 8 of the current spec, because it is important to keep consistency. Indeed, one of the important parts of the message is that the same VC graph can be either secured through DI (which is on Figure 6) and with JWT (which is the first of the two new diagrams).

I will take care of these later, I promise!

• as I understand things, both diagrams should have header typ of JWT (application/ omitted per RFC 7515; all caps per RFC 7519)

Hm. I leave that to the JWT experts (which I am not!). If I understand you well, you say the header part should say:

typ: JWT,
cty: vc+ld+json

This is indeed in line with some other text (like the JWT Handbook which I just checked), but I took the model of these diagrams from #1135 (comment).

I need clear directions on this. @OR13?

• as I understand things, the second diagram should have header cty of vp+ld+json (not vc+...) (being JWS shorthand for application/vp+ld+json)

Damn. I changed that for typ; I forgot the cty value. Done (on my own machine for now).

• it seems odd to have a verifiableCredential (and its verifiable credential graph) in the collection of verifiable presentation graphs

Hm. My understanding on using JWT with VP-s is that we take all the VP material, remove the proofs, and turn it into a payload. This is what I have done. What is exactly wrong with this in your view?

[OR13]

I would ommit typ for now, it's considered a best practice to include it, but there is no consensus on what it should be for multiple suffixes.

There is a PR up that removes all the typ related media types from vc-jose-cose.

My preference for diagrams is to always show the minimal legal structure first, and then possibly show a detailed example filled with optionality.

I do not think that the core data model is the right place for diagrams related to securing speciations.

[iherman]

My preference for diagrams is to always show the minimal legal structure first, and then possibly show a detailed example filled with optionality.

I agree.

Just to avoid unnecessary rounds, this means that the header part would include:

kid: https://....
cty: vc+ld+json (or vp+...)
alg: E384

Is that correct?

What about the usage of JWT vs. JWS in the (informal) label on the upper left-hand corner?

[OR13]

@iherman I think its best to call it a JWT, and we'll need to do one for COSE Sign1 as well I suppose, the header will be the same, and the payload will also be the same.

If we want to cover selective disclosure we will need to cover additonal details... cc @Sakurann

[iherman]

OK for JWT.

My knowledge about the COSE version converges to zero 😀. But is it fundamentally different than the JWT case? Because if the difference is only encoding, then I would think it is enough to mention it in the accompanying text (and maybe add diagrams into the JOSE-COSE document). WDYT?

[OR13]

I think it's probably ok to leave COSE examples in the securing spec.

I would prefer all securing diagrams be placed in securing specs.

[iherman]

I would prefer all securing diagrams be placed in securing specs.

Do you mean that you would prefer to remove the current Figures 6 and 8, too? If so, I respectfully disagree. That whole section is an introductory section giving a high level overview of what is happening in credentials, and that should also include something on securing (which is also present elsewhere in the spec). Adding the new diagrams sounds essential to me to separate the external and embedded securing mechanisms on the same level.

[OR13]

I think high level diagrams and diagrams covering the RDF data model are fine, but I continue to object to the core data model including securing specific diagrams and content. I think it's bad architecture, and leads to harmful security assumptions.

Understanding claims and securing them should be separated unless there is only one way to secure them.

Specifications that take dependency on the core data model, such as C2PA... Have to explain that they only use the data model, not data integrity proofs... This supports the position that blending the two together is harmful enough to cause dependent specifications to write extra text.

Also, proof is defined twice, once as a general purpose securing mechanism, and once in the context of the core data model... That's confusing for readers.

[msporny]

I continue to object to the core data model including securing specific diagrams and content. I think it's bad architecture, and leads to harmful security assumptions.

-1, the specification is about creating verifiable credentials, not just credentials by themselves.

There are multiple ways to make the core data model verifiable, and the WG has explicitly defined what some of those mechanisms are and it's appropriate to talk about those things in the specification (and point to / defer to the securing specifications for more details).

In addition, proof is an extension mechanism. This is not conveyed as we as it should be in the specification presently, so I do agree that we might want to make it more explicit that proof is a general extension mechanism for securing mechanisms.

[iherman]

I think high level diagrams and diagrams covering the RDF data model are fine, but I continue to object to the core data model including securing specific diagrams and content. I think it's bad architecture, and leads to harmful security assumptions.

Understanding claims and securing them should be separated unless there is only one way to secure them.

Specifications that take dependency on the core data model, such as C2PA... Have to explain that they only use the data model, not data integrity proofs... This supports the position that blending the two together is harmful enough to cause dependent specifications to write extra text.

Also, proof is defined twice, once as a general purpose securing mechanism, and once in the context of the core data model... That's confusing for readers.

@OR13 I have the impression that you are raising issues that are not part of the current discussion in this issue. Or would you object putting the diagrams that I created into the VCDM spec?

I must admit I am not sure what we are discussing here.

[iherman]

PR #1404 has been raised. This issue should be closed if and when that PR gets merged.

[iherman]

#1404 has just been merged, closing.