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