Add Verifiable Credential digital signature views for multiple examples.

[msporny]

This PR adds the respec-vc extension to the specification and activates it for example #4. You can view the result here:

https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/pull/834.html#example-usage-of-the-id-property

or see the image below:

Click the tabs to view the Credential, Verifiable Credential (with proof), and Verifiable Credential (as JWT).

Once this is merged, I can go through and update any other examples that would benefit from this feature. Once that's done, we can close issue #833 and PR #817.

---

Preview | Diff

[kdenhartog]

This looks good to me. Is the respec-vc project just taking the base credential and generating the secondary examples on the fly for this?

[iherman]

This looks really good, @msporny

[msporny]

This looks good to me. Is the respec-vc project just taking the base credential and generating the secondary examples on the fly for this?

Yes, that is correct. The secondary examples are generated from source (from the text in the example PRE HTML tag) in real-time.

[TallTed]

Hmmmm. All tabs appear to me to be the same color, regardless of which is displayed. Is that adjustable, and/or can the boxes be made more "tab"-shaped? My goal here is to communicate which of the options is being displayed, and that the others are available options. This might be made more clear if the 3 boxes are stretched to fill the full column width, instead of being tight-left?

[msporny]

Is that adjustable, and/or can the boxes be made more "tab"-shaped? My goal here is to communicate which of the options is being displayed, and that the others are available options. This might be made more clear if the 3 boxes are stretched to fill the full column width, instead of being tight-left?

Given that fixing that will throw me into a pit in hell called "CSS: How Hard Could It Be?!", and I don't want to necessarily enter that particular pit in hell right now... I've raised an issue on respec-vc: w3c/respec-vc#1

I know it sounds simple, but due to the way ReSpec works, it's not. You have to hand code everything using pure HTML DOM APIs available in every browser and in a way that remains accessible. You cannot use external libraries to do this... you're stuck in "assembler land". If it makes you feel any better, it'll bother me until it's fixed... but I have higher priorities right now. PRs welcome. :)

Once the upstream package is fixed to look better, this spec will get the upgrade automatically (when we choose to upgrade versions).

[TallTed]

CSS: How Hard Could It Be?!

Fair enough. I've been there. Don't look forward to another trip. :-/

[dlongley]

Great!

[kdenhartog]

Is that adjustable, and/or can the boxes be made more "tab"-shaped? My goal here is to communicate which of the options is being displayed, and that the others are available options. This might be made more clear if the 3 boxes are stretched to fill the full column width, instead of being tight-left?

Given that fixing that will throw me into a pit in hell called "CSS: How Hard Could It Be?!", and I don't want to necessarily enter that particular pit in hell right now... I've raised an issue on respec-vc: digitalbazaar/respec-vc#1

I know it sounds simple, but due to the way ReSpec works, it's not. You have to hand code everything using pure HTML DOM APIs available in every browser and in a way that remains accessible. You cannot use external libraries to do this... you're stuck in "assembler land". If it makes you feel any better, it'll bother me until it's fixed... but I have higher priorities right now. PRs welcome. :)

Once the upstream package is fixed to look better, this spec will get the upgrade automatically (when we choose to upgrade versions).

The alternative method I was looking to go with this is which somewhat addresses the tabbing concern raised by @TallTed was to use the method that the json-ld-syntax v1.1 did which was to define all the examples by hand from the looks of it. I prefer your respec-vc approach because it will be less cumbersome on us to keep these things updated. Maybe we can take some of the class designs that were made over in that spec and add that here as well. Not sure, but I'll move this discussion over to that issue you raised to see if it might help us go in the right direction.

[iherman]

The issue was discussed in a meeting on 2021-11-17

• no resolutions were taken

View the transcript

3.2. Add new Verifiable Credential views for example 4. (pr vc-data-model#834)

See github pull request vc-data-model#834.

Brent Zundel: the last thing we said is when a PR exists that addresses the problems. We'll take a look at that PR now.
… then jump back to 817.
… so 834 addresses 817 potentially so we'll take a look at this first.

Manu Sporny: we now have a display for a variety of examples including bare credential, w/ ld proofs, and w/ JWT proofs.
… the enhancements that people have asked for is better tabbing, highlighting active tabs, show intermediate form for JWTs.
… they're all good asks and my suggestion is they're all enhancements and we can address them in other PRs.
… this one addresses just example 4.
… there's another PR which updates as many examples as possible.
… those are in PR 835.

David Chadwick: My suggestion is that we add another tab with the intermediate JWT tab.
… I'm willing to do that as well.
… I'd like to suggest that we add this intermediate tab as well.

Manu Sporny: it's not as easy as just adding one.
… these are all auto generated which requires coding it up.
… it's a decent bit of work.
… unless you already have something that can generate the intermediate form and I just didn't have the time to do that yet.

David Chadwick: I thought this was hand done for each one.

Manu Sporny: this is all available in the digitalbazaar/respec-vc repo.
… I've got concerns about showing that, but I don't intend to block it.
… it raises questions about how deep do we want to go around intermediate forms for other proof types as well.
… so I don't want those discussions to block this PR from going forward for now.

Brent Zundel: suggestion is that we work to merge this PR and raise issues for each of the specific enhancements we'd like to see.

Manu Sporny: +1 to the course of action brent just described..

David Chadwick: I see this intermediate format as examples is fundamental and very helpful.
… particularly around the clarification stuff that we've seen for JWT encodings.
… so these examples would help for further clarification.
… let's not close this today. I want to spend some time to go ahead and take a look at this one.
… our current work mode requires notifications to the CCG.
… so a 14 day window from the notification should occur.
… so there's a possibility that during that window requested changes will be made.
… let's go ahead with the 14 day window and then I can take a look during that time.

Brent Zundel: so now the question is have there been enough progress on 834 and 835 to close issue 817.

David Chadwick: yes I'm happy with that.

Brent Zundel: I'll leave it to the editors to update the labels and notify the CCG about the rest.

[msporny]

I have made a number of upgrades to these examples, namely:

1. Per @David-Chadwick's request, the JWT examples now show the unencoded header and payload as well as the final JWT. All known JWT bugs have been fixed while staying conformant with the spec.
2. Per @TallTed's request, the buttons have been upgraded to tabs, with all of the insane CSS stuff necessary to make them look like tabs, handle tab selection/hovering/activation, AND export properly into static snapshots.
3. respec-vc has been upgraded to v1.0.0 and released on a global content distribution network to make it easier for people to use.

You can see what the new output looks like here: #834 (comment) and play around with the tabs here:

https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/pull/834.html#example-usage-of-the-id-property

You can read more about how this extension for ReSpec works here:

https://github.com/digitalbazaar/respec-vc#readme

... aaaand, queue the "I'm using RandomBrowser v14.1.0.328704237 and X doesn't render for me when I Y." comments. :P

[David-Chadwick]

Thankyou very much @msporny. This is a fantastic improvement. @OR13 and myself have been discussing writing a JWT Implementation Guidelines to provide implementors with best practices for producing JWTs. The one thing I would note about your JWT example is that it always uses duplication (as well as) instead of replacement (instead of), whilst both are allowed in the current recommendation. Thus I would kindly ask you to add a note to say: "Note: the JWT example above uses duplication of the credential properties in the claims, whereas replacement is equally well allowed. (See the JWT Implementation Guidelines for best practices [ref])" the text in parenthesis being added once this documents is available to be referenced.

[msporny]

"Note: the JWT example above uses duplication of the credential properties in the claims, whereas replacement is equally well allowed. (See the JWT Implementation Guidelines for best practices [ref])"

I will add that note when the JWT Implementation Guidelines document exists.

[kdenhartog]

This looks great @msporny

Already approved, but definitely liking the new improvements as well

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.