Change credentialSubject to subject

[OR13]

This would align with issuer not being credentialIssuer and holder not being credentialHolder.

[brentzundel]

For the previous conversations held on this topic, please refer to #207
and #480

[msporny]

-1, this would be a massive breaking change on a term that the WG spent months debating (years ago).

[TallTed]

-1 without significantly more justification.

Also, the issue title, "Change credentialSubject to subject" (an action and/or decision), ought to read "Should credentialSubject be changed to subject?" (a question and/or discussion topic).

[melvincarvalho]

@OR13 I agree the naming is potentially confusing. This has been discussed before though: #480 with two other terms credentialSubjectProperties and claims rejected.

[OR13]

"credentialSubject": {
          "@id": "https://www.w3.org/2018/credentials#credentialSubject",
          "@type": "@id"
        },

...

"subject": {
          "@id": "https://www.w3.org/2018/credentials#credentialSubject",
          "@type": "@id"
        },

How is it a breaking change? Nobody is issuing v2 context based VCs.

The justification is, subject is shorter, and aligns better with the other terms.... use use the term subject everywhere in the spec....

[OR13]

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "subject": {
          "@id": "https://www.w3.org/2018/credentials#credentialSubject",
          "@type": "@id"
        }
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "validFrom": "2023-05-09T22:25:23.652Z",
  "issuer": {
    "id": "did:example:123",
    "type": "Organization"
  },
  "subject": {
    "id": "did:example:456",
    "type": "Organization"
  }
}

<did:example:123> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/ns/credentials/issuer-dependent#Organization> .
<did:example:456> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/ns/credentials/issuer-dependent#Organization> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
_:c14n0 <https://www.w3.org/2018/credentials#credentialSubject> <did:example:456> .
_:c14n0 <https://www.w3.org/2018/credentials#issuer> <did:example:123> .
_:c14n0 <https://www.w3.org/2018/credentials#validFrom> "2023-05-09T22:25:23.652Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

[martyr280]

-1 this is a breaking change for other standards that have aligned with VC 2: https://1edtech.github.io/ComprehensiveLearnerRecord/docs/clr_v2p0.html
https://1edtech.github.io/openbadges-specification/ob_v3p0.html

[brentzundel]

I do not have an opinion on whether credentialSubject should be changed to subject
I do not care what it is called at this point and the thought of re-entering the conversation about what to call it does not appeal to me at all.

That said, the fact that this may represent a breaking change is not a valid reason to block, though it certainly is a concern that must be examined.
Our charter explicitly allows for breaking changes.

[decentralgabe]

Whether or not this is a breaking change is completely irrelevant. We're building a v2, which by definition, includes breaking changes. The issue must be evaluated based on its merit alone.

I believe this change would reduce confusion and clarify how the property is intended to be used, so I'm supportive of it.

[jandrieu]

Whether or not this is a breaking change is completely irrelevant. We're building a v2, which by definition, includes breaking changes. The issue must be evaluated based on its merit alone.

Respectfully, the fact that it is a breaking change has everything to do with the burden of consensus. As a breaking change, you would need to establish consensus in order to change the existing specification. Just because some folks like the idea does not make it a change that the working group adopts.

I'll fight for your right to have your proposal heard, but you still have to convince enough participants to call it consensus.

Since your change basically throws JSON-LD out the window, I don't believe you are going to get consensus.

[melvincarvalho]

Since your change basically throws JSON-LD out the window

Could you elaborate on why this throws JSON-LD out the window. Or which specific proposal does.

[melvincarvalho]

-1 this is a breaking change for other standards that have aligned with VC 2: https://1edtech.github.io/ComprehensiveLearnerRecord/docs/clr_v2p0.html https://1edtech.github.io/openbadges-specification/ob_v3p0.html

Appreciating your input, I'd like to highlight a specific point from the Terminology section of the quoted spec:

Claim: A statement about the Credential Subject. A claim may include associated evidence, results, or other metadata regarding a specific achievement, skill or assertion.

This suggests that the term "claim" could indeed be a fitting and intuitive choice here.

[melvincarvalho]

I do not have an opinion on whether credentialSubject should be changed to subject I do not care what it is called at this point and the thought of re-entering the conversation about what to call it does not appeal to me at all.

That said, the fact that this may represent a breaking change is not a valid reason to block, though it certainly is a concern that must be examined. Our charter explicitly allows for breaking changes.

Thank you for bringing forward this balanced perspective.

Indeed, the potential of breaking changes should not serve as an absolute deterrent if they fall within the purview of our charter.

Observing the composition of specification editors, it appears that we have an approximately equal representation from both RDF and JSON perspectives, which I find to be quite healthy and beneficial for our collaborative work.

Given the scope of the potential changes, it might be feasible to incorporate some alterations in term names. We might be able to navigate around these changes using versioning of the @context. I have also recently opened an issue regarding Arrays of Arrays, which might necessitate alignment with Nostr Tags.

While I might be mistaken, I genuinely believe we need to carefully consider how we can allow JSON and RDF to coexist with this technology. This might involve a degree of restructuring, the extent of which is yet to be determined.

[jandrieu]

Since your change basically throws JSON-LD out the window

Could you elaborate on why this throws JSON-LD out the window. Or which specific proposal does.

You are correct. I think I was actually referring more to the arguments in #1130 which would both remove the "id" property and rename "credentialSubject".

Whether or not we change the key "credentialSubject" to "subject" is separate from whether or not we remove the "id" property. So, I am happy to withdraw that argument.

In fact, I'm open to renaming it to "subject" although it would be a bit of a pain for existing implementations. We can probably mitigate that entirely if we map "credentialSubject" and "subject" to the same definition in the JSONLD @context. We actually did this in the Learner and Employment Record Wrapper as "credential" was felt to have too strong of an affinity with very different notions in the educational world. However, we probably just want a clean v2.0 rather than use such a mapping so both terms are valid, which will likely be confusing from a non-disambiguated JSON perspective.

That said, I can point out to why it isn't "claim", on two fronts.

First, we had a catalytic moment at a Rebooting the Web of Trust workshop, where significant incubation work on DIDs and VCs occurred. A respected and experienced collaborator spent three days with the rest of the team imagining that "Verifiable Claims" verified certain facts, but VCs as envisioned were only verifying authenticity. This is why VCs are Verifiable Credentials instead of Verifiable Claims. Hence, the language shift from "claim" to "credential" which influenced the term "credentialSubject"

Second, the structure of JSON-LD is such that properties other than "id" are predicates about the subject identified by the "id" in the same JSON node. In this case, "credentialSubject" is a predicate on the root object, so the statement involved is "this VC (known by the VC's id) has credentitalSubjects that are [members of the array]".

Then, for each member of that array, the "id" field identifies the subject of that credential, with predicates (and objects) that are the claims. So each array member reads as issuer assertions that "entity with ID of 'id' PREDICATE OBJECT" where PREDICATE and OBJECT are the keys and values of the properties of that array member, e.g., "did:ex:abc name 'Joe Andrieu'" is the credential's RDF triple in

  "credentialSubject": [{
    "id" : "did:ex:abc",
    "name" : "Joe Andrieu" }]

We can also read that as "Joe Andrieu is the name of one of the subjects of the VC; they are referred to, in this VC, with the identifier did:ex:abc." Presumably we might have other statements about that identifier, which are taken to be about the person/thing with the name "Joe Andrieu".

Not sure if that's clarifying, but the point is that the "id" of the array member is the identifier of the subject of that set of claims, which are expressed as the predicates and objects about that subject.

If we replaced "credentialSubject" with "claims", then the semantics would be that the array members are claims and statements about those claims, instead of credential subjects and statements about those subjects. That would mean the ids of those array members identify the specific claim, and the predicates and objects are about the claim, rather than about the subject.

That said, I don't think it'd be a big stretch to switch from "credentialSubject" to "subject" despite my earlier argument to the contrary. However, switching that to "claims" would not align with the JSON-LD semantics (even though I realize non-disambiguated JSON processors could interpret the property in a valid way if they understand the spec.).

[TallTed]

@melvincarvalho — In #1128 (comment) ...
and
@jandrieu — In #1128 (comment) ...

Please edit your comments (again), adding code fences around @context (as `@context`) so that GitHub user doesn't get dragged into yet another of our threads, without opting in.

[paulfdietrich]

credentialStatus follows this same convention as credentialSubject.

[iherman]

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

• no resolutions were taken

View the transcript

5.3. Change credentialSubject to subject (issue vc-data-model#1128)

See github issue vc-data-model#1128.

Brent Zundel: change credentialSubject to subject.
… change credential subject to subject.

Manu Sporny: strong -1 to this, there is no need to break things... we have URLs locked in.
… its what we have used for a long time.
… its pre CR, but I propose we close it.

Phillip Long: +1 to closing this one.

Dave Longley: +1 to close and not spend time on it.

Gabe Cohen: the term has caused a lot of confusion, I am not swayed by breaking changes before CR.
… I think we should consider it.

Manu Sporny: people have been using the term for years.
… v2 would be different from v1.

Gabe Cohen: we have "broken" expirationDate.

Manu Sporny: the suggestion that change the name will fix confusion is unfounded.
… people will be confused regardless, I don't find the argument compelling.

Phillip Long: Also this is terminology was used (CredentialSubject) is used in the 1Edtech VC compatible standards for OBv3 and CLRv2.

Manu Sporny: seems not worth it to fix it.

Orie Steele: We made several breaking changes between v1 and v2, in v1 issuanceDate -> validFrom -- that's fundamental to the security property, all of the claims are already being adjusted by a breaking change, regarding time, most important time of all cryptography. Not swayed by argument that we shouldn't break backwards compatibility.
… We use holder, but we use credential subject, I disagree, I think people will find it more intuitive than what we have.

Brent Zundel: I have made my opinions clear, I have no desire to have this conversation again.
… charter says we can make breaking changes.
… I have made my opinions clear in the issue -- I have no desire to have this conversation again. I will note that our charter allows us to come to consensus aruond breaking changes. My only response to Manu is "people expressing confusion around credentialSubject", they say "why didn't you name it subject" -- anecdotal, having been repeated numerous times, havinv said that, happy to close this issue w/ no action.
… if people are saying they are confused... they say.. why didn't you name it "subject"... anecdotal, but I have heard this... before.

Joe Andrieu: I wanted to talk about this.
… feels like we are allowed to make breaking changes with consensus.
… we can't make a breaking change without consensus.
… this is confusion, not a fundamental security problem.

Dave Longley: similar to what joes said... people have opinions on if a change is worth it... some security changes are worth it...
… changes in other areas, might impact people beyond developers.

Ivan Herman: not taking a side, but fact... In our agreement old URL-s do not disappear, so credentialSubject will become deprecated and subject will come in as a new term (with both in their own URL-s).
… we can't remove the URL.

Philip Long: both the standards we use for edu, have credentialSubject in their spec.

Brent Zundel: I suggest this be labeled as pending close, rather than before CR.
… I don't see possibility of consensus here.

[brentzundel]

No objections raised since being marked pending close, closing.