Apply diagram changes

[iherman]

This is just a warning place to adopt some changes on the vocabulary diagrams, see #171 (comment) and the followups in #171 (comment) and #171 (comment)

[iherman]

@TallTed, but also @dlongley, @msporny, @seabass-labrax

I have updated the two diagrams and put them up into the yml2vocab previews. I prefer not to touch the "real" files on the vcdm, resp. di, repositories; real PRs can come later when the last minute pre-cr frenzy is over. But I would welcome your comments, so that the final incorporation would only be a formality.

The two previews are here:

• VCDM Vocab
• DI Vocab

@TallTed I believe I have incorporated your comments, but your check would be welcome.

I have checked the color choices to see if it works all right with dark mode as well. I tested the files on several chromium based browsers with the experimental flag forcing dark mode on web sites; I also tested it with the "Dark Reader" plugin on Firefox. In all cases it looked o.k. to me, but @dlongley should be the final arbiter.

I actually had a version (which is mostly the version in the "official" drafts without the changes as requested by @TallTed) that did not use any background colors in the shapes. I kept those versions as well, but I personally prefer the more colorful version. It is of course a matter of taste; if you think it is better not to use colors to fill the shapes, I am happy to switch back.

(I am out next week, so no rush... I just wanted to get it out of the door before I go away...)

@seabass-labrax, just for info the process now is : export from draw.io and then run it through a script that is built on top of SVGO...

[msporny]

I would welcome your comments, so that the final incorporation would only be a formality.

The diagrams are fantastic, thank you @iherman!

The only thing that jumped out at me was this:

Why is there an "OR" there? What does it mean?

[iherman]

You are good at picking the weak points, @msporny.

These three properties are special in the sense as their domain is VerifiableCredential OR VerifiablePresentation, and I did not find a better way to represent this fact.

Some (weak) alternatives:

• Create two red arrows to each of those, coming from, respectively, the two nodes representing the two classes. The result is a bit messy with the three pairs of arrows crossing.
• Place the three rectangles representing the properties horizontally between the two class nodes and connect them with the arrows (ie, each property would receive a node from above and from under)
• Like now, but remove the OR node and just have a dot where the arrows meet.

None of these are good alternatives...

[TallTed]

@iherman — The revision does some things as I had requested, but I appear to have been unclear about others.

1. The direction of an arrow generally gives the way to read that arc, e.g., VerifiablePresentation rdfs:domain holder and VerifiablePresentation rdfs:domain verifiableCredential -- but these are obviously backwards. Most of those now reading backwards previously had diamonds at the ends which are now the back of the arrows. I had tried to suggest changing the diamonds to arrowheads, which I had meant to point the opposite direction from what is now present. Maybe that's now clearer?

2. As @msporny did, I noticed the OR circle. I think that's trying to say that "VerifiablePresentation OR VerifiableCredential could be Domain (a/k/a schema:domainIncludes VerifiablePresentation, VerifiableCredential) of termsOfUse, validFrom, validUntil" — but I don't understand why this would only apply to those three properties. To my mind (and I hope the text and all bear this out), most if not all pictured properties should have schema:domainIncludes VerifiablePresentation, VerifiableCredential. In any case, I would make all these arrows complete arcs, and do away with the OR as well as the vertical connectors now seen between VerifiablePresentation, OR, and VerifiableCredential.

3. The tiny-dots and tiny-spacing of the Domain arrows are TOO tiny. Better to make these longer dashes with bigger gaps than the current dashed lines of the Range arrows.

4. I would remove the contains label from that arrow, as it's now part of the key, and I would change Graph containment in the key to simply Contains, to match the other labels in the key.

5. I urge checking all contrast ratios between text and background colors, in both light mode and dark mode. This is key for accessibility review. I don't think they pay much attention to red-green or blue-yellow colorblindness concerns, but it would be good form to also avoid those, if possible.

6. Is JsonSchema Superclass of CredentialSchema, or is CredentialSchema Superclass of JsonSchema?

There are additional questions raised by the other diagram, but I think it probably better to get this one fixed, apply the fixes that apply to both to the other, and then dig further into the other.

[iherman]

@TallTed I will take care of the changes in time, just two remarks:

• For the OR node: the diagram reflects what is in the vocabulary which, on its turn, reflects the spec at least the way I understand it. The 'issuer', 'evidence', etc, properties are only mentioned in conjunction with a credential and not with a presentation. I am not the domain expert here, any change should come from the VCDM spec.
• Thanks for the contrast ratio checker pointer, I was looking for something like that. I am a bit worried that the double constraint of contrast ratio and dark mode will make the colored version of the diagram impossible, though. The way the dark modes are generated is a bit of a mystery to me and different from one browser, or from one plugin to the other (let alone the fact that, on Chromium at least, there are 5-6 alternatives to choose from for setting the dark mode...)

[iherman]

One more remark, @TallTed: per the vocabulary, CredentialSchema is a superclass of JsonSchema. Again, if that is incorrect, the vocabulary should be changed and the spec clearer...

[iherman]

Actually...

The direction of an arrow generally gives the way to read that arc, e.g., VerifiablePresentation rdfs:domain holder and VerifiablePresentation rdfs:domain verifiableCredential -- but these are obviously backwards

This may not be what you originally had in mind, but I am not sure it is really wrong as is. The current representation suggests that information "flows" from a class to another one via the property and, although I know this is not what a property does, it somehow fits the mental model for a domain and the range as far as I am concerned...

[dlongley]

@iherman,

Here's what the VCDM diagram looks like to me:

The borders are a little hard to make out.

[dlongley]

Here's what the data integrity diagram looks like to me:

[iherman]

@dlongley yes, that is in line with what I see. And, actually, just looking at the image makes it clear that the diagram would not pass the contrast ratio tests.

At this point, I am tempted to say that we should abandon my attempt to use background colors for the shape. It just not possible to solve the equation with contrast ratios, dark and light modes, and the unclear algorithms the browsers use to turn an SVG file prepared for light mode into dark mode.

We have other issues to discuss on the content; for the visual appearance we should keep to what is, for example, in the current version of the vocabulary file.

WDYT?

(Edited; see #175 (comment).)

[TallTed]

• For the OR node: the diagram reflects what is in the vocabulary which, on its turn, reflects the spec at least the way I understand it. The 'issuer', 'evidence', etc, properties are only mentioned in conjunction with a credential and not with a presentation. I am not the domain expert here, any change should come from the VCDM spec.

Ayie! It's doubly good we have these diagrams now, and that they were generated based-on/from the vocabs, which were generated based-on/from the spec — because this shows that the specs and the vocabs are wrong!

• Thanks for the contrast ratio checker pointer, I was looking for something like that. I am a bit worried that the double constraint of contrast ratio and dark mode will make the colored version of the diagram impossible, though. The way the dark modes are generated is a bit of a mystery to me and different from one browser, or from one plugin to the other (let alone the fact that, on Chromium at least, there are 5-6 alternatives to choose from for setting the dark mode...)

Yeah, dark mode is a dark art. As you've found, it can vary within a single app on a single OS. It also varies between different apps on one OS, and even more across different OS. Some do a partial color inversion; some do a full inversion; and others perform other tricks.

All of which means we can only really control the light mode, and test dark mode on whatever OS and/or browsers we each have, toward making some recommendations to readers for what settings to apply when reading our documents.

The direction of an arrow generally gives the way to read that arc, e.g., VerifiablePresentation rdfs:domain holder and VerifiablePresentation rdfs:domain verifiableCredential -- but these are obviously backwards

This may not be what you originally had in mind, but I am not sure it is really wrong as is. The current representation suggests that information "flows" from a class to another one via the property and, although I know this is not what a property does, it somehow fits the mental model for a domain and the range as far as I am concerned...

Properties have domain and range, which are either Classes or Datatypes.

Classes have neither domain nor range; they have Properties.

I have no argument with the perceived suggestion of information "flow," but if that's what's being diagrammed, it should be labeled as such.

[iherman]

• For the OR node: the diagram reflects what is in the vocabulary which, on its turn, reflects the spec at least the way I understand it. The 'issuer', 'evidence', etc, properties are only mentioned in conjunction with a credential and not with a presentation. I am not the domain expert here, any change should come from the VCDM spec.

Ayie! It's doubly good we have these diagrams now, and that they were generated based-on/from the vocabs, which were generated based-on/from the spec — because this shows that the specs and the vocabs are wrong!

Whether it is wrong or not, I do not know. I am in the humble position of translating the spec into the RDF world, and I do not claim to be a domain expert for VCs and VPs.

@TallTed I would prefer not to discuss this problem in this issue. Would you mind raising a separate issue in the VCDM repo and possibly discuss it there?