Re: [Asdf] WGLC review of draft-ietf-asdf-sdf-16 (Christer)

[Carsten Bormann <[e-mail]>]

Hi Christer,

thank you for checking back on our treatment of your comments, and apologies for where we missed.  I have elided those parts of your email where the -15 comments seem to have been addressed in -16.

Changes for the below have been collected in

https://github.com/ietf-wg-asdf/SDF/pull/146

Grüße, Carsten


> CHH-16: There are a number of my comments that have NOT been addressed in -16, and no reason has been given on the list. If a comment has been discussed e.g., in GitHub, please provide a link to the associated GitHub Issue etc. However, for "archiving purpose", I think it would be good to get at least the final outcome to the comments also by e-mail.
> 
> 
> 
> TECHNICAL
> ==========
> 
> 
> ---
> 
> The text in Section 2.2. says:
> 
>              “sdfProperty is used to model elements of state within sdfObject instances.”
> 
> Q2: When I read "state" I start thinking about state machines. But, that is obviously not the type of state that the document is talking about (eventhough an sdfProperty could also be used to represent the state of a state machine). I can't think of a better word, but I just want to make sure that it is clear to everyone that the document does not restrict sdfProperty to state machine states.
> 
> CHH-16: This has NOT been addressed in -16. Having said that, I realize my understanding of "state" may differ from the meaning within the draft, so if the text is clear to everyone else I am fine with not addressing it.

We did change this to "elements of state within Things modeled	by the enclosing sdfObject.” which should make clear that we are talking about elements of state within Things.  I do think that this removes any connotation of state machines that might have been a result of “state within sdfObject instances”.

> ---
> 
> EDITORIAL
> =========
> 
> Q5: The draft has parts that are difficult to read e.g., because of inconsistent terminology. In addition, there is quite a bit of terminology overloading. For example, the draft use "object" in 3 different contexts: Object, JSON object and sdfObject. Another example is Thing and sdfThing: the document gives an example where a Thing could be a temperature sensor, but a temperature sensor would typically be represented as an sdfObject (not sdfThing).
> 
> CHH-16: This has partly been addressed in -16. However, there is still some confusion, as the document uses both Object and sdfObject to refer to the same thing, but in some cases one may think they are actually different things. See below for examples.
> 
> The text in Section 1.1. says:
> 
> "sdfObjects are similar to sdfThings but do not allow nesting, i.e., they cannot contain other Objects or sdfThings."
> 
> This sentence contains both sdfObject and Object, which may confuse the reader. Why not say "cannot contain other sdfObjects"?

We since introduced the term “grouping” to clean up the wording this somewhat (dda031d).

> The text in Section 2.1. says:
> 
> "The sdfObject group lists the affordances of Things modeled by this Object."
> 
> Why not say "modelled by this sdfObject"?
> 
> 
> The text in Section 2.2.1. says:
> 
> "Objects, the items listed in an sdfObject group"
> 
> This is confusing, as it seems like Objects are something contained within an sdfObject.

OK, we broke down and replaced all Object by sdfObject, except where different objects (e.g., OMA) are meant.  We do explain that people will still say “Object” as a shorthand.

Now
17a3666



> Q6: In a number of places the document talks about “the current version of SDF” and “the present version of SDF”. What is meant by “version of SDF”?
> Section 1 mentions “SDF 1.0” and “SDF 1.1” labels, but when referring to the document refers to the draft number (-15). If this document going define some new version label for SDF?
> 
> CHH-16: This comment has been partly addressed in -16. However, related to the versioning, the document a version Quality, and talks about using the date for Version. While the usage of date is not mandated, I wonder what the difference between Version and Modified? Is there a reason to allow "anything that can be incrementable", and then require the one defining the model to explain how the incrementation is done? Why not simply use an Integer?  

Version identifiers are very different in different environments.
We are not trying to tell people how to do their versioning.
We do provide a “modified” field that is independent of the versioning scheme to provide a date/time.

> ---
> 
> The text in Section 1 says:
> 
>  “The Semantic Definition Format (SDF) is a format for domain experts
>  to use in the creation and maintenance of data and interaction models
> in the Internet of Things.” 
> 
> Q7: What is meant by “in the Internet of Things”?
> 
> CHH-16: This has partly been addressed in -16, but I note that Section 7.1 also uses "in the Internet of Things".

This needs to be a short phrase, and we can’t add a few term definitions, so we say:

in the Internet of Things and related environments


> 
> 
> ---
> 
> The text in Section 1.1. says:
> 
>     "Affordance:  An element of an interface offered for interaction,
>     defining its possible uses or making clear how it can or should be
>     used.  The term is used here for the digital interfaces of a Thing
>     only; it might also have physical affordances such as buttons,
>     dials, and displays."
> 
> Q9: It's hard to understand the “making clear how it can or should be used” part within the context of the sentence. Can it be removed?
> 
> CHH-16: I see the text has been modified in -16, but unfortunately I still think it is hard to understand. Would it be possible to simply say "An element of an interface offered for interaction", or to remove the "defining its possible uses or making clear how it can or should be used" part?

But that is the point — the affordance affords its use.
I’m sure this can be explained better, but not by leaving out this distinguishing aspect.

> 
> ---
> 
> The text in Section 1.1. says:
> 
>       “An entry in the main SDF map…” 
> 
> Q10: What is an SDF map?
> 
> CHH-16: This has NOT been addressed in -16.

Indeed.  We focused on getting the use of JSON map right, but not at this specific place.

-: An entry in the main SDF map and in certain nested definitions that
+: An entry in the main JSON map representing the SDF document, and in
+  certain nested definitions, that

> ---
> 
> The text in Section 1.1. says:
> 
>       “Protocol Binding:  A companion document to an SDF specification that
>       defines how to map the abstract concepts in the specification into
>       the protocols in use in a specific ecosystem.”
> 
> Q13: The sentence itself is fine, but I think it should earlier in the document (Section 1) be described that SDF is “Abstract”, and does not contain protocol bindings.
> 
> CHH-16: This has NOT been addressed in -16. 

Now
901c494

> ---
> 
> The text in Section 2.2.1. says:
> 
>  “Objects, the items listed in an sdfObject group, are the main "atom"
>  of reusable semantics for model construction.” 
> 
> Q14: It's hard to understand the sentence.
> 
> CHH-16: This has NOT been addressed in -16. It is still difficult to understand the sentence. Also, as commented further down (Q27), it is unclear what an "sdfObject group" is.

Added “definition” to “group”.

Now
593ec33


> ---
> 
> The text in Section 2.2.1. says:
> 
>  “An sdfObject contains a set of sdfProperty, sdfAction, and sdfEvent
>  definitions that describe the interaction affordances associated with
>  some scope of functionality.”
> 
> Q15: Should the same thing be said about an sdfThing? I.e., an sdfThing can contain a set of sdfObjects with a shared scope.
> 
> CHH-16: This has NOT been addressed in -16.

Right.  Now
fd9543b

> ---
> 
> Q16: The text in Section 2.2.1. says that sdfObject definitions should be kept narrow in scope in order to enable reuse and interoperability. This is the first time (unless I have missed it) that “reuse” and “interoperability” are mentioned in the document, eventhough reuse and interoperability are 2 of the main reasons why one would use SDF. I think Section 1 should talk more about that.
> 
> CHH-16: This has NOT been addressed in -16.

Indeed, we could have a (sub)section about objectives.
Writing a new one from scratch is a bit beyond what can be done immediately, though.  We also might need to go through another round of WGLC.
So we would like to refrain from this now and rather keep further develop this information on onedm.org and similar sites.

> 
> The text in Section 2.2.2. says:
> 
>  “An instance of sdfProperty may be associated with some protocol
>  affordance to enable the application to obtain the state variable
>  and, optionally, modify the state variable.  Additionally, some
>  protocols provide for in-time reporting of state changes.  (These
>  three aspects are described by the qualities readable, writable, and
>  observable defined for an sdfProperty.)”
> 
> Q17: Earlier the document talked about “protocol bindings”, and now “protocol affordance”. An example of my comment in Q5. Also, I think it is enough that the document ONCE describes that protocol bindings are needed in order to actually interact with SDF models, so I don't think the text needs to be repeated here. See my comment in Q13.
> 
> CHH-16: This has NOT been addressed in -16.

We don’t agree that this sentence is redundant.
It also leads in to the initial exposition of readable/writable/observable.
So we would like to keep it.

> --
> 
> The text in Section 2.2.2. says:
> 
>  “Definitions in sdfProperty groups include the definitions from
>  sdfData groups, however, they actually also declare a Property with
>  the given qualities to be potentially present in the containing
>  Object.”
> 
> Q18: I can’t parse the text beginning with “they actually also…”.
> 
> CHH-16: This has NOT been addressed in -16.

Right.  Now
cb52004

> ---
> 
> The text in Section 2.2.2. says:
> 
>  “For the data definition within sdfProperty or sdfData, SDF borrows
>  some vocabulary proposed for the drafts 4 and 7 of the json-
>  schema.org "JSON Schema" format (collectively called JSO here),
>  enhanced by qualities that are specific to SDF.”
> 
> Q19: What are “drafts 4 and 7”? Are you referring to different versions of some JSON schema document? Please add references.
> 
> CHH-16: This has been addressed in -16. I do note that the referenced drafts expired 10 years ago, but I assume they are still used.

Well, we started with draft 7, but found that some implementers used draft 4.  We got rid of the latter parts of the spec.
The coexistence of different versions is the state of the art in the json-schema.org environment.
That’s why we defined what we actually use in Appendix C.

> 
> Q22: Regarding "Thing", isn't that a generic IoT term, defined elsewhere? Is there a need for a specific SDF definition?
> 
> CHH-16: I see that the definition text for "Thing" has been reduced in -16. I still wonder whether there is a generic definition that could be used, but I am fine if the WG wants to explicitly define it in the draft.

A more precise generic definition is the matter of much discussion; instead of picking one that is citable, it is simpler to make a concise definition here.

> ---
> 
> Q26:
> 
> The text in Section 1.1. says:
> 
>   "sdfThing:  A grouping of sdfObjects (Objects) and/or sdfThings."
> 
> The text in Section 1.1. says:
> 
>   "sdfObjects are similar to sdfThings but do not allow nesting,"
> 
> The text in 2.2.6. says:
> 
>  "sdfThing groups, however, also allow for including interaction affordances, sdfData, as well as minItems and maxItems
>  qualities."
> 
> The definition of sdfThing in Section 1.1. seems to indicate that it is ONLY a grouping mechanism, which it is later indicated that sdfThings can also contain interaction affordances etc, similar to sdfObjects. Perhaps that should be made clear in the sdfThing definition?

Now:

sdfThing:
: A grouping of Groupings as well as potentially Affordance
 declarations (Property, Action, and Event declarations).


> The text in Section 2.2.2. says:
> 
>  "sdfProperty is used to model elements of state within Things modeled by the enclosing sdfObject."
> 
> Based on my comment above, shouldn't the text say "modeled by the enclosing sdfObject or sdfThing"? The same applies to sdfEvent, sdfAction etc.

Using the new term “grouping”, we now changed this to:

`sdfProperty` is used to model elements of state within Things modeled by the enclosing grouping.
Now
c55203c

> 
> ----
> 
> Q27: Related to my earlier comment on consistent terminology, the document uses "sdfObject group", "sdfThing group", "sdfAction group". I understand that sdfThings, sdfObjects etc are used to group things,


A (definition) group is the place in the SDF document where the definitions are made.

> but why does the document use e.g., "sdfObject" and "sdfObject group" while referring (AFAIU) to the same thing?

They are not the same thing (an SDF definition group might have many sdfObject declarations.  Where does it seem they are?


Thank you again for all these observations!