Clarify section on verifiable credential graph

[andresuribe87]

From https://github.com/w3c/vc-data-model/pull/1358#issuecomment-1831580248 it's become evident that we need to further clarify what a "verifiable credential graph" is. Excerpt from the conversation is paster below.

I've read section 9 now multiple times, and I'm still not able to define what a "verifiable credential graph" is. That section is introducing a concept, but it's not defining it. Could you explain further what it is? Happy to open a separate issue to elaborate on this further.

The formal definition is really in the RDF spec, so I am forced to go back to the RDF world. Hopefully, in this case, this helps. And my apologies for the verbosity of my answer.

The reason we are talking about named graphs in RDF is because the concept is, basically, to have a graph with its own, distinct identity, i.e., a name which, in the RDF world, is a URL. To use a somewhat different syntax, one could have something like:

<https://example.org/name1> {
    <https://> type  <Verifiable Credential>;
               issuer <https://university.example/issuers/565049>;
               ...
}

<https://example.org/name2> {
    <https://> type  <Verifiable Credential>;
               issuer <https://university.example/issuers/01234>;
               ...
}

We have here two, distinct credentials, i.e., credential graphs. If I use the URL https://example.org/name1 I know I refer to the terms in the first block and not in the second. I.e., if I have to create a signature for name1, then I know which terms I have to consider: those that are in the first graph and not in the second. That "separation" is what is described in section 9.

What muddles the waters a bit is that, as it is the case for RDF in general, I can also use a blank node instead of a clear URL, which is something like saying "we know there is a distinct identifier but we do not care what it is". (It is an "existential term" in logic). So I could have:

_:1234 {
    <https://> type  <Verifiable Credential>;
               issuer <https://university.example/issuers/565049>;
               ...
}

where _:... is the syntax used in most of the RDF serializations for blank nodes. The choice of _:1234 is arbitrary: an RDF implementation can choose any term there, just be careful that distinct graphs should have distinct bnode identifiers. (This does create practical problems when merging two different graph sets: the bnodes have to be renamed to ensure unicity.)

The way the JSON-LD @context (for VC-s) is defined is to instruct the JSON-LD processor to generate something like this for the verifiableCredential term:

<id for the VP> verifiableCredential _:1234 .
_:1234 {
     <https://> type  <Verifiable Credential>;
               issuer <https://university.example/issuers/565049>;
               ...
}

I.e., only blank nodes are used. If there are more than one credentials, then each gets its own blank node, ie, they are all mutually separated.

Does this help a bit?

And yes, I believe any further clarification should be subject of a separate issue...

[msporny]

@andresuribe87 Can you please be more specific about the sort of "clarification" you're seeking? While everything @iherman says above is accurate, I'm not sure it helps readers.

IOW, we're re-explaining concepts that other specifications explain (like RDF Concepts), or the details are not pertinent to the understanding of implementing VCs. I don't know if you're requesting a few sentences of clarification, and if so, what specifically?

Or you're requesting the depth of explanation @iherman provided to you, which I don't agree is helpful to put in the specification for at least two reasons: 1) those concepts are covered in other specifications; duplicating content is generally frowned upon, and 2) it's not clear how these clarifications impact anyone using or implementing the system?

[andresuribe87]

@msporny here are some more concrete clarifications that I think are the minimum necessary.

Within the section 4.9, state that "An externally secured verifiable credential is not considered a verifiable credential graph. In general, a URL is only considered a verifiable graph when dereferencing the value results in a conformant document according to this data model.".

Within the definition of Presentations, in the verifiableCredential property, state that "The values of the array MUST NOT be a verifiable credential secured with an external proof.".

[OR13]

related https://github.com/w3c/vc-data-model/pull/1372 https://github.com/w3c/vc-data-model/pull/1358

[OR13]

Seems like making it clear that IRI is included in the range of verifiableCredential would be all that is needed.

[iherman]

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

• no resolutions were taken

View the transcript

#### 2.5. Clarify section on verifiable credential graph (issue vc-data-model#1365) _See github issue [vc-data-model#1365](https://github.com/w3c/vc-data-model/issues/1365)._ > *Manu Sporny:* (but not support for ignoring the fact that it's not clear to readers that vc-jose-cose is THE specification that outlines how to use SD-JWT with VCDM). **Brent Zundel:** andres, is this before or post-CR? **Andres Uribe:** I think this should be before CR. **Brent Zundel:** Who's willing to be assigned? **Manu Sporny:** I am willing to be assigned.

[msporny]

@andresuribe87 wrote:

@msporny here are some more concrete clarifications that I think are the minimum necessary.

Great, thank you for the concrete suggestions, very helpful.

I'm going to get super pedantic here because it'll affect the language that's written. To be clear, I want to write some variation of the language you suggested as long as it's accurate:

Within the section 4.9, state that "An externally secured verifiable credential is not considered a verifiable credential graph.

While an externally secured VC couldn't be directly considered to be a separate graph (in most cases), it could be expressed in a separate graph, which is what PR #1379 does.

There is probably also some language that we could create where one could pre/post-process it and /interpret/ it as a verifiable credential graph... but that would just add complexity for the sake of academic purity. I'm not sure that language would benefit the vast majority of VC authors.

In general, a URL is only considered a verifiable graph when dereferencing the value results in a conformant document according to this data model.".

This sounds true on the surface... I'm trying to think about how this might be mis-interpreted. Developers might think that they can start stuffing URLs in the verifiableCredential property, which they can't (and doing so wouldn't be very useful w/o cryptographic digest information on the contents).

Within the definition of Presentations, in the verifiableCredential property, state that "The values of the array MUST NOT be a verifiable credential secured with an external proof.".

This is true, but then people might think they can't do what's in PR #1379.

I guess I'm trying to figure out if PR #1379 changes any of your suggestions? I think what you're trying to say is "ban the use of pure strings and URLs in the verifiableCredential array so that people don't continue to keep getting confused about it"?

[andresuribe87]

1379 does not change my suggestions. It helps provide clarify, but I don't think it's enough.

I think what you're trying to say is "ban the use of pure strings and URLs in the verifiableCredential array so that people don't continue to keep getting confused about it"?

Yes. That's it. I want to provide clarity to implementers on what is and what isn't allowed as a value of the verifiableCredential property.

[msporny]

Ok, I can change #1379 to include that language. Something to the effect of: "For the avoidance of doubt, you can't have these values..." or, as @dlongley suggested on the call, "MUST be an object and can't be something else, such as..."...

[TallTed]

"MUST be an object; i.e., it can't be any non-object, particularly including..."

[iherman]

The issue was discussed in a meeting on 2023-12-13

• no resolutions were taken

View the transcript

#### 2.12. Clarify section on verifiable credential graph (issue vc-data-model#1365) _See github issue [vc-data-model#1365](https://github.com/w3c/vc-data-model/issues/1365)._ **Brent Zundel:** clarify section of verifiable credential graph. … what needs to change to address this? **Manu Sporny:** there is a clear concern, which i think I can address. … for the avoidance of doubt, the following values are not allowed in a `verifiableCredential`. … I list raw text strings, and URLs. … it has to be an object of some kind that creates that graph structure. … and I won't make it exhaustive... its strange to point out, what you cannot put in the field. > *Dave Longley:* "MUST be an object and can't be something else, such as...". > *Andres Uribe:* works for me, thanks manu! **Brent Zundel:** do you want to mix that into 1379? **Manu Sporny:** seems to make sense to put it in 1379. _See github pull request [vc-data-model#1379](https://github.com/w3c/vc-data-model/pull/1379)._ **Brent Zundel:** then it will address that issue as well. … not hearing anyone opposed to this path.

[msporny]

PR #1390 has been raised to address this issue. This issue will be closed when PR #1390 has been merged.

[iherman]

The issue was discussed in a meeting on 2023-12-20

• no resolutions were taken

View the transcript

#### 4.2. Clarify section on verifiable credential graph (issue vc-data-model#1365) _See github issue [vc-data-model#1365](https://github.com/w3c/vc-data-model/issues/1365)._ **Brent Zundel:** 1365 Clarify section on VC graph. Has PR 1390. Status: wide array of approvals, some ed. Most likely to be merged soon. Then will close.

[msporny]

PR #1390 has been merged, closing.