May 2018 - Review comments from Allen Brown

[msporny]

@vieillevigne submitted lots of review comments for the spec in PDF form:

AllenBrownReview-VerifiableCredentialsDataModel.pdf

This is just a reminder to @msporny to not drop that on the floor.

[msporny]

Extracting all 104 comments from the PDF file and including them here to make it easy to respond to each issue:

@vieillevigne wrote:

page: 1, D:20180501081834-07'00', type: text , content: Of the many examples in this document, I did not find any counter examples. That is to say, a JSON/JSON-LD instance purported to be a valid Verifiable Credential but actually is not. Such examples are certainly required for a test suite. Counter examples are also good pedagogical practice.

@vieillevigne wrote:

page: 1, D:20180501082257-07'00', type: text , content: This document has two occurrences f the string "normative" -- including cases prefixed by "non". In both cases the term applies to other documents. I contrast this document with JSON-LD 1.1 spec which is quite clear about what sections are normative.

@vieillevigne wrote:

page: 1, D:20180501081845-07'00', type: text , content: I had expected this document to contain explicitly indicated normative sections analogous to https://json-ld.org/spec/latest/json-ld/#data-model and https://json-ld.org/spec/latest/json-ld/#json-ld-grammar in the JSON-LD spec.

@vieillevigne wrote:

page: 1, D:20180430111454-07'00', type: text , content: This document is excessively verbose in two respects:

1. Elucidation of technical considerations beyond the stated scope of the specif2. Conversational chattiness which might be appropriate to a tutorial but out of place in a document whose principal objectives have to be precision and accuracy.
   In terms of succinctness, I contrast this document with the 16-page JSON spec https://tools.ietf.org/html/rfc8259.

@vieillevigne wrote:

page: 5, D:20180430091017-07'00', type: text , content: This phrase has may possible readings. I presume that what is meant is that it should be possible to mechanize the verification of such credentials.

@vieillevigne wrote:

page: 5, D:20180430091112-07'00', type: text , content: These are USA-specific constructs. Something more neutral is desired.

@vieillevigne wrote:

page: 5, D:20180430091441-07'00', type: text , content: Some information in a physical credential is simply not salient in the digital context. A paper credential, for example, contains as information the pH of the paper from which the credential is made. At one time this was a critical factor in validating a US passport as not being a forgery. Why a digital credential would contain such information is, obscure: "The pH of this digital credential is 5.3." Better to say: "It is intended that a verifiable be capable of representing all of the same information that a physical credential is intended to represent."

@vieillevigne wrote:

page: 5, D:20180430091720-07'00', type: text , content: Distance hardly seems the point here other than a place holder for "distributed". In so far as the agents of Figure 1 each has a location, it is unlikely to be shared with the others. Digital credentials can be presented other than by physically materializing the credential at a physical place to be validated.

@vieillevigne wrote:

page: 6, D:20180427153046-07'00', type: text , content: The holder seems to be "in possession" but hardly "in control" as credentials may be revoked by other parties.

@vieillevigne wrote:

page: 6, D:20180430092837-07'00', type: text , content: The "entities" enumerated on this page would appear to be better termed "agents". In general, what is interesting about them is how they may act.

@vieillevigne wrote:

page: 6, D:20180430092743-07'00', type: text , content: Here the four items following are termed "roles". Within their descriptions they are re-termed "entities". Roles are rather like typed variables. (Work flow systems are typically implemented this way.) "Entities" are rather like values of a certain type -- something which may be bound to variables. In any event, a "holder is either a role" as stated here or an "entity" as stated below. It cannot be both.

@vieillevigne wrote:

page: 6, D:20180430092927-07'00', type: text , content: Apparently an identifier registry is neither a role nor an entity as the other terms introduced in this section. There is presumably some semantic difference imputed by the two distinct kinds of arrows in this figure. What exactly is that difference? Also, how is an identifier registry anything more than a database against which a holder appears to be doing updates, while an issuer is performing a query?

@vieillevigne wrote:

page: 7, D:20180430093117-07'00', type: text , content: The ordinary language reading of "MUST" is such that this sentence means that a holder is not allowed to receive a verifiable credential through an agent that the holder trusts. Other "MUST" sentences below have a similar reading.

@vieillevigne wrote:

page: 7, D:20180430124010-07'00', type: text , content: As I understand this document, it is a specification of the class of data instances which const"This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and autAll of the below relate to the operational semantics of such data instances. I fail to see how such semantics are relevant to the document's avowed purpose. Indeed, what I expected this document to be is an analogue of Clause 3 of the IEEE 754-2008 floating point standard. That particular clause relates only to floating point formats. It does not talk about -- for example -- exception handling or operations. The latter topics are found in other clauses.

@vieillevigne wrote:

page: 9, D:20180430093407-07'00', type: text , content: While figure 1 indicates that a holder stores credentials, there is no evidence of a credential repository in the data flow of the figure. Of course, I may be unjustifiably assuming that the arrows constitute some sort of data flow. Possibly much handier than this dictionary of terminology would be a complete data flow among the constructs mentioned. Finally, if it is meant that the Holder is the only repository of credentials, that point should be made explicitly.

@vieillevigne wrote:

page: 9, D:20180501084439-07'00', type: text , content: My understandin"Data model" refers to either (1) an abstract formalization of the objects and relationships found in a particular application domain, for example the customers, products, and orders found in a manufacturing organization; or (2) a set of concepts used in defining such formalizations: for example concepts such as entities, attributes, relations, or tables.
Given the enumeration of terms in section 2 above, this document would appear to concern itself with interpretation (1) of a data model. All my comments are in the context of that interpretation.

@vieillevigne wrote:

page: 10, D:20180430093613-07'00', type: text , content: This sentence has the same status as "An untyped binary predicate can mean anything one wants it too." More generously the first order predicate calculus having only binary predicate symbols is no less expressive than the first order predicate calculus with function symbols and predicate symbols of arbitrary arities. Presumably any reader with the least familiarity with the goals of the semantic web is aware of all this.

@vieillevigne wrote:

page: 11, D:20180427163957-07'00', type: text , content: Indeed, in 1988 passports issued by the Islamic Republic of Iran had four slots labeled "wife".

@vieillevigne wrote:

page: 12, D:20180430093901-07'00', type: text , content: Again, this section elaborates the operational semantics of VCs as they flow in Figure 1. While informative, such is not the subject matter of a data model.

@vieillevigne wrote:

page: 12, None , type: popup , content: Again, this section elaborates the operational semantics of VCs. Such is not the subject matter of a data model.

@vieillevigne wrote:

page: 19, D:20180502100904-07'00', type: text , content: What prevents the developer from replacing old terms like "proof" and "claim"?

@vieillevigne wrote:

page: 20, D:20180430094226-07'00', type: text , content: What prevented instead? The answer is apparently, "nothing". The next example strongly suggests that the current example is ill conceived. Since almost surely, the developer didn't mean to permit the instance I just proposed, I am surprised that the example without nested @context was offered.

@vieillevigne wrote:

page: 21, D:20180430094346-07'00', type: text , content: One presumes thtermsOfUse:Credential --> Maybe([Policy])edential type:

The text says what the value of the property MUST be, but does not remark upon the property itself.

@vieillevigne wrote:

page: 23, D:20180428142210-07'00', type: text , content: MAY

@vieillevigne wrote:

page: 23, D:20180428143115-07'00', type: text , content: "Evidence" for what? How is Evidence different from Proof? At least in the American system of jurisprudence "evidence" is understood to be a premise in an argument. Insofar as argument = proof, I'd like to understand how Evidence relates to Proof.

@vieillevigne wrote:

page: 24, D:20180430094807-07'00', type: text , content: Some sentence in this paragraph should have used "MAY". As the carrier of the dispute is the presumably optional property, currentStatus, that property should presumably be the target of MAY. As they stand, the sentences which use "may" don't seem to be the right ones to be MAYs.

@vieillevigne wrote:

page: 26, D:20180430094838-07'00', type: text , content: This presumably means properties introduced by "MUST". Surprisingly, no mention is made of properties introduced by "MAY". Since this section is about verification, the MAYs need to be elaborated as well.

@vieillevigne wrote:

page: 26, D:20180430095013-07'00', type: text , content: How is a reader to know what it means to "match expectations" if the document alludes only to "likely" meaning".

Legislatures don't generally get to write laws like "It is prohibited to sell bad goods. Likely, bad goods are goods customers don't want."

@vieillevigne wrote:

page: 26, D:20180428144426-07'00', type: text , content: Available? In what context? To whom?

@vieillevigne wrote:

page: 26, D:20180428144524-07'00', type: text , content: Again, I have trouble with this sort of sentence in a specification.

@vieillevigne wrote:

page: 27, D:20180428174726-07'00', type: text , content: Both negatives presumably are NOT intended.

@vieillevigne wrote:

page: 27, D:20180428174828-07'00', type: text , content: What does this mean?

@vieillevigne wrote:

page: 27, D:20180428180017-07'00', type: text , content: Whose future? The future of the issuer? The future of the holder? The future of the verifier? Suppose for example the issuer cannot possibly see the issued credential until 2 hours after issue?

@vieillevigne wrote:

page: 27, D:20180428175656-07'00', type: text , content: Suppose the credential is currently valid. Suppose the activity for which the credential grants permission starts now but cannot complete until two hours after expiration.

@vieillevigne wrote:

page: 27, D:20180429110539-07'00', type: text , content: Does this mean MUST be?

@vieillevigne wrote:

page: 27, D:20180430102048-07'00', type: text , content: I do not undersIt begins by asserting that the issuer will be trusted by the verifier "to make the claims at hand". The infinitive phrase seems to be a legal term of art. which goes unexplained. In contrast, the spec earlier takes the trouble to explain tThe next sentence opens with "For example" and proceeds to elucidate an example which almost surely does not constitute "claims at hand". In fact, it seems likely that it is a counter example to "claims at hand".

@vieillevigne wrote:

page: 28, D:20180430102154-07'00', type: text , content: These last two bullets (unlike the first two) appear not to be sentences as each of them appears to consist of two subordinate clauses. To what are they meant to be subordinate?

@vieillevigne wrote:

page: 28, D:20180430102416-07'00', type: text , content: Each example offered heretofore -- modulo contained ellipses -- appears to have been JSON/JSON-LD! Specifically, those examples are presumably intended to denote structures admissible by the data model. This first sentence strongly suggests that that which has appeared in examples thus far is not JSON/JSON-LD. As I neither speaks nor write JSON/JSON-LD fluently, I am confused by the sentence.

@vieillevigne wrote:

page: 28, D:20180430102440-07'00', type: text , content: Mappings from and to what? That the mappings are "syntactic" strongly suggests from some source syntax to some target syntax. But, maybe not.

@vieillevigne wrote:

page: 28, D:20180430114557-07'00', type: text , content: I take this collection of bullets as normative and as controlling what sorts of terms may be ta'21' as used in various examples in this document represents a "number value". 'XVII' and '9A3C' presumably do not represent number values -- despite the fact that they could reasonably do so. I understand "represented" here to mean "encoded". As such representations are purely syntactic. Types are semantic constructs.
I am aware that the JSON spec says "The representation of numbers is similar to that used in most programming languages. A number is represented [by JSON] in base 10 using decimal digits." and "JSON can represent [inhabitants of] four primitive types (strings, numbers, booleans, and null)" But actually, the two sentencIn any event, a number value cannot be represented as a Number type as a Number type -- being semantic rather than syntactic -- is not a representation. Put another way, in the JSON context a Number type denotes a set while a number value does not denote a set. Consequently it is an error of kind to say that a number value is represented as a number type.
In the current instance "A value which is intended to be a number MUST be of type Number". SImilarly for the other bullets.

@vieillevigne wrote:

page: 29, D:20180429114733-07'00', type: text , content: Here is EXAMPLE 1

{
"id": "http://dmv.example.gov/credentials/3732",
"type": ["Credential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov/issuers/14",
"issued": "2010-01-01T19:73:24Z",
"claim": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageOver": 21
},
"proof": { ... }
}

What is EXAMPLE 14 trying to tell me that I don't already know?

@vieillevigne wrote:

page: 30, D:20180430114748-07'00', type: text , content: This example ilapart from introducing a domain property, a revocation property, etc.?Since the domain property has never been mentioned before in this document, one has no idea whether it's a required property, an optional property, a property introduced The the first sentence of 8.1.1 says "an instance of the Verifiable Credential is expressed as a single JSON object whose properties are the verifiable credential's properties". At this point in the document one still doesn't know exactly what those properties are.

@vieillevigne wrote:

page: 34, D:20180430114935-07'00', type: text , content: All my earlier remarks concerning relating values and types in this way apply to these bullets as well.

@vieillevigne wrote:

page: 36, D:20180429120241-07'00', type: text , content: Unbound section reference.

@vieillevigne wrote:

page: 36, D:20180429123754-07'00', type: text , content: Understanding "@context" as a feature distinguishing JSON-LD from JSON, I consulted https://json-ld.org/spec/latest/json-ld/. I went immediately to the section entitled "The Context" https://json-ld.org/spec/latest/json-ld/#the-context -- which turns out to be non normative. Then I discovered the sections "Context Definitions" https://json-ld.org/spec/latest/json-ld/#context-definitions and "Id Maps" https://json-ld.org/spec/latest/json-ld/#id-maps which, being full of MUSTs and MAYs, are pI was specifically interested in the phrase "where a document could be retrieved that provides its semantics in a machine-readable data format". In neither of the referenced sections in the JSON-LD spec can I find a reference to such a semantic adjunct to contexts. So I feel to conclude that such an adjunction -- even as a MAY -- is not normative. As this section, 8.2.1, is presumably normative, it doesn't seem the proper place to introduce the possible existence of some putatively semantical construct.

@vieillevigne wrote:

page: 40, D:20180430130551-07'00', type: text , content: I gather that a section of this sort is now required in W3C recommendations. As far as I can tell here, all the privacy considerations are about the operational use of this notional data standard. I have already remarked multiple times that this document departs from being a data standard and enters the realm of the operational. As a thought experiment one might ask oneself about the privacy considerations regarding clause 3 of the previously mentioned IEEE floating point standard. While I can suggest many such considerations as regards the use of the IEEE floating point numbers, I find it difficult to discern privacy issues in the floating point format.

@vieillevigne wrote:

page: 41, D:20180430130108-07'00', type: text , content: Here it is worth remembering and possibly even mentioning Eric Bergeron's 2000 W3C workshop position paper https://www.w3.org/P3P/mobile-privacy-ws/papers/zks.html: "...In this example, the goals of security and privacy are the same. But there are other times when they may be orthogonal, and there are also times when they are in conflict..."

@vieillevigne wrote:

page: 44, D:20180430131944-07'00', type: text , content: I fail to see how the ageOver property is any more abstract than the birthDateOf property. What I think is intended here relates to entailment rather than abstraction.
What one wants is a collection of property values from which, for example, it can be entailed that a person is old enough to drink without entailing the person's identity. It may well be that there is no set of properties that would convincingly (from the verifier's perspective) entail a person's legality as a drinker without also entailing the person's identity. This gets back to the point earlier quoted from Bergeron.

@vieillevigne wrote:

page: 44, D:20180430133036-07'00', type: text , content: "Minimum" and "minimal" in this section both relate to entailment. What one wants logically is the smallest set of available propositions which entail (or refute) the proposition of interest. In the current setting properties may be understood as propositIt is worth noting that the sorts of extension mechanisms elucidated in section 6.1 are not the friends of privacy. As it is hard to introduce a new property that is independent of all other properties, this makes the minimal discolsure problem all the more difficult.

@vieillevigne wrote:

page: 46, D:20180430133338-07'00', type: text , content: This probibition seems largely at odds with the next section.

@vieillevigne wrote:

page: 47, D:20180430133714-07'00', type: text , content: Aggregation of credentials implies NOT minimal disclosure. Why not unite sections 9.8 and 9.12?

@vieillevigne wrote:

page: 51, D:20180429125131-07'00', type: text , content: While it is true that this document is replete with references to digital cryptographic constructs, I fail to see how this particular sentence can possibly be true.

@vieillevigne wrote:

page: 51, D:20180430122817-07'00', type: text , content: This has actually puzzled me since the start of the document. For JSON-LD objects in this document that have a type property "Credential" there seems to be no obligation to have proof(s). In that regard, the document seems to be a specification for credentials, only some of which are verifiable.

[msporny]

@vieillevigne wrote:

page: 1, D:20180501081834-07'00', type: text , content: Of the many examples in this document, I did not find any counter examples. That is to say, a JSON/JSON-LD instance purported to be a valid Verifiable Credential but actually is not. Such examples are certainly required for a test suite. Counter examples are also good pedagogical practice.

Yes, the test suite certainly has (and will have more of these sorts of tests). From a pedagogical standpoint, I'm not sure we want to include counter-examples in the specification. The reason being that there are many ways a Verifiable Credential can be wrong, and I'm not certain that elaborating on only a subset will be helpful. Verifiable Credentials that are wrong will fail validation/checking and the errors will be apparent to the developers using libraries to check the correctness of the verifiable credential.

[msporny]

@vieillevigne wrote:

page: 1, D:20180501082257-07'00', type: text , content: This document has two occurrences f the string "normative" -- including cases prefixed by "non". In both cases the term applies to other documents. I contrast this document with JSON-LD 1.1 spec which is quite clear about what sections are normative.

Fixed here 901a5d3

[msporny]

@vieillevigne wrote:

page: 1, D:20180501081845-07'00', type: text , content: I had expected this document to contain explicitly indicated normative sections analogous to https://json-ld.org/spec/latest/json-ld/#data-model and https://json-ld.org/spec/latest/json-ld/#json-ld-grammar in the JSON-LD spec.

This has been fixed in 901a5d3

[msporny]

@vieillevigne wrote:

page: 1, D:20180430111454-07'00', type: text , content: This document is excessively verbose in two respects:

1. Elucidation of technical considerations beyond the stated scope of the specif2. Conversational chattiness which might be appropriate to a tutorial but out of place in a document whose principal objectives have to be precision and accuracy.
   In terms of succinctness, I contrast this document with the 16-page JSON spec https://tools.ietf.org/html/rfc8259.

One of the frequent complements we received on the JSON-LD specification was that the specification's front-matter can be used to understand why the specification exists for people that are not developers while the back-matter can be used by implementers to implement.

I have no issue with short specifications, for example the meat of the HTTP Signatures specification (which I wrote) is all of 5 pages long:

https://tools.ietf.org/html/draft-cavage-http-signatures-10

This is because the concepts and use case that it addresses is simple and self-contained. That is not the case for the Verifiable Credentials specification. In addition, we have had to defend its right to exist many times over the past 5+ years (it's not immediately obvious to people that have a background in x.509 and similar technologies), which has led us to refining that story into the front matter of the specification so that we don't have to keep explaining it to people as they discover what we're doing.

I think the mistake that many W3C specifications make is being so succinct that they completely miss out on the opportunity to teach people what the problem is and how it is being solved in the first place. Most technical specifications (and technical writing) fails to orient the reader before delving into the details.

That's not to say that the VC spec is doing a good job in that regard... but that's at least the principle behind why the front matter is so verbose.

[msporny]

@vieillevigne wrote:

page: 5, D:20180430091017-07'00', type: text , content: This phrase has may possible readings. I presume that what is meant is that it should be possible to mechanize the verification of such credentials.

Fixed in 3387198

[msporny]

@vieillevigne wrote:

page: 5, D:20180430091112-07'00', type: text , content: These are USA-specific constructs. Something more neutral is desired.

Fixed in f30c3c0

[msporny]

@vieillevigne wrote:

page: 5, D:20180430091441-07'00', type: text , content: Some information in a physical credential is simply not salient in the digital context. A paper credential, for example, contains as information the pH of the paper from which the credential is made. At one time this was a critical factor in validating a US passport as not being a forgery. Why a digital credential would contain such information is, obscure: "The pH of this digital credential is 5.3." Better to say: "It is intended that a verifiable be capable of representing all of the same information that a physical credential is intended to represent."

Fixed in 68cb5da

[msporny]

@vieillevigne wrote:

page: 5, D:20180430091720-07'00', type: text , content: Distance hardly seems the point here other than a place holder for "distributed". In so far as the agents of Figure 1 each has a location, it is unlikely to be shared with the others. Digital credentials can be presented other than by physically materializing the credential at a physical place to be validated.

Fixed in d304bc7

[msporny]

@vieillevigne wrote:

page: 6, D:20180427153046-07'00', type: text , content: The holder seems to be "in possession" but hardly "in control" as credentials may be revoked by other parties.

Fixed in 62e2242

[msporny]

@vieillevigne wrote:

page: 6, D:20180430092837-07'00', type: text , content: The "entities" enumerated on this page would appear to be better termed "agents". In general, what is interesting about them is how they may act.

We try to avoid the term "agent" as W3C people often confuse it with "user agent" which results in tragic consequences.

[msporny]

@vieillevigne wrote:

page: 6, D:20180430092743-07'00', type: text , content: Here the four items following are termed "roles". Within their descriptions they are re-termed "entities". Roles are rather like typed variables. (Work flow systems are typically implemented this way.) "Entities" are rather like values of a certain type -- something which may be bound to variables. In any event, a "holder is either a role" as stated here or an "entity" as stated below. It cannot be both.

Clarified the language around roles and entities in 8fa3910

[msporny]

@vieillevigne wrote:

page: 6, D:20180430092927-07'00', type: text , content: Apparently an identifier registry is neither a role nor an entity as the other terms introduced in this section. There is presumably some semantic difference imputed by the two distinct kinds of arrows in this figure. What exactly is that difference? Also, how is an identifier registry anything more than a database against which a holder appears to be doing updates, while an issuer is performing a query?

Clarified it as a role in 8fa3910

[msporny]

@vieillevigne wrote:

page: 7, D:20180430093117-07'00', type: text , content: The ordinary language reading of "MUST" is such that this sentence means that a holder is not allowed to receive a verifiable credential through an agent that the holder trusts. Other "MUST" sentences below have a similar reading.

Fixed in 525d709

[msporny]

@vieillevigne wrote:

page: 7, D:20180430124010-07'00', type: text , content: As I understand this document, it is a specification of the class of data instances which const"This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and autAll of the below relate to the operational semantics of such data instances. I fail to see how such semantics are relevant to the document's avowed purpose. Indeed, what I expected this document to be is an analogue of Clause 3 of the IEEE 754-2008 floating point standard. That particular clause relates only to floating point formats. It does not talk about -- for example -- exception handling or operations. The latter topics are found in other clauses.

I think this is fixed in 525d709, but I'm not sure.

[msporny]

@vieillevigne wrote:

page: 9, D:20180430093407-07'00', type: text , content: While figure 1 indicates that a holder stores credentials, there is no evidence of a credential repository in the data flow of the figure. Of course, I may be unjustifiably assuming that the arrows constitute some sort of data flow. Possibly much handier than this dictionary of terminology would be a complete data flow among the constructs mentioned. Finally, if it is meant that the Holder is the only repository of credentials, that point should be made explicitly.

The arrows do specify the data flow. The specification does state "Holders store their credentials in credential repositories". The Holder isn't always the only repository of credentials (for example, public databases, blockchains, etc. can also be credential repositories, some of them have no connection with the holder.)

[msporny]

@vieillevigne wrote:

page: 9, D:20180501084439-07'00', type: text , content: My understandin"Data model" refers to either (1) an abstract formalization of the objects and relationships found in a particular application domain, for example the customers, products, and orders found in a manufacturing organization; or (2) a set of concepts used in defining such formalizations: for example concepts such as entities, attributes, relations, or tables.
Given the enumeration of terms in section 2 above, this document would appear to concern itself with interpretation (1) of a data model. All my comments are in the context of that interpretation.

Yes, that is the correct interpretation.

[msporny]

@vieillevigne wrote:

page: 10, D:20180430093613-07'00', type: text , content: This sentence has the same status as "An untyped binary predicate can mean anything one wants it too." More generously the first order predicate calculus having only binary predicate symbols is no less expressive than the first order predicate calculus with function symbols and predicate symbols of arbitrary arities. Presumably any reader with the least familiarity with the goals of the semantic web is aware of all this.

Yes, correct. It's an obvious statement but there are many that don't know about or understand the goals of the semantic web. We're trying to succinctly express those here (without overly burdening the reader w/ the goals or mechanisms used for semantic web... as many of those concepts are uninteresting to most developers... and some of them are not useful for day to day programming tasks).

[msporny]

@vieillevigne wrote:

page: 11, D:20180427163957-07'00', type: text , content: Indeed, in 1988 passports issued by the Islamic Republic of Iran had four slots labeled "wife".

Ha! Interesting, I didn't know that.

@vieillevigne wrote:

page: 12, D:20180430093901-07'00', type: text , content: Again, this section elaborates the operational semantics of VCs as they flow in Figure 1. While informative, such is not the subject matter of a data model.

Yes, although they are provided to help give the reader some operational context.

@vieillevigne wrote:

page: 12, None , type: popup , content: Again, this section elaborates the operational semantics of VCs. Such is not the subject matter of a data model.

Again, to provide the reader w/ operational context.

[msporny]

@vieillevigne wrote:

page: 19, D:20180502100904-07'00', type: text , content: What prevents the developer from replacing old terms like "proof" and "claim"?

The processor will throw an error as explained at the bottom of the section.

@vieillevigne wrote:

page: 20, D:20180430094226-07'00', type: text , content: What prevented instead? The answer is apparently, "nothing". The next example strongly suggests that the current example is ill conceived. Since almost surely, the developer didn't mean to permit the instance I just proposed, I am surprised that the example without nested @context was offered.

The answer isn't nothing... it's prevented by happening via the processor throwing an error.

[msporny]

@vieillevigne wrote:

page: 21, D:20180430094346-07'00', type: text , content: One presumes thtermsOfUse:Credential --> Maybe([Policy])edential type:
The text says what the value of the property MUST be, but does not remark upon the property itself.

The property itself is defined by the Verifiable Credentials JSON-LD context (this is true for all properties defined in the specification)... which is defined in the section on extensibility above where this comment was made:

"the base JSON-LD Context (https://w3id.org/credentials/v1)."

The current JSON-LD Context is provided here:

https://github.com/w3c/vc-data-model/blob/gh-pages/vocab/context.jsonld

When the spec is finalized, the URL above will be udpated.

[msporny]

@vieillevigne wrote:

page: 23, D:20180428143115-07'00', type: text , content: "Evidence" for what? How is Evidence different from Proof? At least in the American system of jurisprudence "evidence" is understood to be a premise in an argument. Insofar as argument = proof, I'd like to understand how Evidence relates to Proof.

Clarified how evidence is different from proof in this commit: f10f8c8

[msporny]

@vieillevigne wrote:

page: 24, D:20180430094807-07'00', type: text , content: Some sentence in this paragraph should have used "MAY". As the carrier of the dispute is the presumably optional property, currentStatus, that property should presumably be the target of MAY. As they stand, the sentences which use "may" don't seem to be the right ones to be MAYs.

Removed confusing non-normative MAY language in 3dcbe4e

[msporny]

@vieillevigne wrote:

page: 26, D:20180430094838-07'00', type: text , content: This presumably means properties introduced by "MUST". Surprisingly, no mention is made of properties introduced by "MAY". Since this section is about verification, the MAYs need to be elaborated as well.

Fixed the MAYs in 3dcbe4e. Clarified the requirements in 9e73f95.

[msporny]

@vieillevigne wrote:

page: 26, D:20180430095013-07'00', type: text , content: How is a reader to know what it means to "match expectations" if the document alludes only to "likely" meaning".
Legislatures don't generally get to write laws like "It is prohibited to sell bad goods. Likely, bad goods are goods customers don't want."
page: 26, D:20180428144426-07'00', type: text , content: Available? In what context? To whom?

Cleaned up the language in 860a725.

[msporny]

@vieillevigne wrote:

page: 26, D:20180428144524-07'00', type: text , content: Again, I have trouble with this sort of sentence in a specification.

Fixed in ad793e1.

[msporny]

@vieillevigne wrote:

page: 27, D:20180428174726-07'00', type: text , content: Both negatives presumably are NOT intended.
page: 27, D:20180428174828-07'00', type: text , content: What does this mean?

Fixed and clarified in ffc269a.

[msporny]

@vieillevigne wrote:

page: 27, D:20180428180017-07'00', type: text , content: Whose future? The future of the issuer? The future of the holder? The future of the verifier? Suppose for example the issuer cannot possibly see the issued credential until 2 hours after issue?

The text says "verifier", so the currently means "the future of the verifier". I expect you mean "example the verifier", and if they can't see it until 2 hours after issue, then it's not a problem as long as 2 hours in the future is not "in the future" for the verifier.

That said, I've clarified the language a bit in c625755.

[msporny]

@vieillevigne wrote:

page: 27, D:20180428175656-07'00', type: text , content: Suppose the credential is currently valid. Suppose the activity for which the credential grants permission starts now but cannot complete until two hours after expiration.

This is up to the verifier's risk model to determine if that is appropriate for the use case. This is one of the reasons we're keeping the language around issued and expires a bit loose. It may be perfectly valid to accept credentials that have expired by a couple of days for a light ID check, for example.

[msporny]

@vieillevigne wrote:

page: 27, D:20180429110539-07'00', type: text , content: Does this mean MUST be?

Yes, fixed in 2d08dc4.

@vieillevigne wrote:

page: 27, D:20180430102048-07'00', type: text , content: I do not undersIt begins by asserting that the issuer will be trusted by the verifier "to make the claims at hand". The infinitive phrase seems to be a legal term of art. which goes unexplained. In contrast, the spec earlier takes the trouble to explain tThe next sentence opens with "For example" and proceeds to elucidate an example which almost surely does not constitute "claims at hand". In fact, it seems likely that it is a counter example to "claims at hand".

Yes, that was confusing. Fixed in 2d08dc4 to use positive examples instead of negative ones.

@vieillevigne wrote:

page: 28, D:20180430102154-07'00', type: text , content: These last two bullets (unlike the first two) appear not to be sentences as each of them appears to consist of two subordinate clauses. To what are they meant to be subordinate?

Fixed in 2d08dc4.

[msporny]

@vieillevigne wrote:

page: 28, D:20180430102416-07'00', type: text , content: Each example offered heretofore -- modulo contained ellipses -- appears to have been JSON/JSON-LD! Specifically, those examples are presumably intended to denote structures admissible by the data model. This first sentence strongly suggests that that which has appeared in examples thus far is not JSON/JSON-LD. As I neither speaks nor write JSON/JSON-LD fluently, I am confused by the sentence.

I've effectively gutted the entire section on syntax as most of the specification is introduced by example, most every example /is/ JSON and this section doesn't add a great deal wrt. the examples and language. Most of the section is confusing and repetitive (it was one of the first sections written in the specification and hasn't been kept up to date). Thus, the huge editorial gutting in eb9be6c. For every section in the syntax section that has been gutted, I've made sure that an example or text exists elsewhere in the specification that covers the text that has been removed.

Many of your questions/confusions below have been addressed by the rewrite.

@vieillevigne wrote:

page: 28, D:20180430102416-07'00', type: text , content: Each example offered heretofore -- modulo contained ellipses -- appears to have been JSON/JSON-LD! Specifically, those examples are presumably intended to denote structures admissible by the data model.

Yes, that's true.

This first sentence strongly suggests that that which has appeared in examples thus far is not JSON/JSON-LD. As I neither speaks nor write JSON/JSON-LD fluently, I am confused by the sentence.

That was not the intent and I've added clarity here in eb9be6c.

@vieillevigne wrote:

page: 28, D:20180430102440-07'00', type: text , content: Mappings from and to what? That the mappings are "syntactic" strongly suggests from some source syntax to some target syntax. But, maybe not.

It's meant to map a source data model to a target syntax. Some clarification in eb9be6c.

@vieillevigne wrote:

page: 28, D:20180430114557-07'00', type: text , content: I take this collection of bullets as normative and as controlling what sorts of terms may be ta'21' as used in various examples in this document represents a "number value". 'XVII' and '9A3C' presumably do not represent number values -- despite the fact that they could reasonably do so. I understand "represented" here to mean "encoded". As such representations are purely syntactic. Types are semantic constructs.

Yes. I've tried to clarify all of this in eb9be6c.

I am aware that the JSON spec says "The representation of numbers is similar to that used in most programming languages. A number is represented [by JSON] in base 10 using decimal digits." and "JSON can represent [inhabitants of] four primitive types (strings, numbers, booleans, and null)" But actually, the two sentencIn any event, a number value cannot be represented as a Number type as a Number type -- being semantic rather than syntactic -- is not a representation. Put another way, in the JSON context a Number type denotes a set while a number value does not denote a set. Consequently it is an error of kind to say that a number value is represented as a number type.
In the current instance "A value which is intended to be a number MUST be of type Number". SImilarly for the other bullets.

I've tried to bring the language such that it speaks specifically to "Numeric values representable as IEEE754" in eb9be6c.

@vieillevigne wrote:

page: 29, D:20180429114733-07'00', type: text , content: Here is EXAMPLE 1
What is EXAMPLE 14 trying to tell me that I don't already know?

Nothing... I've gutted the examples. :)

@vieillevigne wrote:

page: 30, D:20180430114748-07'00', type: text , content: This example ilapart from introducing a domain property, a revocation property, etc.?Since the domain property has never been mentioned before in this document, one has no idea whether it's a required property, an optional property, a property introduced The the first sentence of 8.1.1 says "an instance of the Verifiable Credential is expressed as a single JSON object whose properties are the verifiable credential's properties". At this point in the document one still doesn't know exactly what those properties are.

Removed the confusing language in eb9be6c.

@vieillevigne wrote:

page: 34, D:20180430114935-07'00', type: text , content: All my earlier remarks concerning relating values and types in this way apply to these bullets as well.

Removed in eb9be6c.

@vieillevigne wrote:

page: 36, D:20180429120241-07'00', type: text , content: Unbound section reference.

Fixed in eb9be6c.

@vieillevigne wrote:

page: 36, D:20180429123754-07'00', type: text , content: Understanding "@context" as a feature distinguishing JSON-LD from JSON, I consulted https://json-ld.org/spec/latest/json-ld/. I went immediately to the section entitled "The Context" https://json-ld.org/spec/latest/json-ld/#the-context -- which turns out to be non normative. Then I discovered the sections "Context Definitions" https://json-ld.org/spec/latest/json-ld/#context-definitions and "Id Maps" https://json-ld.org/spec/latest/json-ld/#id-maps which, being full of MUSTs and MAYs, are pI was specifically interested in the phrase "where a document could be retrieved that provides its semantics in a machine-readable data format". In neither of the referenced sections in the JSON-LD spec can I find a reference to such a semantic adjunct to contexts. So I feel to conclude that such an adjunction -- even as a MAY -- is not normative. As this section, 8.2.1, is presumably normative, it doesn't seem the proper place to introduce the possible existence of some putatively semantical construct.

Removed and reworded in eb9be6c. Does the new text address your concern?

[msporny]

@vieillevigne wrote:

page: 40, D:20180430130551-07'00', type: text , content: I gather that a section of this sort is now required in W3C recommendations.

Yes, that is correct. In fact, we weren't even allowed to start the WG until we had a section that picked apart all of the privacy considerations that we could think of. It took us multiple in-person meetings at conferences, multiple requests to WGs and IGs, and close to six months to do the analysis and bring all of this together. :(

As far as I can tell here, all the privacy considerations are about the operational use of this notional data standard. I have already remarked multiple times that this document departs from being a data standard and enters the realm of the operational. As a thought experiment one might ask oneself about the privacy considerations regarding clause 3 of the previously mentioned IEEE floating point standard. While I can suggest many such considerations as regards the use of the IEEE floating point numbers, I find it difficult to discern privacy issues in the floating point format.

Yes, well... there are politics at play here and we need this section in the document. We tried to make it a separate document and people (not involved in the work) moaned and complained about it. So, it's there until everyone feels comfortable with the fact that we've done the proper review. We're submitting this document to the W3C Privacy Interest Group in the next couple of months.

[msporny]

@vieillevigne wrote:

page: 41, D:20180430130108-07'00', type: text , content: Here it is worth remembering and possibly even mentioning Eric Bergeron's 2000 W3C workshop position paper https://www.w3.org/P3P/mobile-privacy-ws/papers/zks.html: "...In this example, the goals of security and privacy are the same. But there are other times when they may be orthogonal, and there are also times when they are in conflict..."

If we can cite a collection of Web Privacy papers that might be better, such as from the most recent Privacy on the Web Workshop (which I did a quick search for and couldn't find).

[msporny]

@vieillevigne wrote:

page: 44, D:20180430131944-07'00', type: text , content: I fail to see how the ageOver property is any more abstract than the birthDateOf property. What I think is intended here relates to entailment rather than abstraction.

The latter establishes an exact date where the former just provides monotonic logic wrt. the question asked. The second is more privacy preserving than the first.

What one wants is a collection of property values from which, for example, it can be entailed that a person is old enough to drink without entailing the person's identity.

Yes, correct.

It may well be that there is no set of properties that would convincingly (from the verifier's perspective) entail a person's legality as a drinker without also entailing the person's identity. This gets back to the point earlier quoted from Bergeron.

I'd challenge that assertion, there are zero knowledge proofs that would convince /some/ verifiers that the person's legality as a drinker is entailed.

[msporny]

@vieillevigne wrote:

page: 44, D:20180430133036-07'00', type: text , content: "Minimum" and "minimal" in this section both relate to entailment. What one wants logically is the smallest set of available propositions which entail (or refute) the proposition of interest. In the current setting properties may be understood as propositIt is worth noting that the sorts of extension mechanisms elucidated in section 6.1 are not the friends of privacy. As it is hard to introduce a new property that is independent of all other properties, this makes the minimal discolsure problem all the more difficult.

Yes, that is correct. I've tried to note that in the spec in 30ccbcd.

[msporny]

@vieillevigne wrote:

page: 46, D:20180430133338-07'00', type: text , content: This probibition seems largely at odds with the next section.

Privacy is a sliding scale, and at times, principles are at odds with one another. So yes, it is at odds for all use cases, but not for some use cases (where you prefer one principle over the other).

[msporny]

@vieillevigne wrote:

page: 47, D:20180430133714-07'00', type: text , content: Aggregation of credentials implies NOT minimal disclosure. Why not unite sections 9.8 and 9.12?

They are different conceptually... Principle of Minimum Disclosure is meant to be about "asking and giving as little as possible"... Aggregation of Credentials is about "be aware of the information collected on you over time".

[msporny]

@vieillevigne wrote:

page: 51, D:20180429125131-07'00', type: text , content: While it is true that this document is replete with references to digital cryptographic constructs, I fail to see how this particular sentence can possibly be true.

Agreed, bad sentence. Attempted to clarify in 352a574.

[msporny]

@vieillevigne wrote:

page: 51, D:20180430122817-07'00', type: text , content: This has actually puzzled me since the start of the document. For JSON-LD objects in this document that have a type property "Credential" there seems to be no obligation to have proof(s). In that regard, the document seems to be a specification for credentials, only some of which are verifiable.

Yes, that was the intent. This point is being debated in #178.

[msporny]

Ok @vieillevigne, I have responded to every comment you made in your review. Most of them with changes, and when there were not changes, the response included the reason there were no changes.

Please review PR #179 ... diff-marked version here: https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/179/daed52d...352a574.html line by line diff here: https://github.com/w3c/vc-data-model/pull/179/files

Let me know if all of that satisfies your review comments (understanding that you can submit more comments at a later date).

[msporny]

All review comments have been processed and editorial changes have been made to the specification.