Define terminology for properties and values

[jricher]

Since a DID document is an abstract data model that consists of a collection of properties, we need a consistent way to refer to the parts of the property so that parts of the spec (like representations) can use them. For example, given a property like:

      <h2>DID Subject</h2>

      <p>
The <a>DID subject</a> is denoted with the <code>id</code> property. The
<a>DID subject</a> is the entity that the <a>DID document</a> is about. That is,
it is the entity identified by the <a>DID</a> and described by the
<a>DID document</a>.
      </p>

We need a way to refer to the string id as a specific entity. Is this the "property name"? Is this the "property" itself? Is it the "member label" or something else we make up? We also have to talk about things like the "property value" and the "property value data type". These terms all need to be defined and used consistently.

[jricher]

In addition, the document needs to define what an "empty" property value is.

[kdenhartog]

We discussed this on the call today. I'd be happy to assist in making this PR, but I think we need to bikeshed the terminology a bit. Bringing in the likes of @dmitrizagidulin @msporny @selfissued @dlongley to assist with some color options 😄

[rhiaro]

Partly addressed by text in PR #241: https://pr-preview.s3.amazonaws.com/talltree/did-core/pull/241.html#definition

[kdenhartog]

@iherman suggested that we not bikeshed this issue and instead use common language already defined. His suggestion was to use infra definitions which would leave us with "key" and "value".

See #241 (comment) for additional context.

Can we please get a rough strawpoll on this on the next call @burnburn @brentzundel and if it's agreed I'll go in and start the PR to update this in the spec?

[peacekeeper]

In the PR #247 about DID Resolution, when talking about metadata, I am using language such as

"These sets of metadata are expressed as maps of name-value string pairs, referred to as metadata properties."

I suppose this can perhaps also be improved, depending on the outcome of the discussion in this thread.

[burnburn]

@iherman suggested that we not bikeshed this issue and instead use common language already defined. His suggestion was to use infra definitions which would leave us with "key" and "value".

See #241 (comment) for additional context.

Can we please get a rough strawpoll on this on the next call @burnburn @brentzundel and if it's agreed I'll go in and start the PR to update this in the spec?

@kdenhartog name bikeshedding is horrible to do on a call (and that's what is likely at this point). Best would be first to have options listed in this issue, call it out on our call for people to respond, and only schedule call time if needed after responses in this issue.

[msporny]

We need to make the spec consistent in the way we talk about properties and their associated values. We went to great lengths to get alignment in the VC Data Model spec on this: https://www.w3.org/TR/vc-data-model/

This is how we solved the problem in the vc-data-model:

A property X has an associated value Y. X is the name of the property. Y is the value of the property. Together these are property-value pairs.

The formulation above is what we used in the VC Data Model (and it took a long time to get everyone aligned over there on the formulation above).

[kdenhartog]

@iherman suggested that we not bikeshed this issue and instead use common language already defined. His suggestion was to use infra definitions which would leave us with "key" and "value".
See #241 (comment) for additional context.
Can we please get a rough strawpoll on this on the next call @burnburn @brentzundel and if it's agreed I'll go in and start the PR to update this in the spec?

@kdenhartog name bikeshedding is horrible to do on a call (and that's what is likely at this point). Best would be first to have options listed in this issue, call it out on our call for people to respond, and only schedule call time if needed after responses in this issue.

Now that you point it out, I can see how this could become a timesink very quickly. I'll take the advice and list out a few options.

Option 1: property-value pairs
Align with VC data model spec language and use:

A property X has an associated value Y. X is the name of the property. Y is the value of the property. Together these are property-value pairs.

The formulation above is what we used in the VC Data Model (and it took a long time to get everyone aligned over there on the formulation above).

Option 2: name-value string pairs
Align with language used in PR #247

"These sets of metadata are expressed as maps of name-value string pairs, referred to as metadata properties."

Option 3: key-value pairs
Aligns with infra document

An ordered map, or sometimes just "map", is a specification type consisting of a finite ordered sequence of key/value pairs, with no key appearing twice. Each key/value pair is called an entry.

For option 1, please use the "Heart" emoji

For option 2, please use the "Rocket" emoji

For option 3, please use the "Hooray" emoji

We'll use this to get an indication of which has the greatest support. If you've got a strong argument against using one (where, you would indicate a -1 normally) please provide that argument in a comment below.

Hopes this polling mechanism will get us to a resolution faster without too many disagreements

[iherman]

@kdenhartog before we vote: we should note a slight difference with #241. This issue is a common terminology but #241 is, originally, about defining a full data model, that should include things like what is a 'map', what are the possible type values, etc. Ie, we should think about this when we vote.

[msporny]

-1 on name-value and and -1 on key-value. Remember that these are really 3-tuples, there is always a subject associated with the data (the DID). So, these are really subject-X-Y 3-tuples (I don't mean this in the RDF sense, I mean 3-tuple in the pure mathematical sense).

name-value is used by JSON, which is fine, but the JSON RFC does not consider a subject and we don't want people to confuse what we're doing in this spec with the JSON data model, which deals with 2-tuples in objects. Yes, you can use the JSON data model to express the DID Core data model, but there is an extra data item in the data we're representing.

key-value has the same problem, often used by systems that only consider a two-tuple instead of a three-tuple.

... and finally, in order to head off the "but this smacks of RDF favoritism, and I don't care about that!" -- if we wanted to pick the RDF terms, it would be subject-predicate-object, which would just confuse everyone that isn't from the RDF world, so let's not do that.

Over the years, subject-property-value has struck the right balance (and having written a fair number of specs with this language, and debated this exact question over the last decade or so, subject-property-value tends to lead to the least amount of confusion (based on reviewer feedback) around what we're talking about).

[jricher]

The language that we're talking about here is really a 2-tuple: the property itself consists of a name and value. The fact that it's been applied to a subject is external to that discussion.

[jricher]

Additionally, I would like to note that the VC text does call it "name-value", and not "property-value". There is a property, the property has a name and a value. When we talk about the left hand side only we say "name", when we talk about the right and side we say "value", when we talk about the whole thing together we use "property". VC incorrectly uses "property-value" terminology in spite of its own definitions and this mistake should not be repeated here.

[msporny]

Additionally, I would like to note that the VC text does call it "name-value", and not "property-value".

The only place where that happens in the VC spec is an editorial mistake. Here is how we use the naming pattern in the VC spec:

Verifiable credentials and verifiable presentations MUST have a type property.

The value of the type property MUST be, or map to (through interpretation of the @context property), one or more URIs.

EXAMPLE 5: Usage of the type property

There is a property, the property has a name and a value.

Agreed, or more specifically, there is a property name and a property value. Now it sounds like we're talking about the same end result working from different mental models.

When we talk about the left hand side only we say "name", when we talk about the right and side we say "value", when we talk about the whole thing together we use "property". VC incorrectly uses "property-value" terminology in spite of its own definitions and this mistake should not be repeated here.

Or... you could interpret it both ways and both would be correct. I've never interpreted it as you're interpreting it, but I can see how one could and not have the same internal mental model.

So, here's a rephrasing in an attempt to bring clarity to the mental model:

A property is at least an (X, Y) tuple. (this is new wrt. my mental model)
A property has a property name (X), and a property value (Y).

Examples of usage:

The foo property MUST be present.

The value of the foo property MUST be true.

The upside of this naming model is that it's also compatible with (S, X, Y) tuples -- ones that have a subject, which all DID Documents have.

[jricher]

+1 to use "property", "property name", "property value"

[kdenhartog]

Did we ever announce this on the call or reach a conclusion on this? It seems to be inconclusive to me still.

[iherman]

@kdenhartog see https://www.w3.org/2019/did-wg/Meetings/Minutes/2020-04-21-did#section3

Bottom line is: align with the terminology in VC.

[kdenhartog]

Thank you. I won't get around to this for at least 2 weeks, but it's higher on my list of things to get done and I have the expectation that I'll be doing it.

[OR13]

Related: https://w3c.github.io/did-core/#production

[rhiaro]

PR in for this ^, but not actually many changes. I'm assuming wording like "the type property" is reasonable shorthand for "a property with the name type" and haven't edited this.

I replaced "object" in the data model section with "set of properties" and "array of" or "list of" with "unordered set of", to better match the language in the Representations sections.

We don't have a definitive definition of an "empty property" though, which this issue also requests before we can close.