Improve the explanation of using graphs in VCDM

[iherman]

This PR is a replacement for #1321, following up on #1321 (comment). Globally, it takes a more thorough approach and also attempts to provide a more complete solution to #1248 and #1318.

What it does is:

• brings to the spec the RDF terms "named graphs" and "default graph", although in simpler formats
• Figure 6 and Figure 8 both fully exploit these terms, both in the diagram and in the preceding informal description
• the proof property has now a proper definition of what is being proven, i.e., which claims; this is done by using the graph terminology.

All this required some more, relatively minor changes on the text for a better coherence. The most visible change is that what used to be §4.11.1 Verifiable Credential Graphs has been moved to the top level of the Basic Concepts section, and is now known as §4.9 (with some minor changes).

(As an aside, the PR also puts the sources of the new versions of Figures 6 and 8 to the repository, using the drawio format. Better have all these at the same place.)

For reviewers: the automatic preview below does not work properly because it does not process included files (e.g., the terminology section or the diagrams). You can use these pointers instead:

• Preview
• Diff (take a deep breath when using this, and be patient: there is no caching of the processing behind this, i.e., respec generates a final form, which is followed by an HTML diff on two fairly large documents…)

---

Preview | Diff

[iherman]

I marked it as post-CR, insofar as the PR does not introduce any normative change, just tightens up the specification (e.g., for the usage of the proof property). I was hesitating, though; I think it would be way better to get this done before going to CR.

I leave the decision to the chairs. @brentzundel @Sakurann

[dlongley]

A few suggestions, then I'm supportive. Thanks!

[TallTed]

• [@iherman] brings to the spec the RDF terms "named graphs" and "default graph", although in simpler formats

I am concerned that neither of the things now called "the default graph" in the new diagrams actually is "the default graph" in any scenario. If anything, I would expect each of these instead to be another "named graph". (In at least one RDF quadstore, the UNION MERGE of all the graphs it holds is "the default graph".)

At minimum, I think some discussion of how and why these come to be "the default graph" here is necessary, certainly in the text neighboring, and possibly within, each diagram. Possibly the the default graph label should just be changed to a named graph in parallel to the other named graph(s) in each diagram.

[TallTed]

I'll have more, but the direction I go in from here will depend on the outcome of the comments already made, so I'll wait for the more...

[iherman]

Thanks for your comments, @TallTed.

As for:

I am concerned that neither of the things now called "the default graph" in the new diagrams actually is "the default graph" in any scenario. If anything, I would expect each of these instead to be another "named graph". (In at least one RDF quadstore, the UNION of all the graphs it holds is "the default graph".)

I use the term "default graph" in the way it is defined in the RDF 1.1 concepts spec. This is in line with the way the term is used in JSON-LD 1.1 or N-Quads (both are relevant to us). The succinct way N-Quads describes the quads in a default graph is (when defining a simple quad term):
"The graph label IRI can be omitted, in which case the triples are considered part of the default graph of the RDF dataset."

I'm afraid the usage of the term "default graph" in that quadstore may not be aligned with the RDF specs, but I cannot judge it.

At minimum, I think some discussion of how and why these come to be "the default graph" here is necessary, certainly in the text neighboring, and possibly within, each diagram.

I've not brought in anything new. I just describe, in more precise terms, what is already implicitly defined by the spec. E.g., let us look at Example 5 in the spec, which is the case of a "simple" credential (i.e., no presentation). The same dataset in N-Quads can be seen on the JSON-LD playground example. The terms that are part of the "core" of the credentials are all quads without a graph label, i.e., part of the default graph of the dataset per the N-Quads specification.

Possibly the the default graph label should just be changed to a named graph in parallel to the other named graph(s) in each diagram.

I don't think so. As the aforementioned playground example shows, those quads are different; there is also a real named graph in that example (the proof graph), and the quads all have an explicit graph label _:b0. If the goal was to turn what is now the default graph into a genuine named graph, we would have to have a different (and more complicated) JSON-LD @context, if not a different JSON-LD structure altogether. It would not reflect today's specification.

B.t.w., to make things complete and coherent I did make some changes in other places of the spec making use of the default graph/named graph terminology. See, for example, the section on verifiable credential graphs or, primarily, the definition of the proof property in §4.10 and §4.12. I believe the specification was incomplete with regard to the proof property, and that addition was necessary (this is, in my view, the core of the discussion in #1248).

I believe the real goal of all this PR is the issue around the proof property's definition (i.e., the incompleteness thereof). I think introducing the default graph/named graph terminology into the spec is the simplest way of doing that.

[TallTed]

Perhaps there is a way to qualify "the default graph" so it doesn't appear to be "the only default graph", but rather is "the default graph of this dataset"? I will think further on this. I raise the question here so others who might have good ideas might voice them.

I realized that I mis-typed above, where I said '(In at least one RDF quadstore, the UNION of all the graphs it holds is "the default graph".)' It's not the UNION, it's the MERGE.

[iherman]

Perhaps there is a way to qualify "the default graph" so it doesn't appear to be "the only default graph", but rather is "the default graph of this dataset"? I will think further on this. I raise the question here so others who might have good ideas might voice them.

I take your point, and I am happy to change this. The problem is that "the default graph of this dataset" is a bit of a mouthful. "Dataset default graph"? "Local default graph"?

(I am not even sure the VCDM spec uses the term "dataset", so we may not want to go there. Hence the "local".)

[OR13]

my understanding is that multiple proofs are allowed here, and that in the case of BBS, the secure these information graphs in very different ways.

[iherman]

@OR13 I have no opinion on this, and I would prefer if this was raised and discussed as a separate issue. The text in this version simply reused what is currently in the official draft.

Could you raise a separate issue and mark this conversation as resolved?

[decentralgabe]

Just a comment - not blocking - it would be great to have a similar set of graphics/text that highlight a graph VC with a vc-jose-cose based proof

[OR13]

I feel that proof remains a property of data integrity, and would prefer to see normative guidance related to data integrity done in the data integrity specification.

[iherman]

@OR13 similar comment as above: I've just reused the current draft, and I do not have a strong opinion either way. Would it be possible to move this into a separate issue and not hold up this one on this?

[iherman]

Just a comment - not blocking - it would be great to have a similar set of graphics/text that highlight a graph VC with a vc-jose-cose based proof

@decentralgabe I agree with that, and I am also happy looking into this, but I would prefer to do that once this PR is merged. Truth must be said, I am not really deeply familiar with the JWT world, so I do not know whether there is an accepted "style" of diagrams. Do you know?

[decentralgabe]

@iherman no problem if you want to take a shot at it after this PR is merged that would be greatly appreciated! Perhaps @selfissued knows if there's prior art on such diagrams, if not, I think a similar form to what you've already done would work nicely.

[iherman]

The issue was discussed in a meeting on 2023-11-01

• no resolutions were taken

View the transcript

1.2. Improve the explanation of using graphs in VCDM (pr vc-data-model#1326)

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

Ivan Herman: There is one PR 1326 last week that is labeled as Post-CR, but I wonder whether this is not a Pre-CR PR. It does include a more precise and normative definition on which part of a credential representation the proof property applies to.

Brent Zundel: I am happy to make that change.

Ivan Herman: Maybe Dave Manu and Ted have already looked at it.

Manu Sporny: The PR needs to be re-based. There are a whole bunch of changes which makes it difficult to review.

Ivan Herman: I put a separate preview into the instance.

Manu Sporny: I can try to rebase to see which normative language is modified.

Ivan Herman: Extremely grateful if you did that.

Manu Sporny: Do you which normative text?

Ivan Herman: There is a terminology change and the definition of the proof property both for a credential and a presentation.

Manu Sporny: we need to deal with this pre-CR.

Ivan Herman: As an answer to Henry raised issue. So that issue can be closed if this PR gets accepted.

Brent Zundel: I will change from Post-CR to Pre-CR. Only outstanding requests for changes are from Ted. Welcome to speak on changes.

Ted Thibodeau Jr.: My concern is the reference to the default graph. Its used for the first time in this document. I don't think it has the meaning intended.

Ivan Herman: I think we do disagree on that.

Brent Zundel: This conversation can continue in the PR. Manu has agreed to rebase and cleanup.

[msporny]

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