Non-normative changes from Jeffrey Yasskin's review

[msporny]

This issue tracks the NON-normative changes requested from @jyasskin's review (issue #1285) of the VC v2.0 specification:

1. Introduction

• Use property terminology throughout entire specification.

1.1 What is a Verifiable Credential?

• Specify which properties exist on a VC.

1.3 Use Cases and Requirements

• Use non-normative wording instead of "should".

3.2 Credentials

• Mention quoting and verifiable credential graph.

4.1 Getting Started

• Make section non-normative.

4.2 Contexts

• Use better language to specify ordered sets.
• Remove redundant "This specification requires for a @context property to be present;" statement.
• Rewrite paragraph that contains "Verifiable credentials and verifiable presentations have many attributes and values that are identified by URLs" -- re-write paragraph to introduce contexts in a different way.

4.3 Identifiers

• Merge the id and the "If the id property is present:" block.

4.4 Types

• Clarify that you can use a full URL, or you can use a JSON-LD term that maps to a URL. That is, you can't use a number, string, object, etc.
• Point to VC-SPECS for some examples of "A valid proof type".
• Clean up and reword section containing "This enables implementers to rely on values associated with the type property".

5.1 Lifecycle Details

• Add text on what a "verifiable data registry" and how it is used.
• Include operations that can be performed in ecosystem.

5.2 Trust Model

• Wordsmith statements to say is that the verifier trusts the issuer to make the statements it's making after verification has been performed.
• Elaborate on why entities trust/depend on verifiable data registry.
• Explain why holder trusts the issuer.
• Say something about the verifier choosing the issuers they want to trust.

5.3.1 Semantic Interoperability

• "is expected to be published" diffuses responsibility. Use active voice.

5.4 Integrity of Related Resources

• Editorial clean-up and simplification of normative statements to match other sections.

5.5 Refreshing

• Add some text in https://w3c.github.io/vc-data-model/#presentations to say that issuers and verifiers can use presentations to prove who they are to a holder by providing their own credentials via a presentation.

5.11 Ecosystem Compatibility

• Clarify intent of "rules" in section to be guidance to specification authors that desire compatability.

6.3 Proof Formats

• Change "The sections detailing" to "The specifications detailing".

7. Privacy Considerations

• "Implementers of software utilized by holders"

7.3 Personally Identifiable Information

• Update "Implementers" to "Implementers of software utilized by holders"
• Say that people should assume a VC will leak PII unless the credential and securing mechanism is designed specifically to avoid correlation (and there are credential types designed specifically for this purpose).

7.4 Identifier-Based Correlation

• Specify that proof specifications are responsible for avoiding identifier-based correlation.

7.5 Signature-Based Correlation

• Specify who is responsible for signature-based correlation and update section to match modern practices.

7.6 Long-Lived Identifier-Based Correlation

• Fold this section into the "Identifier-based Correlation" section and provide a refresh on the text.
• Say credential repository software needs to provide protections.

7.8 Favor Abstract Claims

• Specify who should favor abstract claims -- "issuers should favor abstract claims".

7.9 The Principle of Data Minimization

• Specify that this is advice for issuers and verifiers. Remind credential repositories to disclose what fields the verifier is asking for, so that users can push back.

7.11 Validation

• Possibly move section into larger Validation section?

7.12 Storage Providers and Data Mining

• Say that civil society groups and regulators should play a part in this ecosystem (by doing evaluations and monitoring).

7.14 Usage Patterns

• Localize mitigations to particular actors by saying things like "Authors of specifications for credentialStatus types", and "Using a globally-unique identifier" could be guidance for credential repositories to warn uses when they're re-using an ID.

8.3 Content Integrity Protection

• Update outdated text and speak to new relatedResource feature.

A.1 Credential Type

• Specify that the documents at the type's URL are expected to describe the available properties and their usage.

[jyasskin]

A couple notes based on the questions in #1285 (comment) and later:

4.4 Types
Point to VC-SPECS for some examples of "A valid proof type".

This was just about the word "valid" needing a definition in the context of proof types. If nobody's supposed to check their validity, just remove "valid". I think the work in #1338 is going to help with this: you'll be able to say a proof type with a specified securing algorithm that fits the interface you'll define in #1338.

• Pre-CR review from Jeffrey Yasskin #1285 (comment) replies to my question "Have you considered a way of marking extensions critical?" with a discussion of how the type field naturally ensures that any verifier trying to read a credential of a certain type will be able to process the critical fields for that type. This is plausible, but it implies that individual types can't evolve by adding new critical fields. Instead, the designer would need to allocate a new credential type with the new critical field. I think it'd be good to warn credential type designers about this. Such a warning would be editorial.

7.11 Validation
Possibly move section into larger Validation section?

Here I was suggesting that it'd be nice if the non-normative warnings like "The process of performing these checks might result in information leakage" could instead become normative requirements that prevent the leakage. That won't be possible for every warning, and to the extent that these only happen during Validation, you don't actually have normative language about it at all, so maybe no improvement is possible.

I think you've captured everything else. Thanks!

[iherman]

The issue was discussed in a meeting on 2024-02-14

• no resolutions were taken

View the transcript

2.3. Non-normative changes from Jeffrey Yasskin's review (issue vc-data-model#1348)

See github issue vc-data-model#1348.

Brent Zundel: Non-normative changes from Jeffrey Yasskin's review #1348. currently assigned to manu.

Manu Sporny: I will do this one. in theory all editorial changes. will take me a while since there are so many of them.

[iherman]

The issue was discussed in a meeting on 2024-02-28

• no resolutions were taken

View the transcript

3.10. Non-normative changes from Jeffrey Yasskin's review (issue vc-data-model#1348)

See github issue vc-data-model#1348.

Brent Zundel: Manu, do you need anything on this one?

Manu Sporny: This one scares me ... it's not one issue, it's like 30 things that Jeffrey would like to have changed but they are all in theory editorial. This one will take the longer amount of time.
… I'm afraid a single normative thing will come up. We have time, but I need to prioritize.

Brent Zundel: It's good that we've wrapped around on the issue discussion. Hopefully we'll positively increase the pressure to get these done.
… Thank you Dave for scribing.

Dave Longley: welcome!

---

[iherman]

The issue was discussed in a meeting on 2024-03-06

• no resolutions were taken

View the transcript

2.8. Non-normative changes from Jeffrey Yasskin's review (issue vc-data-model#1348)

See github issue vc-data-model#1348.

Joe Andrieu: understood.

Brent Zundel: 1348.

Manu Sporny: this ones mine. It'll take a few days, but I should be able to do it.

[iherman]

The issue was discussed in a meeting on 2024-03-13

• no resolutions were taken

View the transcript

4.4. Non-normative changes from Jeffrey Yasskin's review (issue vc-data-model#1348)

See github issue vc-data-model#1348.

Brent Zundel: will not be marked pending close. Jeff Y. review. manu: trying to address as many as possible.
… folks if you want to raise a small PR, please do, greatly appreciated!

David Chadwick: section on trust model Jeff Y. wants quite a lot. I'm willing to work on but need more discussion. Break out into.
… separate issues.

Manu Sporny: can skip section 5.2, will provide commit for each checkmark. agree trust model changes require discussion.

[David-Chadwick]

Concerning section 5.2, trust model, here is my input for discussion.

Wordsmith statements to say is that the verifier trusts the issuer to make the statements it's making after verification has been performed.

This can be done as a simple editorial PR. Happy to do that for the WG.

Elaborate on why entities trust/depend on verifiable data registry.

We can say that the VDR contains metadata about issuers, holders and verifiers and is trusted because of the method of its publication. This could be by a peer to peer protocol from a trusted publisher, or on a publicly accessible and well known web site, or on a blockchain etc. When entities publish meta data about themselves, this can be integrity protected e.g. by signing with the entity's private key.

Explain why holder trusts the issuer.

We can say that in many cases the holder will have a pre-existing trust relationship with the issuer, and will trust all the information that it provides, for example, an employer providing an employment VC to an employee, or a bank providing a banking VC to a customer, or a government issuing a passport VC to a citizen. In other cases, where no pre-existing relationship exists, the holder would be advised to have some out of band means of determining if the issuer can be trusted to issue the VC that it provides.
Alternatively we could say that it is not necessary for the holder to always trust the issuer, since the issued VC is an assertion made by the issuer about a subject (which is not the holder), or about no-one, and therefore the holder may be willing to relay this information to a verifier without being held accountable for its veracity.

Say something about the verifier choosing the issuers they want to trust.

We can say that how verifiers decide which issuers to trust is out of scope of the recommendation. However some issuers, e.g. well known organisations, may be implicitly trusted by many verifiers because of their reputation. Other issuers and verifiers may be members of a specific group and all group members trust each other. Other verifiers may trust a specific trust service provider whose responsibility is to vet issuers and list them in a trust list e.g. as specified in ETSI TS 119 612 [ref].

[msporny]

PR #1464 has been raised to address this issue. This issue will be closed once PR #1464 has been merged.

[David-Chadwick]

PR #1469 addresses the comments on section 5.2

[iherman]

The issue was discussed in a meeting on 2024-04-10

• no resolutions were taken

View the transcript

2.2. Non-normative changes from Jeffrey Yasskin's review (issue vc-data-model#1348)

See github issue vc-data-model#1348.

Brent Zundel: 1348, non-normative changes from J Yaskin.

Manu Sporny: i would love help on this, not sure how to distribute the task, other than people picking sections from the big long list.
… if people want to take sections from the bottom of that list, that'd be awesome.
… there's roughly 35 changes that need to be made. not too bad, most of those should be editorial.
… so, volunteers welcome.

David Chadwick: the bit I've done is nearly agreed on now. the one thing I don't know how to do is to add a reference to an external document.

Manu Sporny: at the top of the document, there's a section called Biblio or something like, that has a bunch of square brackets, that's where you add it.
… if you're referencing an existing RFC, those should be there already, you just need double brackets around RFC.

Dave Longley: See https://github.com/w3c/vc-data-model/blob/main/common.js#L7.

Dave Longley: DavidC ^.

Dave Longley: note that this: https://github.com/w3c/vc-data-model/blob/main/index.html#L48 links to that common.js file.

David Chadwick: I couldn't find that section.

Manu Sporny: ok, yeah, what dlongley said.

Brent Zundel: See DavicC's ongoing PR on this.

Brent Zundel: just to note for the minutes, PR 1469 is DavidC's PR that he's addressing.

Brent Zundel: See Manu's ongoing PR on this.

Brent Zundel: and manu's PR for the rest is 1464.
… and as has been mentioned, please feel free to claim a section and work on it.