Added an SVG diagram of the vocabulary.

[iherman]

I have created an overview diagram for the vocabulary, and added to the vocabulary description.

As usual, the preview of this should be through

https://w3c.github.io/yml2vocab/previews/vcdm/vocabulary.html

The embedded diagram is in SVG (with all boxes acting as links, b.t.w.), and the SVG file can also be downloaded directly as

https://w3c.github.io/yml2vocab/previews/vcdm/vocabulary.svg

Note that this diagram anticipates the confidence method presence (ie, #1228) although the vocabulary text itself does not have it yet; that is because the branch is from the "main" branch (to avoid possible merge conflicts later). That also explains why respec issue warning on two missing links.

The original source of the diagram is at:

https://drive.google.com/file/d/1-kg7AzhahSzIwiIHeh5ANGJB_JK-kugs/view?usp=drive_link

which is a draw.io file. I tried to create/edit the SVG file directly using inkscape (and, actually, that program can be used to change/edit the resulting SVG file itself) but, alas!, the connecting line feature is buggy in inkscape, and it works perfectly well in draw.io. Sigh...

This is definitely not a pre-CR feature, but it definitely helps to possibly find problems in the vocabulary.

(I have a similar diagram coming up for the security vocabulary, but I wait until the PR storm is over for that spec before finalizing the diagram which, obviously, is much more complex.)

[OR13]

Wow pictures help...

I think the styling on reserved vs actual properties is probably too similar... And I wonder why we need:

https://www.w3.org/2018/credentials/#VerifiableCredentialGraph

^ assuming this is normative, why do implementers need to understand it, and how is it different from:

https://www.w3.org/2018/credentials/#VerifiableCredential

[TallTed]

Nice!

[iherman]

Wow pictures help...

I think the styling on reserved vs actual properties is probably too similar...

Ok. I could change the background color to a different shade... would that be better?

And I wonder why we need:

https://www.w3.org/2018/credentials/#VerifiableCredentialGraph

^ assuming this is normative, why do implementers need to understand it, and how is it different from:

https://www.w3.org/2018/credentials/#VerifiableCredential

How is it different from: the former is the "envelope" that contains the latter. Just as the envelope is not the same as what it contains, the VerifiableCredentialGraph is different from what it contains, i.e., a VerifiableCredential. This differentiation is crucial for, e.g., the usage of the RDFC 1.0 algorithm.

Why do implementers need to understand it: the question is which implementer you are talking about. I do not think there is a single answer. It is like asking whether implementers need to understand the exact mathematics behind b-spline curves, ray tracing or, closer to the topics, the RSA algorithm or elliptic curves. Clearly, those must be defined somewhere, but many implementers will ignore those details and use some existing tools as black boxes.

Please, let us not dive into this in this PR, however. The diagram illustrates what is in the vocabulary, it does not introduce anything new. If you want to follow up this discussion, there should be a separate issue for this.

[csarven]

Nice! Can never say no to eye candy in these spaces =)

Don't mean to hijack the thread here - and can move discussion elsewhere - on generating SVG diagrams from (cough) RDF, but is anyone aware of current tools to autogenerate the diagrams (with optional interactions)?

https://www.w3.org/RDF/Validator/ still offers an SVG view which is generally useful but not particularly pleasing, understandably, especially when there is more than a handful of triple statements.

For a category of diagrams that need to convey more meaning in the view beyond the raw underlying information, I understand that there needs to be more hands-on work. I was just hoping to see what's out there that closes that gap.

[iherman]

@csarven

Thannks.

Don't mean to hijack the thread here - and can move discussion elsewhere - on generating SVG diagrams from (cough) RDF, but is anyone aware of current tools to autogenerate the diagrams (with optional interactions)?

Yes, better move this discussion elsewhere. The short answer is that I did not find anything.

[OR13]

@iherman thanks for this PR.

Wow pictures help...
I think the styling on reserved vs actual properties is probably too similar...

Ok. I could change the background color to a different shade... would that be better?

Yes, I think that would be better.

And I wonder why we need:
https://www.w3.org/2018/credentials/#VerifiableCredentialGraph
^ assuming this is normative, why do implementers need to understand it, and how is it different from:
https://www.w3.org/2018/credentials/#VerifiableCredential

How is it different from: the former is the "envelope" that contains the latter. Just as the envelope is not the same as what it contains, the VerifiableCredentialGraph is different from what it contains, i.e., a VerifiableCredential. This differentiation is crucial for, e.g., the usage of the RDFC 1.0 algorithm.

Why do implementers need to understand it: the question is which implementer you are talking about. I do not think there is a single answer. It is like asking whether implementers need to understand the exact mathematics behind b-spline curves, ray tracing or, closer to the topics, the RSA algorithm or elliptic curves. Clearly, those must be defined somewhere, but many implementers will ignore those details and use some existing tools as black boxes.

Please, let us not dive into this in this PR, however. The diagram illustrates what is in the vocabulary, it does not introduce anything new. If you want to follow up this discussion, there should be a separate issue for this.

I filed #1240 to follow up on VerifiableCredentialGraph

[TallTed]

[@csarven] on generating SVG diagrams from (cough) RDF, but is anyone aware of current tools to autogenerate the diagrams (with optional interactions)?

Answering here because @iherman didn't find such, either --

I have been informed that ChatGPT can do such a thing. I have not tested it myself. You both seem motivated, so I leave you with the temptation.

[iherman]

The issue was discussed in a meeting on 2023-08-15

• no resolutions were taken

View the transcript

1.6. Added an SVG diagram of the vocabulary. (pr vc-data-model#1236)

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

Brent Zundel: next PR...1236 Added an SVG diagram of the vocabulary. only a couple of days old. could use more review. raised by Ivan.
… if folks have questions/concerns please jump on the queue.
… seems straightforward and non-controversial; don't expect it to sit out too long.

Manu Sporny: agree, PR seems fine.

[iherman]

@OR13

Wow pictures help...
I think the styling on reserved vs actual properties is probably too similar...

Ok. I could change the background color to a different shade... would that be better?

Yes, I think that would be better.

I have changed the background color for the reserved properties. For the preview, do not forget to clean the cache (I had to explicitly clear it to get the right version via github.io).

[seabass-labrax]

I'm generally in favour of these changes, but two things stand out:

1: could we not use SVGO to clean up the file? It's not bad in this case, but proper indentation makes looking at diffs easier

2: could we not also automate the removal of the height and width parameters? It is XML after all

[iherman]

@seabass-labrax,

Preamble: I would prefer to continue this discussion either by email or via a separate issue. The SVG diagram will change as the VCDM spec evolves, so this PR is really on

1. Is the general direction o.k. with the WG
2. Are there stylistic/content changes to be done to make it acceptable (like the comment of @OR13 on the representation of reserved properties).

And I would prefer to merge this PR as soon as everyone is o.k. with it, knowing that the SVG tool chain is still in flux. On that I am happy to chat with you every time :-)

---

Responding to your comments. First of all: thanks for the pointer to the svgo tool. I did not know about it; I have installed it and indeed looks great. I tried it on the output of draw.io, and it formatted the file nicely, which is great. Interestingly, by default it removed the width and height attributes from the top level svg element, so it also takes care of your second remark. It compressed some attributes (like the path expressions or the color settings) which is good, although not affecting the overall size of the file too much.

However, whether it would be used on long term or not still depends on the final tool chain. I use draw.io because it works fairly well for this type of diagrams and exports a very decent SVG (in contrast to google's draw, which exports everything in path statements, hiding all the structure and text). However, it still relies on its own format, which it exports to SVG. Inkscape, the other tool I was referring to, uses SVG as its core format, and it does that by adding its own attributes to the file. If I succeed in finding a way of navigating around the bugs of inkscape, and I would use that tool instead of draw.io, then svgo may not be a good idea because it may remove attributes that inkscape actually needs... Something to be checked.

[iherman]

For the records: the branch has been rebased to the latest main, ie, the initial remark:

Note that this diagram anticipates the confidence method presence (ie, #1228) although the vocabulary text itself does not have it yet; that is because the branch is from the "main" branch (to avoid possible merge conflicts later). That also explains why respec issue warning on two missing links.

is now moot.

[iherman]

@dlongley @msporny for the records: following w3c/vc-data-integrity#171 (comment) I have also updated the vcdm diagram for dark mode...

[dlongley]

Thanks, @iherman!

[msporny]

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

[TallTed]

Looking at https://w3c.github.io/yml2vocab/previews/vcdm/vocabulary.svg, the key does not match the diagram, at least for Reserved Property. Suggestions I made on the other diagram about the Domain and Range connectors also apply here.

[iherman]

Just for the records: I have made both changes on my machine, thanks. Needs some more testing; I will refresh the version on the repo at a later PR.