Subject: [apps-discuss] Appsdir review of draft-ietf-geopriv-relative-location

From: [email-masked] (Henry S. Thompson)
Date: Wed, 17 Apr 2013 16:02:44 +0100

I have been selected as the Applications Area Review Team reviewer for
this draft (for background on apps-review, please see
http://www.apps.ietf.org/content/applications-area-review-team).

Please resolve these comments along with any other Last Call comments
you may receive. Please wait for direction from your document shepherd
or AD before posting a new version of the draft.

Document: draft-ietf-geopriv-relative-location

Title: Relative Location Representation

Reviewer: Henry S. Thompson

Review Date: 2013-04-16

Summary: This draft is almost ready for publication as a Proposed
Standard but has a few issues that should be fixed before publication

Minor Issues: 

  3 The use of the phrases '"baseline" location' and '"reference"
    location' to mean the same thing (?) is confusing in the extreme
    (as is the fact that sometimes the phrase includes scare-quotes,
    but sometimes not).

    For example, in the following, what is meant to be the difference
    between the two highlighted phrases?

      "In particular, while it is possible to put all location
       information into the 'reference' location (leaving an
                             ^^^^^^^^^
       universally broad 'baseline'), location objects SHOULD NOT have
       all location information in the baseline location.  Doing this
                                       ^^^^^^^^
       would cause clients that do not understand relative location to
       incorrectly interpret the baseline location (i.e., the
       reference point) as the actual, precise location of the
       client."

   Furthermore wrt this passage, either I'm confused, or there's a
   mistake at the second highlighted point.  I was expecting
   "relative", not "baseline" (or "reference").  After all, if all the
   information is in the baseline, then there is no information in the
   relative part, and so not processing it misses nothing???

   Ah, repeated re-readings have uncovered the origin of the problem,
   further back:

     "A client that does understand this extension will interpret the
      location within the relative element as a refinement of the
      baseline location, which gives the reference location for the
      relative offset."

   I read that the first five times as if it were bracketed like this:

      [a refinement of [the baseline location, which gives the
       reference location for the relative offset]].

   But you mean it as if it were bracketed like this:

    [a refinement of the baseline location], [which gives the
       reference location for the relative offset].

   So, I suggest you rephrase the whole sentence along the following
   lines:

     "A client that does understand this extension will interpret the
      location within the relative element as a refinement of the
      baseline location.  The resulting refined location then gives
      the reference location for the relative offset."

  With that change, the paragraph containing the first quote above
  (the para beginning "The baseline location SHOULD be general
  enough") is comprehensible, but still very dense.  I know
  illustrations are hard when one is restricted to ASCII-art, but a
  pair of examples would be a great help here, where one obeys the
  rules, and is not understood wrongly by a non-extension-supporting
  app, but the other breaks the rules, and therefore liable to be
  interpreted wrongly by such an app.

  And, finally, perhaps just _after_ the example now at the end of
  this section, just a brief gloss along the lines of

    The baseline location, given by the first ca:civicAddress element,
    the first child of the gp:location-info, is a street address, to
    the level of detail of the house number (123).  The reference
    location is [now the front door, something else if you fix the 5.1
    issue below].  The actual location, which is still within the
    baseline building, is a point 100m east and 50m north [?] of the
    front door.

  4.11.1

    "An 'http:' or 'https:' URL MUST be used unless . . ."

  Wouldn't it be more in the spirit of 2119 to say "A URI with scheme
  other than 'http:' or 'https:' SHOULD NOT be used unless" ?

  5.1 Civic PIDF with Polygon Offset [also at end of section 3]

  This example uses the ca:INT element, which as far as I can tell is
  only defined in the expired draft-rosen-geopriv-pidf-interior [1].
  It would be better to adjust the example so that it uses elements
  and validates with schema documents all of which can be found in
  current RFCs.

  5.2 Geo PIDF with Circle Offset

  Once the cut-and-paste error identified below in the 'Nits' section
  is fixed, the result has 4 schema-validity errors, all of which I
  presume should be straightforward to correct:

   ex5.xml:14:4: Invalid per cvc-complex-type.1.2.4 : element
   {http://www.opengis.net/gml}:radius not allowed here (5) in element
   {http://www.opengis.net/pidflo/1.0}:Circle, expecting
    {http://www.opengis.net/pidflo/1.0}:radius

   ex5.xml:25:6: Invalid per cvc-complex-type.1.2.4 : element
   {http://www.opengis.net/gml}:Circle not allowed here (1) in element
   {urn:ietf:params:xml:ns:pidf:geopriv10:relative}:offset, expecting
    {http://www.opengis.net/gml}:OrientableCurve,...,
    {http://www.opengis.net/gml}:LineString

   ex5.xml:25:6: Invalid per cvc-complex-type.1.3 : undeclared
       attribute {None}:srsName

   ex5.xml:28:3: Invalid per cvc-complex-type.1.2.4 : element
   {http://www.opengis.net/gml}:radius not allowed here (4) in element
   {http://www.opengis.net/gml}:Circle, expecting
    {http://www.opengis.net/gml}:pos,
    {http://www.opengis.net/gml}:pointProperty,
    {http://www.opengis.net/gml}:pointRep,$

Nits: 

  5.1, 5.2 [examples]

  These examples rely on schema documents which require moderately
  tedious indirection via the XML registry [2] to find -- it would be
  helpful if the references section at least included the relevant
  RFCs, at least 3863, 4479 and 5139.

  5.2

   <rel:urltype="image/png"> --> <rel:url type="image/png">

   There are a number of spurious lines at the end of the example,
   which don't match anything at the beginning and render the whole
   thing non-well-formed:

     </gp:geopriv>
    </status>
    <timestamp>2003-06-22T20:57:29Z</timestamp>
   </tuple>

   ???

  6. Schema Definition

  The repeated pattern used for complex type definition in this schema
  doc is as follows:

  <xs:complexType name="relativeType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
	<xs:sequence>
         ...
  	</xs:sequence>
	<xs:anyAttribute namespace="##other" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  This is overly . . . complex and invites confusion, as it is
  strictly equivalent to the much simpler

  <xs:complexType name="relativeType">
    <xs:sequence>
     ...
    </xs:sequence>
    <xs:anyAttribute namespace="##other" processContents="lax"/>
  </xs:complexType>

  Please simplify all your complex type definitions along these lines.

[1] https://datatracker.ietf.org/doc/draft-rosen-geopriv-pidf-interior/
[2] http://www.iana.org/assignments/xml-registry/xml-registry.xml

-- 
       Henry S. Thompson, School of Informatics, University of Edinburgh
      10 Crichton Street, Edinburgh EH8 9AB, SCOTLAND -- (44) 131 650-4440
                Fax: (44) 131 650-4587, e-mail: [email-masked]
                       URL: http://www.ltg.ed.ac.uk/~ht/
 [mail from me _always_ has a .sig like this -- mail without it is forged spam]