Reviewer: Susan Hares
Review result: Has Issues
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. /
--
last-call mailing list -- last-call@xxxxxxxx
To unsubscribe send an email to last-call-leave@xxxxxxxx
