Skip to main content

Last Call Review of draft-ietf-asdf-sdf-18
review-ietf-asdf-sdf-18-opsdir-lc-hares-2024-06-12-00

Request Review of draft-ietf-asdf-sdf
Requested revision No specific revision (document currently at 18)
Type Last Call Review
Team Ops Directorate (opsdir)
Deadline 2024-05-22
Requested 2024-05-08
Authors Michael Koster , Carsten Bormann , Ari Keränen
I-D last updated 2024-06-12
Completed reviews Genart Last Call review of -18 by Mallory Knodel
Secdir Last Call review of -18 by Magnus Nyström
Artart Last Call review of -18 by Harald T. Alvestrand
Opsdir Last Call review of -18 by Susan Hares
Assignment Reviewer Susan Hares
State Completed
Request Last Call review on draft-ietf-asdf-sdf by Ops Directorate Assigned
Posted at https://mailarchive.ietf.org/arch/msg/ops-dir/Uoncu5_lWd65LehKJBamMbWuy88
Reviewed revision 18
Result Has issues
Completed 2024-06-12
review-ietf-asdf-sdf-18-opsdir-lc-hares-2024-06-12-00

Editorial #1, Introduction, paragraph 1 

overall: Very interesting work. The authors have tackle a major project.
Thank the authors for their hard work.  

Major Issue: Text is unclear to a non-WG reviewer.   
Due to the lack of clear definitions and discussions, 
I have done "my best" to try to suggest the errors. 

Issues: I have listed 40 editorial/clarity issues.


Issues 
==== 
#1 Introduction, editorial 

Run-on sentence:/
   The Semantic Definition Format (SDF) is a format for domain experts
   to use in the creation and maintenance of data and interaction models
   that describe Things, i.e., physical objects that are available for
   interaction over a network. /
   
Sue-1: The author should make this into two sentences. 

   An SDF specification describes
   definitions of SDF Objects/SDF Things and their associated
   interactions (Events, Actions, Properties), as well as the Data types
   for the information exchanged in those interactions.  Tools convert
   this format to database formats and other serializations as needed.

#2 Introduction, editorial 2 
Old text:/

   // The present revision (-18) adds security considerations, a few
   // editorial cleanups, discusses JSON pointer encodings, and adds
   // sockets to the CDDL for easier future extension.
/

Sue-1: I'm assuming this will be removed before 

#3: Introduction,  Editorial, confusing text due to ";", rework  
   SDF is designed to be an extensible format.  The present document
   constitutes the base specification for SDF; we speak of "base SDF"
   for short.  
   
#4: Introduction, Editorial/Technical,  what does "it may be necessary imply here", 

Old text:/ For other
   extensions, it may be necessary to indicate in the SDF document that
   a specific extension is in effect; see Section 3.1 for details of the
   features quality that can be used for such indications.  With
   extension points and feature indications available, base SDF does not
   define a "version" concept for the SDF format itself (as opposed to
   version indications within SDF documents indicating their own
   evolution, see Section 3.1).

#5 - 1.1.  Terminology and Conventions, please alphabetize the terms 
 comment for whole section: Please alphabetize terms. 

#6 - Section 1.1, Clarity of key term, Editorial/Technical 

Old/ 
   Affordance:  An element of an interface offered for interaction, for
      which information is available (directly or indirectly) that
      indicates how it can or should be used.  The term is used here for
      the digital (network-directed) interfaces of a Thing only; it
      might also have physical affordances such as buttons, dials, and
      displays.
/ 

Comment no the first sentence: 
   Affordance:  An element of an interface offered for interaction, for
      which information is available (directly or indirectly) that
      indicates how it can or should be used. /
	  
What does "for interaction, for which information" mean?
 I think you mean that you have a piece of data and 
 you are trying to describe appropriate usage. 
 
 new text / The term is used here for the digital (network-directed) 
      interfaces of a Thing only.  The digital interfaces may also 
	  be substantiated into physical realities (denoted as physical
	  affordances) such as buttons, dials, and displays./ 


#7, Section 1.1, Block, Grammar, verb tense agreement 

Old text:/
       Block:  One or more entries in a JSON map that is part of an SDF
      specification; these entries together serve a specific function./
	  
Sue-1: In English Grammar when you must have noun-verb alignment. 
If you have singular and plural noun as compound noun, you use a plural verb. 
suggested change: /is part/ are part/ 

#8, Section 1.1, Group, Punctuation makes definition unclear. 

old text:/
   Group:  An entry in the main JSON map representing the SDF document,
      and in certain nested definitions, that has a Class Name Keyword
      as its key and a map of named definition entries (Definition
      Group) as a value./

What do nested definitions do?  It is unclear how it impacts the group definition. 

#9, Section 1.1, Property, Grammar and Punctuation with ";" makes it difficult to understand 

Old text:/
   Property:  An affordance that can potentially be used to read, write,
      and/or observe state (current/stored information) on an sdfObject.
      (Note that Entries are often called properties in other
      environments; in this document, the term Property is specifically
      reserved for affordances, even if the map key "properties" might
      be imported from a data definition language with the other
      semantics.)/

Sue-1: Rewrite (Note... ) - into a clear concept of what the relationship 
    between an entry and a property is.  It might be useful to write a 
	definition of an entry and then put a improved note after property.

#10, Section 1.1, Object, Unclear definition 

Old text: /  
   Object, sdfObject:  A grouping containing only Affordance
      declarations (Property, Action, and Event declarations); the main
      "atom" of reusable semantics for model construction. sdfObjects
      are similar to sdfThings but do not allow nesting, i.e., they
      cannot contain other Groupings (sdfObjects or sdfThings). /
	  
Sue-1: I understand that Object, sdfObjects are fundamental "atoms" in 
       the architecture.  However, it is difficult to parse and understand
	   this key definition. I cannot tell if it is the concept, the English,
	   or both. 
	   
#11, Section 1.1, Element, Unclear Text/Grammar 

Old text:/
   Element:  A part or an aspect of something abstract; used here in its
      usual English definition.  (Occasionally, also used specifically
      for the elements of JSON arrays.)/
Comment: I've got 3 definitions that you might use "part of an abstract concept",
       "usual English Definition", and specific elements of JSON arrays. 
	   How do I use a definition like this to understand the document's text. 
	   
#12, Section 1.1, Definition, Unclear Text 

Old text:/
   Definition:  An entry in a Definition Group; the entry creates a new
      semantic term for use in SDF models and associates it with a set
      of qualities.  /

Here the ";" grammatically indicates the two halfs of the sentence are parallel  
statements about the same thing. This grammatical usage makes it very unclear what
a definition is. 

Part 2:/	  
	  Unless it is also a Declaration, a definition just
      defines a term, it does not create a component item within the
      enclosing definition./
Sue: 
How do I tell when a declaration is also a definition?  Is there a section 
the text shoudld refer to. 

#13, Section 1.1, Grammatical, unclear text and unclear concept. 

Old text;/   Declaration:  A definition within an enclosing definition, intended
      to create a component item within that enclosing definition.
      Every declaration can also be used as a definition for reference
      in a different place./

New text:/Declaration:  A definition within an enclosing definition which is intended
      to create a component item within that enclosing definition./
	  
Unclear concept: How do you define when it is "different place" in the 
     concept of this statement.  What creates the boundaries of a "place"?
	 
#14 - section 1.1, Grammatical, unclear text and concept. 

Old text:/
   Protocol Binding:  A companion document to an SDF Model that defines
      how to map the abstract concepts in the model into the protocols
      in use in a specific ecosystem.  Might supply URL components,
      numeric IDs, and similar details.  Protocol Bindings are one case
      of an Augmentation Mechanism./
	  
What entity "Might supply URL components, ..."/ Do you mean the 
    companioni document, the SDF model or something else? 

#15 section 1.1, Grammatical, unclear definition 

   Old text:/   Augmentation Mechanism:  A companion document to a base SDF Model
      that provides additional information ("augments" the base
      specification), possibly for use in a specific ecosystem or with a
      specific protocol ("Protocol Binding"). / 

    what does the phrase "possibly for use" mean? Pleae rework. 


#16, section 2.1, Clarity 

Old text:/
   current state of the Property named value.  (The third type of
   affordance is Events, which are not described in this example.)/ 
   
Sue-1: Why did you not include events in this example or a second example./ 
   IMHO, events are the harder concept to grasp. 

#17, section 2.2.2 sdfProperty, paragraph 3, Clarity of text   

Old text:/
   Definitions in sdfProperty groups include the definitions from
   sdfData groups, however, they actually also declare that a Property
   with the given qualities potentially is present in the containing
   sdfObject./
   
 Did you just miss a period (sdfData groups. However)? Otherwise,, 
 I cannot parse this sentence.  It is important since this gives a key concept. 
 
 
 #18, section 2.2.2, sdfProperty, paragraph 4, clarity of text
 
 Old text:/
   For definitions in sdfProperty and sdfData, SDF provides qualities
   that can constrain the structure and values of data allowed in the
   interactions modeled by them, as well as qualities that associate
   semantics to these data, such as engineering units and unit scaling
   information./ 
   
  text offset by commas (/as well as qualities that associate
   semantics to these data/) is suppose to be non-critical to the 
   sentence.  In your sentence, it appears to be critical to the concept. 
   Help! 
   
 New text:/
   For definitions in sdfProperty and sdfData SDF provides qualities
   that can constrain the structure and values of data allowed in the
   interactions modeled by them. sdfProperty also describes qualities that associate
   semantics to these data such as engineering units and unit scaling
   information./ 

#19, section 2.2.3, sdfAction, Clear definition of action.  


2.2.3.  sdfAction, paragraph 1, unclear  

Old text: 
   /The sdfAction group contains declarations of Actions, model
   affordances that, when triggered, have more effect than just reading,
   updating, or observing Thing state, often resulting in some outward
   physical effect (which, itself, cannot be modeled in SDF).  From a
   programmer's perspective, they might be considered to be roughly
   analogous to method calls./
 
Sue's  
   Concept of actions in Yang or data modeling is of something that 
   does more than reading or updating a value.  An action may report 
   status or do a particular program method. It is unclear what observing means. 
   If observing a critical concept, it should be defined prior to this definition. 

#20, Section 2.2.3, sdfAction, paragraph 2-5, unclear grammar and text 
   
 Old text:/
    Actions may have data parameters; these are modeled as a single item
   of input data and output data, each. /
   
   Sue-Comment: English grammar points out that a ";" signals two clauses that
   are paralel.  How does this text provide parallel comment. 
   This lack of correct grammar or clear text leaves an important 
   concept confused. 
   
   Key concept in (..): 
   Old text:/ (Where multiple parameters need
   to be modeled, an "object" type can be used to combine these
   parameters into one.)/
   
   Sue-Comment: This is an important concept.  It is worth more than 
   bundling into a paragraph in (...). Please expand on this concept with 
   more descriptions in the texxt.  
   
   text:/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. /
   
   Sue-Comment: ";" in this sentence makes it unclear.  
   Actions do take time to function in Yang models and in sdfAction. 
   Responses from actions may pop up after time has passed. 
   More detail is needed on the following: 
     a) Actions that immediately response (successfully or unsuccessfully) 
	 b) actions that complete successfully after time (successfully or unsuccessfully) 
	 c) actions that do not report status, and 
	 c) a sequence of actions (action chains) that have the first action fail. 
   
   The text below starts to explain 
   in terms of a URI for Ephemeral action resource. 
   
   Text in draft:/
   One idiom for giving an action initiator status and control about the
   ongoing action is to provide a URI for an ephemeral "action resource"
   in the sdfAction output data, allowing the action to deliver
   immediate feedback (including errors that prevent the action from
   starting) and the action initiator to use the action resource for
   further observation or modification of the ongoing action (including
   canceling it).  Base SDF does not provide any tailored support for
   describing such action resources; an extension for modeling links in
   more detail (for instance, [I-D.bormann-asdf-sdftype-link]) may be
   all that is needed to fully enable modeling them.

   Actions may have (or lack) qualities of idempotence and side-effect
   safety./
   
   Sue's comment: If you are using the qualities of "idempotence" and
   "side-effect safety", these need to be defined before this point. 
   
   Sue's comment: Is the text below trying to tell me about what the constraints 
   for modeling and semantics are outside the context of this draft 

   /Base SDF only provides data constraint modeling and semantics for the
   input and output data of definitions in sdfAction groups.  Again,
   data definitions for payloads of protocol messages, and detailed
   protocol settings for invoking the action, are expected to be part of
   the protocol binding./
   

#21, 2.2.4.  sdfEvent, incorrect grammar usage in ";"

old text:/
   The sdfEvent group contains declarations of Events, which can model
   affordances that inform about "happenings" associated with a Thing
   modeled by the enclosing sdfObject; these may result in a signal
   being stored or emitted as a result./ 
   
new text:/
   The sdfEvent group contains declarations of Events, which can model
   affordances that inform about "happenings" associated with a Thing
   modeled by the enclosing sdfObject. These "happenings" may result in a signal
   being stored or emitted as a result./ 

#22, 2.2.5.  sdfData, Nice phrase 

Nice sentence:/ The sdfData definitions only spring to life by
   being referenced in one of these contexts (directly or indirectly via
   some other sdfData definitions)./

   It is a common use case for such a data definition to be shared
   between an sdfProperty item and input or output parameters of an
   sdfAction or output data provided by an sdfEvent. sdfData definitions
   also enable factoring out extended application data types such as
   mode and machine state enumerations to be reused across multiple
   definitions that have similar basic characteristics and requirements.

#23, 2.2.6.  sdfThing, clear grammar

Old text:/ Like sdfObject, sdfThing groups also allow for
   including interaction affordances, sdfData, as well as "minItems" and
   "maxItems" qualities. /
New text:/ Like sdfObject, sdfThing groups allow for the 
   inclusion of interaction affordances, sdfData, as well as "minItems" and
   "maxItems" qualities. /

#24,  2.3.3.  Extensibility of Given Names and Quality Names, 

Comment: in the text below "Quality Names:"

text:/
   In SDF, both Quality Names and Given Names are _extension points_.
   This is more obvious for Quality Names: Extending SDF is mostly done
   by defining additional qualities. /
   
What does "Quality Names:" mean? 

#25, 2.3.3, paragraph 2, run-on sentences, lack of clarity 

Please remove ";" and break this into clear sentences 

text:/  Names with $ signs are intended
   to be used for functions separate from most other names; for
   instance, in this specification $comment is used for the comment
   quality (the presence or absence of a $comment quality does not
   change the meaning of the SDF model).  Names that are composed of
   multiple English words can use the "lowerCamelCase" convention
   [CamelCase] for indicating the word boundaries; no other use is
   intended for upper case letters in quality names.

#25, 2.3.3, paragraph 3, run-on sentences, lack of clarity 

Old text:/ Quality Name Prefixes are registered in the "Quality Name Prefixes" sub-registry
   in the "SDF Parameters" registry (Section 7.4.1); they are composed
   of lower case ASCII letters and digits, starting with a lower case
   ASCII letter (i.e., using a pattern of "[a-z][a-z0-9]*")./
   
What does ";" mean in this sentence.  Why not 2 sentences. 

#26, 2.3.3 Given names, grammar 

text: "Some styles also allow a dot . in given names. 
new text: "Some styles also allow a dot (".") in given names. 
comment: Grammatical error. 

#27, Section 3, paragraph 1, run-on sentence 

text-1:/Definitions and
   declarations from additional SDF documents can be referenced;
   together with the definitions and declarations in the referencing SDF
   document they build the SDF model expressed by that SDF document./

Comment: What does the semi-colon in this sentence do? I'm confused. 

#28, 3.3.  Definitions block

old text:/
   The Definitions block contains one or more groups, each identified by
   a Class Name Keyword (there can only be one group per keyword; the
   actual grouping is just a shortcut and does not carry any specific
   semantics).  /
Sue's comment:  I'm not sure what this means about the parameters of the 
  definitions block.  I realize "groups" are short cuts.  However, 
  what are you tryig to tell me about definitions in this text. 
  
  #29, 3.3.3 paragraph 6, what does "Entries within sdfData are not" mean? 
  
  text: 
  / Entries within sdfProperty,
   sdfAction, and sdfEvent, in turn within sdfObject or sdfThing
   entries, are declarations; entries within sdfData are not.
   Similarly, sdfObject or sdfThing entries within an sdfThing
   definition specify that the interactions offered by a Thing modeled
   by this sdfThing include the interactions modeled by the nested
   sdfObject or sdfThing./
   
  Sue: 
  This text block is confusing on what is declarations, definitions. 
  Please consider rewording 

#30 Section 4.2 Contributing global names, paragraph 2, Grammar/Clarity 

Old text:/
   The absolute URI part is a copy of the default namespace, i.e., the
   default namespace is always the target namespace for a name for which
   a definition is contributed.  When emphasizing that name definitions
   are contributed to the default namespace, we therefore also call it
   the "target namespace" of the SDF document./
   
What does "i.e." do for hte sentence?  It confuses me.  
What happens when you are not "emphasizing the name definitions?"


#31, 4.3.  Referencing global names, paragraph 1, clarity of text

text:/
   A name reference takes the form of the production curie in
   [W3C.NOTE-curie-20101216] (note that this excludes the production
   safe-curie), but also limiting the IRIs involved in that production
   to URIs as per [RFC3986] and the prefixes to ASCII characters
   [RFC0020]./
   
  Sue's comment: The text "(note that this excludes the production
   safe-curie)," placed in the text is confusing.  Could you rework this 
   paragraph to put it at the end.  What is the "productio safe-curie). 
   
#32, 4.4  sdfRef, paragraph 3, clarity, Grammar 

  text:/
   Note that the formal syntaxes given in Appendices A and B generally
   describe the _result_ of applying a merge-patch; the notations are
   not powerful enough to describe, for instance, the effect of null
   values given with the sdfRef to remove members of JSON maps from the
   referenced target. /
   
   Sue's comment: What does this ";" imply.  I'm confused what you are 
   trying to tell me about merge-patches versus "null" values for
   removal of members. 
   
 
 #33, 4.5.  sdfRequired

Text paragraph 3 tries to tell me two forms for abbreviated references.

What does this following mean with the ";" 

text:/
   References in this array can be SDF names (JSON Pointers), or one of
   two abbreviated reference formats:
   *  a text string with a "referenceable-name", i.e., an affordance
      name or grouping name.  /

Sue's: What does ",i.e., an affordance name or grouping name". 
       Perhaps a better definition of affordance would help me here. 


#34, 4.7.1.  sdfType, 2nd to last paragraph

old text:/ Note that SDF
       processors are not expected to (and normally SHOULD NOT)
       dereference these URIs (see also [I-D.bormann-t2trg-deref-id]);
       they may be useful to humans, though. /
	   
	   Sue's commment: This is a bit dense. Perhaps you can unpack this
	   sentence into multiple sentences. 

  

#35, 5.5.  sdfData, 2nd paragraph

Old text:/
   It is not itself a declaration, i.e., it does not cause any of these
   data items to be included in an affordance definition./
   
new text:/
   sdfData is not itself a declaration and it does not cause any of these
   data items to be included in an affordance definition./



#36, 6.  High Level Composition, 2nd paragraph 

Old text:/
   *  The ability to compose a reusable definition block from
      sdfObjects, for example a single plug unit of an outlet strip with
      on/off control, energy monitor, and optional dimmer sdfObjects,
      while retaining the atomicity of the individual sdfObjects./
New text:/
   *  The ability to compose a reusable definition block from
      sdfObjects. For example a single plug unit of an outlet strip with
      on/off control, energy monitor, and optional dimmer sdfObjects,
      while retaining the atomicity of the individual sdfObjects./

Sue's commment: Changing from 1 run-on sentence to 2 sentences helps clarity.

#37, Section 6, high Level Composition, 4th bullet.

Old text:/
   *  The ability to reference items in one part of a complex definition
      from another part of the same definition, for example to summarize
      the energy readings from all plugs in an outlet strip./
New text:/
   *  The ability to reference items in one part of a complex definition
      from another part of the same definition. For example to summarize
      the energy readings from all plugs in an outlet strip./  

#38, 6.2.1., paragraph 3  

 Text 1: /
   Note that if the referenced definition contains qualities or
   definitions that are not valid in the context where the sdfRef is
   used (for instance, if an sdfThing definition would be added in an
   sdfObject definition), the resulting model, when resolved, may be
   invalid./
 Improved text:/
   Note that if the referenced definition contains qualities or
   definitions that are not valid in the context where the sdfRef is
   used. For instance, if an sdfThing definition would be added in an
   sdfObject definition) the resulting model, when resolved, may be
   invalid./
   
 Sue: If this is incorrect, please rework the paragraph4, It has 
      long run-on sentences.  I 
 
#38, 6.2.1., paragraph 4, lots of run-on sentences. 

Paragraph 4:/

   As a convention, overrides are intended to be used only for further
   restricting the set of data values, as shown in Figure 5: any value
   for a cable-length also is a valid value for a length, with the
   additional restriction that the length cannot be smaller than 5 cm.
   (This is labeled as a convention as it cannot be checked in the
   general case; a quality of implementation consideration for a tool
   might be to provide at least some form of checking.)  Note that a
   description is provided that overrides the description of the
   referenced definition; as this quality is intended for human
   consumption there is no conflict with the intended goal./ 

#39, 6.3.  sdfThing, run-on 

   old text:/
   For example, the sdfObject declarations
   that make up the definition of a single socket of an outlet strip
   could be encapsulated in an sdfThing, which itself could be used in a
   declaration in the sdfThing definition for the outlet strip (see
   Figure 6 in Appendix D.1 for an example SDF model)./
   
   Please break this into multiple sentences.  I cannog parse it. 
   
#40, Sections 7.1, 7.2, and 7.3 - RFC xxxx 

What is the "RFC XXXX" mean? Are you referring to this document? 
If so the norm is [this document]. 

#41, Section 8, paragraph 1, concepts 

old text:/
   Some wider security considerations applicable to Things are discussed
   in [RFC8576].  Section 5 of [RFC8610] gives an overview over security
   considerations that arise when formal description techniques are used
   to govern interoperability; analogs of these security considerations
   can apply to SDF./
   
 Sue's - you've reference 3 concepts, but I cannot tell how these 
   impact the security of your models 

#41, Section 8, paragraph 2, editorial, 

old text:/  SDF uses JSON as a
   representation language; for a number of cases [RFC8259] indicates
   that implementation behavior for certain constructs allowed by the
   JSON grammar is unpredictable.  /
   
new text:/SDF uses JSON as a
   representation language. For a number of cases [RFC8259] indicates
   that implementation behavior for certain constructs allowed by the
   JSON grammar is unpredictable.  /