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

[Christer Holmberg <[e-mail]>]

Hi,

Below I will copy my comments on -15, and indicate whether I think they have been addressed in -16. My comments based on -16 are prefixed with "CHH-16".

GENERAL
========

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
==========

---

Q1: The document talks about “sdfObject instances”, “sdfThing instances” etc. What is the meaning of “instance” here? My understanding is that the concept of instance (as in a class-vs-instance context) is outside the scope of this document.

CHH-16: This has been addressed in -16.

---

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.

---

The text in Section 2.3. says:

        “Actions may be long-running, that is to say
        that the effects may not take place immediately as would be expected
        for an update to an sdfProperty; the effects may play out over time
        and emit action results.” 

Q3: Is there a way for a user to figure out whether an Action is still “ongoing”, or whether the Action execution has even started? If the answer is No, I think it would be good to point out.

CHH-16: This has been addressed in -16.

The text in Section 2.3. says:

        “Actions may also not always complete and
        may result in application errors, such as an item blocking the
        closing of an automatic door.

Q4: Is there a way for a user to figure out what the result of the Action was? I am not referring to Output data returned by the Action, but the result of the Action itself. If the answer is No, I think it would be good to point out. Related to Q3.

CHH-16: This has been addressed in -16.

---

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"?


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.

---

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?  

---

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".

---

The text in Section 1.1. says:

      “a router that employs both temperature sensors and indicator lights
      might exhibit less Thingness, as the effects of its functioning
      are mostly on the digital side.”

Q8: I can’t parse this sentence. The “less Thingness” and “mostly on the digital side” parts sound strange.

CHH-16: This has been addressed in -16.

---

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?

---

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.

---

The text in Section 1.1. says:

        “Objects are similar to Things but do not allow nesting, i.e., they cannot
        contain other Objects or Things.”

Q11: The definition of Thing earlier in the section does not say anything about nesting.

CHH-16: This has been addressed in -16, but I have an additional comment related to sdfObject vs sdfThing further down (Q26).

---

The text in Section 1.1. says:

        “(Note that JSON maps are often
        called JSON objects due to JSON's JavaScript heritage; in this
        document, the term Object is specifically reserved for the above
        grouping, even if the type name "object" might be imported from a
        data definition language with the other semantics.)”

Q12:  The document often says “JSON maps (objects)”. This is confusing, as the text in Section 1.1. indicates that “object” is something else. It would be more clear to say “JSON maps (JSON objects)”. However, I don’t think you need to do that. It is enough to ONCE in the document say that “JSON object” and “JSON map” means the same thing, and after that use ONE of them. This is an example of my comment in Q5.

CHH-16: This has been addressed in -16.

---

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. 

---

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.

---

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.

---

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.

---

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.

--

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.

---

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.

---

The text in Section 3 says:

   “SDF definitions are contained in SDF files.  One or more SDF files
   can work together to provide the definitions and declarations that
   are the payload of the SDF format.”

Q20: What is meant by “payload of the SDF format”? 

CHH-16: This has been addressed in -16.

Q21: What is meant by “SDF file”. Does this refer to the storage of SDF definitions in some database etc?

CHH-16: This has been addressed in -16.

---

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.

---

In Q11, I commented that the definition of Thing does not mention nesting. 
However, I think the issue may we larger than that.

The definition of Thing says:

      "a temperature sensor or a light might be a Thing, but a
      router that employs both temperature sensors and indicator lights
      might exhibit less Thingness"

The definition of Object says:

      "Objects are similar to Things but do not allow nesting, i.e., they cannot
      contain other Objects or Things."

Q23: The Object text implies that Things can be nested. But, the Thing text says that a temperature sensor might be a Thing. When would a temperature sensor be nested?

An sdfThing might be nested, but that is a separate thing. For example, I assume a router could be represented by an sdfThing, while the Thing text says that a router is "less Thingy".

CHH-16: This has been addressed in -16.

---

Q24: As mentioned earlier, "Object" is very overloaded. Section 1 says "SDF Object", but after that only "Object" is used. Please pick one.

CHH-16: This has been addressed in -16.

---

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?

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.

----

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, but why does the document use e.g., "sdfObject" and "sdfObject group" while referring (AFAIU) to the same thing?

----

Regards,

Christer