Subject: [netmod] AD review of draft-ietf-netmod-geo-location-07

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Sun, 7 Mar 2021 20:48:13 +0000

Hi Chris,

Apologies for the delayed AD review of this document.

I found that this document to be interesting, enlightening, and well written, so thank you.

I only have a few minor comments, the rest are grammatical nits. Some I spotted manually; the rest are from a beta version of a grammar tool that I am playing with.

Minor comments/questions:

1.
In the YANG module, the pattern statements have 3 ranges of characters,
but the description only indicates two ranges.  Is there a reason that
the following pattern doesn't work?
  pattern '[ -@\[-~]*';

2.
I note that the YANG module allows just a lat, or a long, or a height
to be specified, rather than requiring at least a pair of lat/long or
x/y coordinates.  I think that this is fine (and keeps the model
flexible), but wanted to check that this is the intentional.

3.
I also note that that grouping doesn't require that any coordinates be
specified at all.  I presume that this is intentional, it makes sense
to me (e.g., if it is intended to be optional).

4. In the YANG module,
"v-east is the rate of change (i.e., speed) perpendicular
 to truth-north as defined by the geodetic-system.";

As a nit, this doesn't actually define whether a positive v-east
value is in the East or West direction.  I appreciate that this is
obvious, but for the other two components in the vector, it is
unambiguously specified.

5.
In Security Considerations:

   Since the grouping defined in this module identifies locations,
   authors using this grouping SHOULD consider any privacy issues that
   may arise when the data is readable.

Perhaps, expand this paragraph to give an example, e.g., revealing
the physical location of a device, or data center.

The rest are just grammar nits:

   In addition to identifying the astronomical body we also need to
   define the meaning of the coordinates
=>
   In addition to identifying the astronomical body, we also need to
   define the meaning of the coordinates

   In addition to the "geodetic-datum" value we allow refining the
   coordinate and height accuracy using "coord-accuracy" and "height-
   accuracy" respectively.
=>
   In addition to the "geodetic-datum" value, we allow refinement of the
   coordinate and height accuracy using "coord-accuracy" and "height-
   accuracy" respectively.

   This is the location on or relative to the astronomical object.  It
   is specified using 2 or 3 coordinates values.
=>
   This is the location on, or relative to, the astronomical object.  It
   is specified using 2 or 3 coordinates values.

   The intent of the grouping being defined here is to identify
   where something is located, and generally this is expected to be
   somewhere on or relative to Earth (or another astronomical body).
=>
   The intent of the grouping being defined here is to identify
   where something is located, and generally this is expected to be
   somewhere on, or relative to, Earth (or another astronomical body).

   At
   least two options are available to YANG models that wish to use this
   grouping with objects that are changing location frequently in non-
   simple ways, they can add additional motion data to their model
   directly, or if the application allows it can require more frequent
   queries to keep the location data current.
=>
   At
   least two options are available to YANG models that wish to use this
   grouping with objects that are changing location frequently in non-
   simple ways.  They can add additional motion data to their model
   directly.  Or, if the application allows, it can require more frequent
   queries to keep the location data current.

When coord-accuracy is specified it overrides the geodetic-datum implied
accuracy.
=>
When coord-accuracy is specified, it overrides the geodetic-datum implied
accuracy.

When specified it overrides the geodetic-datum implied default.
=>
When specified, it overrides the geodetic-datum implied default. 

indicated by the reference-frame value.
=>
indicated by the reference-frame.

For a formula to convert these values to speed and heading see
this modules defining document RFC XXXX.";
=>
For a formula to convert these values to speed and heading see
RFC XXXX.";

You have "truth-north" and "truth north" and "true-north".  Should
these all be "true north"?

   YANG grouping using decimal64 values rather than strings.  For the
   relative height cases the application doing the transformation is
   expected to have the data available to transform the relative height
   into an absolute height which can then be expressed using the YANG
   grouping.
=>
   YANG grouping using decimal64 values rather than strings.  For the
   relative height cases, the application doing the transformation is
   expected to have the data available to transform the relative height
   into an absolute height, which can then be expressed using the YANG
   grouping.

Grammar Warnings (generated by a tool):
Draft Text:
Indeed it is easy to imagine a network or device located on The Moon, on Mars, on Enceladus (the moon of Saturn) or even a comet (e.g., 67p/churyumov-gerasimenko).

Warning:  Did you forget a comma after a conjunctive/linking adverb?
Suggested change:  "Indeed,"

Draft Text:
This document defines a "geo-location" YANG grouping that allows for all of the above data to be captured.

Warning:  Consider using all the.
Suggested change:  "all the"

Draft Text:
When specified these values override the defaults implied by the "geodetic-datum" value.

Warning:  "When" at the beginning of a sentence usually requires a 2nd clause. Maybe a comma, question or exclamation mark is missing, or the sentence is incomplete and should be joined with the following sentence.
Suggested change: "When specified, "

Draft Text:
In both choices the exact meanings of all of the values are defined by the "geodetic-datum" value in the [xref].

Warning:  Consider using all the.
Suggested change:  "all the"

Draft Text:
During the development of this module, the question of whether it would support data such as orientation arose. 
Warning:  Wordiness: Consider shortening this phrase.
Suggested change:  "whether"

Draft Text:
For test "A.1.2.1" the YANG geo location object either includes a CRS ("reference-frame") or has a default defined ([xref]).

Warning:  This word is normally spelled as one.
Suggested change:  "geolocation"

Draft Text:
Many systems make use of geo-location data, and so it's important to be able describe this data using this geo-location object defined in this document.

Warning:  The preposition 'to' is required in front of the verb 'describe'.
Suggested change:  "able to describe"

Draft Text:
For accuracy it has a single "u" parameter for specifying uncertainty. 
Warning:  The comma is probably missing here: accuracy, it.
Suggested change:  "accuracy, it"

Draft Text:
This is used by many application (e.g., Google Maps API).

Warning:  Possible agreement error. The noun application seems to be countable; consider using: many applications.
Suggested change:  "many applications"

Draft Text:
Thus GML "gml:pos" values can be mapped directly to the YANG grouping, with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than doubles.

Warning:  Did you forget a comma after a conjunctive/linking adverb?
Suggested change:  "Thus,"

Draft Text:
Furthermore "gml:validTime" can either be an Instantaneous measure ("gml:TimeInstant") or a time period ("gml:TimePeriod"). 
Warning:  Did you forget a comma after a conjunctive/linking adverb?
Suggested change:  "Furthermore,"

Draft Text:
As with the "kml:altitudeMode" value, the YANG grouping supports the ignore case but not the relative case.

Warning:  After 'the', do not use a verb. Make sure that the spelling of 'ignore' is correct. If 'ignore' is the first word in a compound adjective, use a hyphen between the two words. Note: This error message can occur if you use a verb as a noun, and the word is not a noun in standard English.

Draft Text:
Thus the YANG grouping and KML values can be directly mapped in both directions (when using a supported altitude mode) with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than strings. 
Warning:  Did you forget a comma after a conjunctive/linking adverb?
Suggested change:  "Thus,"

Draft Text:
The allocation policy for this registry is First Come First Served, [xref] as the intent is simply to avoid duplicate values.

Warning:  It seems that a comma is missing.
Suggested change:  "Come,"

Draft Text:
All of the data nodes defined in this YANG module are writable/creatable/deletable (i.e., "config true", which is the default). 
Warning:  Consider using all the.
Suggested change:  "All the"

Draft Text:
These are the subtrees and data nodes and their sensitivity/vulnerability:
None of the writable/creatable/deletable data nodes in the YANG module defined in this document are by themselves considered more sensitive or vulnerable then standard configuration.

Warning:  Did you mean than?
Suggested change:  "than"

Draft Text:
Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. 
Warning:  If the text is a generality, 'of the' is not necessary.
Suggested change:  "Some"

Draft Text:
Below is a the YANG tree for the fictitious module that uses the geo-location grouping.

Warning:  Maybe you need to remove one determiner so that only a or the is left.
Suggested change:  "a"

Draft Text:
We would also like to thank Peter Lothberg for the motivation as well as help in defining a broadly useful geographic location object, and Acee Lindem and Qin Wu for their work on a geographic location object that led to this documents creation.

Warning:  Possible typo: apostrophe is missing. Did you mean documents' or document's?
Suggested change:  "documents'"

Regards,
Rob