Naming classes of properties and syntax

[peacekeeper]

#455 introduced the concept of "representation properties". Per comments in that PR, we still wanted to discuss the exact terminology. I propose to distinguish properties and syntax according to 1. whether they are core, registered, or unregistered, and 2. whether they are representation-independent or representation-specific.

See this matrix:

Additional notes:

• We re-organize the DID Spec Registries to no longer use the term "Base properties" (since this isn't defined anywhere)
• We also introduce the term "representation-foreign syntax", but that's not a separate class. It's the same class as "representation-specific syntax" if that syntax show up in another representation (e.g. @context in a YAML DID document).

If people agree with this, I can do PRs to update DID Core and DID Spec Registries.

[OR13]

is there an example of "representation-independent syntax" ?

I think its probably safe to take a stab at a PR for this regardless.

[peacekeeper]

is there an example of "representation-independent syntax" ?

No there is no such thing, that would be a contradiction.

Based on the above diagram, we would have:

• Core Properties (representation-independent): id, alsoKnownAs, verificationMethod, service, ...
• Registered Properties (representation-independent): includes Core Properties, and also: ethereumAddress, ...
• Unregistered Propertes (representation-independent): foo, ...

and:

• Core Syntax (representation-specific): @context
• Registered Syntax (representation-specific): includes Core Syntax, and also: (nothing yet)
• Unregistered Syntax (representation-specific): %YAML, xmlns, ...

[talltree]

@peacekeeper, you nailed it. Great diagram (as always), and I'm totally aligned with your proposed terminology.

One question: do you think we need to add these to the terminology section? My gut feeling is no, but that we should introduce them (and I would even vote to include your diagram) in the Abstract Data Model section.

[iherman]

The issue was discussed in a meeting on 2020-11-24)

• no resolutions were taken

View the transcript

3. PR 454 and 455...

See github pull request #454, #455.

Brent Zundel: status update?

dlongely: we are waiting for a response from mike jones regarding the suggestions for adding a note to the PR / regardign @context in the JSON representation section.
… unsure if he is still objecting

Brent Zundel: I will ping him again

Markus Sabadello: after merging 455 and then 454 we still need to revisit the exact terminology... lots of different properties type to hammer down.

See github issue #463.

Markus Sabadello: feedback welcome

Brent Zundel: other PRs that need to be discussed in this meeting?

[kdenhartog]

@shigeya added this point over in #500

In Sec. 4 Data Model, the last statement of the second paragraph:

The second class of properties are called representation properties, and are specified in section § 6. Representations.

I think representation properties does not correctly express its property.

I propose adding -specific like representation -specific properties.

I'm moving here so #500 can be closed and the discussion is consolidated

[msporny]

Core Syntax (representation-specific): @context

The term "syntax" is misleading because it's being used in a vague manner... here are valid examples of syntax in JSON:

{ } , [ ] " :

These lexical tokens are also valid syntax (and we call them properties in the specification) -- "foo", "bar", "@context", etc...

It's only once you get into the semantics of the tokens where you can start differentiating... language syntax is typically composed of at least three layers, in order -- words, phrases, and context. I'd argue we're trying to name the third layer by referring to it as "syntax" -- it's not entirely wrong, but it is vague and misleading.

I think the last sentence of the issue that @peacekeeper raised identified a more accurate naming scheme:

they are representation-independent or representation-specific.

We don't do anyone any favors by adding more terminology than necessary to the specification... it makes it harder to grasp. So, let's just have these categories:

• Core Properties: id, alsoKnownAs, verificationMethod, service, ...
• Registered Properties: includes Core Properties, and also: ethereumAddress, ...
• Unregistered Properties: foo, ...

Then each representation, in it's Representation-specific section, can also add details about "representation-specific properties":

• Representation-specific Properties: @context (with an explanation that this is a "representation-specific property" that is expected to be preserved through data model consumption/production).

If we do this, we give the thing a name without requiring a vague new class of terms (syntax) or adding unnecessary subsections.

[msporny]

Representation-specific

Thinking about this a bit more... even this is a bit misleading -- @context can be used in JSON-only to trigger a JSON Schema check... so it's not only useful in JSON-LD, but is also useful in JSON (and CBOR-LD)... so it's not even representation-specific (which is why it was just a property before). That said, I don't think the distinction matters as much as just naming it using a single subclass of existing terminology in the specification.

[peacekeeper]

If we're now again calling @context or xmlns or %YAML "properties", then we're basically ignoring much of the ADM discussion of the TPAC F2F last November. The compromise was that those could be preserved across representations, but they would be called "syntax", not "properties". The diagram above reflects that.

E.g. see this resolution here: https://www.w3.org/2019/did-wg/Meetings/Minutes/2020-11-05-did#resolution5

• serviceEndpoint, verificationMethod, controller, etc. are "properties" in the DID document data model. They describe the subject or how to interact with the subject or controller.
• @context, xmlns, %YAML, etc. are representation-specific things ("syntax").

I suggest to not re-open this discussion again, and to not blur the lines between representation-independent properties that must work in all representations, and things that are only meaningful to certain representations...

[OR13]

The problem here is folks are conflating what an Object and a DID Document have inside them.

I suggest a special topic call dedicated to reviewing:

1. object properties
2. object members
3. object attributes
4. object predicates

See also:

• https://stackoverflow.com/questions/1235013/what-is-a-member-vs-a-property
• https://plato.stanford.edu/entries/properties/
• https://en.wikipedia.org/wiki/Attribute_(computing)

This problem didn't exist before we had an abstract data model, because everything was JSON, and the following definitions applied:

https://json-schema.org/understanding-json-schema/reference/object.html#:~:text=The%20properties%20(key%2Dvalue%20pairs,used%20to%20validate%20that%20property.&text=The%20additionalProperties%20keyword%20may%20be%20either%20a%20boolean%20or%20an%20object.

Sadly since the ADM is not RDF, we actually don't have a way of separating a "predicate" from a "attribute" or "member" or "property"... and all these words are now confusing because they are all abstract.

Luckily INFRA has the answer to this question, and if we don't agree this is the answer, we better re-evaluate infra.

according to our spec, a DID Document is an infra map

the word "property" is incorrectly used in the did core spec, maps have "keys" ... maps do not have "properties".... and in fact.... the word property only shows up when infra discusses serialization to json: https://infra.spec.whatwg.org/#serialize-a-javascript-value-to-a-json-string

I suggest we agree to the following:

1. A DID Document is an INFRA Map. (normative today)
2. A DID Document has "keys" that are representation specific or agnostic.
3. An example of a representation specific key is "%YAML"
4. An example of a representation agnostic key is "verificationMethod"

All instances of the word "property" are replaced with the word "key" when referring to the ADM, and are hyperlinked with the infra defintion of a map.

https://infra.spec.whatwg.org/#maps

This issue should be retitled naming classes of registered infra map keys used by did documents.

The word "syntax" is unhelpful and irrelevant.

[msporny]

A DID Document has "keys" that are representation specific or agnostic.

We avoided using the word "key" because it also contains public keys :) -- when we had this language before, multiple people noted how confusing it was... so I doubt we can go back to something people didn't want. I know I would probably object.... "Well, you see... there are /keys/ and then there are *keys*".

[msporny]

The word "syntax" is unhelpful and irrelevant.

+1, agreed.

An example of a representation specific key is "%YAML"
An example of a representation agnostic key is "verificationMethod"

+1, I'm supportive of representation-specific property and representation-agnostic property.

[OR13]

We avoided using the word "key" because it also contains public keys :)

The spec no longer defines publicKey, and uses the term verificationMethod... making this less of a concern, and if folks really want to use infra, we should be using it consistently, and not smudging terms like "map key" with words like "did document property"....

The group should use terms like "property" or "attribute" consistently... if folks don't want to use the term "property" for a key in an INFA Map that is "representation specific", they don't get to use the term for things that are "representation agnostic".

I personally think INFRA made the entire spec worse, but if we are going to use it, let's not use parts of it and not other parts.... a did document is an infra map, infra maps have keys.... not attributes or properties... every instance of the word "property" is bias towards JSON representations, which is attempted to remove when we introduced the ADM... the appeal of the word "property" is hold over from the time when everything was JSON. that time has passed... everything is now INFRA.

It is more confusing to use the term "property" for an "infra map key" in did core, than it is to use the infra definitions without modification in did core, if we are going to rename infra vocabulary in order to use it in did core, we should add a sectiton describing the name changes, to remove ambiguity... for example, we could say: "DID Documents are INFRA Maps, but we use the term "property" instead of map key, to avoid ambiguity"....then we can use the term "property" for any instance of "map key"....

Either we do that, and things like @context are a "property (aka map key) of a did document (aka infra map)... or we use the infra terms and stop using the term property.

personally, I would prefer to just use INFRA as it is, or not use it... I find redefining vocabulary to be one of the least helpful things that a spec can do.

[peacekeeper]

I agree with @OR13 on re-using INFRA terms and not changing them. I'd prefer something like this:

A DID document consists of a map of entries, where each entry consists of a key/value pair. The data model contains at least two different classes of entries. The first class of entries are representation-independent properties, and are specified in section § 5. Core Properties. The second class of entries are representation-specific syntax, and are specified in section § 6. Representations.

I think this would be consistent with the F2F discussions and also the diagram here in my first comment. This also enables the preservation of representation-specific syntax across different representations (even though personally I still have reservations about this).