Avoiding confusion by renaming 'credentialSubject'

[RieksJ]

In section 4.4, the term 'credentialSubject' is defined, suggesting a relation between the credential in which it is included and a 'Subject', i.e. an entity about which claims are made. However, the credentialSubject section contains a list of claims, rather than a (or more) subject(s).

This issue calls for renaming 'credentialSubject', and provides the following suggestions

• 'credentialSubjectProperties'
• 'claims'

[brentzundel]

+1 to claims

[awoie]

+1 to claims

[ken-ebert]

+1 to claims

[jandrieu]

+1 to claims

[David-Chadwick]

We have been round this one many times, and the reason it was changed from claims is that the ID is not the iD of the claim, but the ID of the subject. So the object needs to have subject somewhere in its name.

[brentzundel]

@David-Chadwick, I agree that it makes sense to those of in the group to call it the credentialSubject for the reasons you mentioned.
This doesn't change the fact that it is confusing for others. We say that a verifiable credential contains claims, then show a data model that (for valid, yet pedantic reasons) has a credentialSubject property. We then have to explain that that's where claims should go, and then explain why the property is not just called "claims," since that is what a verifiable credential supposedly contains.

Rather than requiring this educational moment every time someone new looks at the data model, I support the proposal to change credentialSubject back to claims.

[jandrieu]

I think there was also confusion about the embedded graph container, making the RDF subject of the claims confusing. We have examples in the focal use cases where there are multiple subjects, for example in a birth certificate and marriage certificate.

"CredentialSubject" strongly suggests that there is always single subject of the credential, but that's demonstrably untrue.

@dlongley could you provide an example of how an issuer would construct a VC with multiple subjects?

I scanned the current spec, but only found examples such as the following:

...
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
...

Am I correct that simply replacing that single object with an array works?

  "credentialSubject": [{
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    },{
    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
    "parent": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "type": "Mother"
    }]

If that's correct, I believe @David-Chadwick's issue isn't with CredentialSubject but with the id.

The example says, in effect, that the subject of the first claim is the mother of the subject of the second claim.

In this case, I think the best we can do is explain clearly that "id" is the "id" of the subject of just the each claim. That's something we need to clarify, but my understanding is that the way JSON-LD works the "id" field is necessary. Or is it possible to change the "id" field to "claimSubject"? That's the semantic meaning in this situation. Can we make it explicit?

In any case, when you see the multi-subject "CredentialSubject", it doesn't make sense.

[David-Chadwick]

The way out of this dilemma is to have a claims object that contains within it one or more credentialSubject objects. Then it is clear that the VC contains claims, and that the ID is that of the subject. Eg.

"claims": [
 "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    },
"credentialSubject": {
    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
    "parent": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "type": "Mother"
    }
]
...

[jandrieu]

That's not bad, except I believe the "credentialSubject" is actually a "claimSubject" in your example.

[talltree]

I like it too. And with that context, wouldn't just "Subject" work as the name?

…

On Wed, Apr 3, 2019 at 7:17 AM Joe Andrieu ***@***.***> wrote: That's not bad, except I believe the "credentialSubject" is actually a "claimSubject" in your example. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#480 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ADLkTbh3PPL8HF2VN9ODFBEYubXA5nBwks5vdLgBgaJpZM4cNFRu> .

[jandrieu]

Maybe. I think folks get wrapped around the singular subject, thinking a credential can only have one subject. ClaimSubject focuses it nicely on this particular claim, gently inviting credentials that have claims about many subjects.

[msporny]

I will note that the conversation in this issue is all over the place and is pretty classic bike shedding during the Candidate Recommendation phase (typically, a terrible, horrible time to bike shed core properties in the specification since implementers are already busy implementing using the properties that are currently being bikeshedded in this issue).

-1 to anything plural (claims, subjects, properties, etc.). schema.org made that mistake years ago and has been busy playing whack-a-mole to remove all the plural properties. The same goes for the Web Payments specification. We have over a decade of experience now naming properties that will go back-and-forth between JSON and RDF and the best practice is to NOT use plural form.

-1 to claim (and I say this as the person that initially put that in the specification). You are expressing "one or more credential subjects". The language in the spec may lead people to a different conclusion, and if it does, we should fix that specification text (not change the property to something that it's not).

I also note that the WG has many more things to worry about at present than bike shedding a name. Can we please just drop this issue and focus on things that are a better use of the WGs time? I'm concerned that this issue is going to consume a lot of time that should be spent doing things like getting the VC extension registry up and running, working on use case finalization, etc.

@RieksJ -- perhaps there is some non-normative text that you would like added to the specification to explain why the "credentialSubject" property is named what it is named?

[RieksJ]

I appreciate that there is a lot to do. However, I don't consider heavy workloads as a valid argument for deciding to skip issues in a standardization process. I would support it as an argument to postpone the transition to a next phase, because standards should be solid. And in particular, discussions about what might seem to be details should be done carefully, because that's where the devils tend to be, and in my experience as expert in ISO SC27/JTC1, fixing standards is much harder once they're out there.

Note that this is not an argument to discuss every detail - relevance of the discussion must be shown first. The relevance of this issue is to prevent confusion and misinterpretation by readers (standards should be unambigous and clear). The term 'credentialSubject' suggests that there is a relation between the credential and a single subject (which isn't there). But even if we say that this standard uses singulars, then 'credentialSubject' still has the word 'Subject', and that doesn't cover its payload (which is a set of Claims). It is like having a sign on the door of a restroom that says 'Chair'.

To me, it is relevant that standards do not have these kinds of things in them. But if there is a consensus that preventing such confusion is irrelevant, then I have no problems with closing this issue, because that's how standardization works.

@msporny: I don't think it is up to me to elaborate on why 'credentialSubject' is named as it is, because I did not invent that name (and I wouldn't have named it that in the first place for the same reasons I created this issue).

[dlongley]

@RieksJ,

Using a relationship named credentialSubject makes sense in the data model, particularly if you think of the data as a graph, which is what we're modeling.

A credential is a node in this graph. If you want to represent something about this node, you create a link emanating out from the credential node that connects to another node in the graph. For example, if you want to identify the issuer of the credential, you can create a link named issuer and use it to connect the credential node to another node that represents the issuer. If you want to say that a credential is about a subject, you can link the credential node with a link called credentialSubject that connects to the subject node. If you want to say that the credential is about yet another subject, you create yet another link called credentialSubject and connect that to that other subject.

You can see from this why using plural names for links doesn't make much sense. The links identify the relationship between two nodes in a graph; if you want to say one node has the same kind of relationship with two other nodes, you add two links of the same name to the graph, each connecting to one of the other nodes.

Now, if you want to say things about any one of those subjects, you repeat this process -- you link the subject node you want to say something about to another node through another relationship. For example, you could create a link called alumniOf that connects the subject node to a node that represents a literal string value of Example University.

In the JSON and JSON-LD syntax, links are represented as JSON keys, where the JSON key id is a special key that is used as an identifier for a node. Nodes are represented as JSON objects or, if a node represents a literal value, it can be a string, number, boolean, etc. Other syntaxes may do something different while still being compliant with the data model.

At a high level, the entire graph is therefore comprised of sentences that include a "subject" (a node), a "property" (a link), and an "object" (another node/literal value). These sentences are the "claims" -- and in our model they are understood to have been made by the entity identified as the "issuer".

We have a picture of a graph showing how this works in the data model: