Re: Updated data model specification document

On 5/27/16 3:20 AM, Daniel Burnett wrote:
> Thanks Steven.  With the exception of 'TBD Credential', I think
> most of the confusion you describe is coming from the fact that the
> terms used are not all linked clearly and correctly.  This is a big
> item on my existing ToDo list.  It's compounded by the fact that we
> import definitions from another document that are then conflicting
> with definitions within the document.
>
> How about this:  when I think the references and definitions are
> all fixed I will ping you to look again.  Then we can see what else
> needs to be done.
>

Fine, I'll be happy to look. Two further points you might want to 
consider:

First, from my memory of my readings, it may help to define the terms 
before they are first used, rather than just linking them to a place 
later in the document where the definition is given.

This is standard practice is some places (patents, for instance, where 
I believe it's legally required), and I think this is done because it 
helps smooth the comprehension for those who are new to the terms.

To put it another way, a section of text that has, say, two new terms 
in it, both of which are linked to places later in the document where 
they are defined, can't be understood without juggling back and forth 
through the document at least twice.  Whereas if they're defined 
before the first use, at least there's a chance that the reader can go 
straight through.

Second, which I also remember from my first reading and have just gone 
back to the document to check: I'm uncomfortable with the fact that 
'id' is not differentiated in its different usages. Couldn't it be 
give an different name like "claimid"?  I found this disorienting -- 
if the 'id' for a claim is specific for claims, then shouldn't that be 
indicated?

And not just in reading the data description; I think this is a 
potential hotspot for confusion in writing the code. For example, to 
me the second example seems ripe for confusion:

Example 2: A simple claim

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

Perhaps this could be easier to code and parse, instead, if was:

Example 2: A simple claim

{
   "id": "http://example.gov/credentials/3732",
   "type": ["Credential", "ProofOfAgeCredential"],
   "issuer": "https://dmv.example.gov",
   "issued": "2010-01-01",
   "claim": {
     "claimid": "did:ebfeb1f712ebc6f1c276e12ec21",
     "ageOver": 21
   }
}


Steven


>
> -- dan
>
>> On May 26, 2016, at 3:04 PM, Steven Rowat
>> <steven_rowat@sunshine.net> wrote:
>>
>>> On 5/26/16 7:52 AM, Daniel Burnett wrote:
>>>
>>>
>>> On Wed, May 25, 2016 at 12:41 AM, Steven Rowat
>>> <steven_rowat@sunshine.net <mailto:steven_rowat@sunshine.net>>
>>> wrote:
>> ...>     In section 3.1, I became hopelessly confused.
>>>
>>> At first I was just confused, but I came back and tried that
>>> section again a few hours later, and now it's hopeless.  ;-) .
>>>
>>>
>>> I'm sorry to hear that.  Feel free to ask questions or make
>>> suggestions :)
>>
>> Right. I thought of that. :-) But didn't know how to ask about
>> that paragraph, which is:
>>
>> "Both identities and claims, including verifiable claims, consist
>> of a collection of name-value pairs which will be referred to as
>> <b> properties </b> in this document. The following subsections
>> describe the required and optional properties for both. The link
>> between the two is in the id property. An Identity data set
>> defines the identifier given in the id property, while a Claim
>> data set, referred to as a TBD Credential, uses the id property
>> to refer to the Identity data set that defines the given id
>> value."
>>
>> The final sentence in particular stumped me both times.
>>
>> I think my problems might be at different meta-levels; I'll call
>> them A and B.
>>
>> A. I think this entire document is probably intended for
>> specialists in the languages the data will be expressed in, and
>> as such I'm not an appropriate reader. I was fooled, perhaps, by
>> the plain language of the Abstract, which I think could be
>> appreciated by almost anyone.
>>
>> B. However, I think it's also possible that my confusion is
>> contributed-to by these things:
>>
>> i. "TBD Credentials", which is perhaps unavoidable but makes a
>> peculiar stumble in my mind each time I hit it.
>>
>> ii. The use of "properties" confused me. I think I'm unable to
>> model in my head where this fits. This sentence in section 3.2
>> about properties didn't help:
>>
>> "Unlike with claims, the properties in an Identity are merely
>> properties that, together with an identifier id, constitute an
>> identity. The properties are not claims and are not intended to
>> be verifiable."
>>
>> Is properties an official term, in the sense that it's the child
>> or parent of some other term? It only appears in descriptions,
>> not in the lists of terms. Yet it's bolded at the first
>> insertion, like the other defined terms that are listed (id,
>> type, signature, etc.). Is "properties" the parent of those other
>> terms?
>>
>> iii. That final sentence I referred to above: "An Identity data
>> set defines the identifier given in the id property, while a
>> Claim data set, referred to as a TBD Credential, uses the id
>> property to refer to the Identity data set that defines the given
>> id value."
>>
>> My problems with this were/are something along the lines of...
>> What is an 'Identity data set"? Is that the same thing as "a
>> collection of name-value pairs which will be referred to as
>> properties in this document", which you said in the previous
>> sentence? If so, I think you need to make this explicit, not
>> assumed. Especially since in the final sentence you've got 'id',
>> 'Identifier' and 'Identity' all used. Keeping those straight in
>> my mind...didn't happen, and probably won't unless I get a clear
>> and simple definition for each term before they're all used
>> together.  :-)
>>
>> Steven
>>
>
>

Received on Friday, 27 May 2016 15:31:36 UTC