[opendap-tech] DAP 2.0 Questions and Comments

[Bob Simons]

I have a few questions and comments related to ESE-RFC-004.0.08
"The Data Access Protocol - DAP 2.0" (dated 2005-10-27).

First, let me say that I am a big fan of the DAP specification and
all the software that implement it.
My comments are intended to be helpful, not critical.
I am more confident of some items than others.
Some of the items are important. Some are picky details.
So please take them all with a grain of salt.

In an effort to make the examples more readable, I will indent literal
examples instead of putting them in double quotes.

Here are the questions and comments:

* Table 5 lists the "=~" operator,
   but dods.dap.parser.ExprParserConstants.java lists "~=" instead.
   And the online help at 
http://www.opendap.org/user/guide-html/guide_35.html#id4
   lists "~=" instead.
   Which is correct?

* In your notation, square brackets indicate optional items.
   The box in section 6.1.1 lists
      [ array-dim ]
   Shouldn't it be
      *[ "[" array-dim "]" ]
   instead, particularly since array-dim doesn't include "[" and "]"?

* Footnote 8: instead of
      decimal value 10 and decimal vale [sic] 13.
   perhaps it would be better to say
      decimal value 13 and decimal value 10, respectively.

* Footnote 8, the general use of CRLF in the document, and the
   CRLF description in Appendix A.2 are somewhat misleading.
   Appendix A.2 mentions section 3.7 of RFC 2616 which
   indicates that just CR or just LF
   can be used in place of CRLF if used consistently throughout
   a document. Indeed, this is what some implementations, e.g., TDS,
   seem to do.
   I understand that you are following the HTTP syntax, but perhaps
   it makes sense to add a comment about allowing just
   CR or just LF to the DAP specification.

* Section 7.1.4 has a minor typographic error:
      includ
   should be changed to
      include
   .

* All of the examples of the XDODS-Server header in section 8
   (e.g., "Friendly-neighborhood DAP implementation v/3.1.1")
   are very different from the specification in section 7.1.7
   (e.g., dods/3.2.2).

* Is the "Last-Modified" header described in section 7.1.4.2
   a MUST or an OPTIONAL header?

* In section 7.1.4.2, what do you mean "the last time the
   server changed"?
   The last time the server software was updated?
   The version date for the server software?

* Perhaps I missed it, but where is the server version number
   defined? section 7.1.7 describes how to return the number in
   the header. But where does that number come from?
   Does it indicate the DAP standard number? (I don't think so.)
   Does it indicate the version number of my OPeNDAP server software?
   (I don't think so, because this would be meaningless to most clients,
   since the header includes "dods", not the name of my software.)
   Does it indicate the version number of some OPeNDAP software?
   If so, which software?

* It seems odd to put Figure 2 (which is referenced in section 7.2.2 and
   relates to section 7.2.2) before section 7.2.2.

* The box in section 7.2.2 includes
      "data-source"
   but the Figure 2 example, the examples in section 8, and actual
   implementations seem to use
      "dataset"
   instead.

* It is unfortunate that the term "array-dim" is used in two
   different contexts and is therefore defined differently in
   section 6.1.1.2 and section 7.2.2.2.

* In the box in section 7.2.2.3, isn't
      structure
   a literal? So shouldn't it it be
      "structure"
   instead?

* In the box in section 7.2.2.4, isn't
      sequence
   a literal? So shouldn't it it be
      "sequence"
   instead?

* In the box in section 7.2.2.4, there is a reference to
      [sequence-type]
   but there is no definition of sequence-type.
   Did you mean
      sequence-decl
   instead? (I'm not sure.)

* In the box in section 7.2.4, there is no
      ";"
   after
      "}"
   The trailing semi-colon seems to be required by
   dods.dap.DConnect
   and seems to be included with errors from DAP implementations
   like TDS (e.g., see
 
http://oceanwatch.pfeg.noaa.gov:8081/thredds/dodsC/satellite/MH/chla/8day.dods?zzz 
).

* In the second box in section 7.2.5, is "dap-version" really required?
   I note that TDS does not include dap-version (e.g., see
 
http://oceanwatch.pfeg.noaa.gov:8081/thredds/dodsC/satellite/MH/chla/8day.ver 

   or
   http://oceanwatch.pfeg.noaa.gov:8081/thredds/dodsC/version ).
   Or is this a mistake in the TDS implementation of the DAP spec?

* In the second box in section 7.2.5, it would be nice if there were a
   description of what the "token" should indicate for dap-version,
   server-version, and data-source-version.
   Specifically, if the token needs to be, or is usually, a specific
   word (e.g., "dods"), it would be nice to mention that.

* In the second box in section 7.2.5, should the final
      "." 1*DIGIT
   be optional?
   I note that the XDODS-Server version number defined in section
   7.1.7 allows for 2 or 3 digits.

* At the very end of section 8.1, perhaps it would be useful to change
      MUST NOT contain any carriage-return line-feed pairs.
   into
      MUST NOT contain any carriage-return line-feed pairs inserted
      as separators. Carriage-return line-feed pairs in the binary data
      section are interpreted as data values.
   or something like that, since #13 and #10 may appear as part of
   the binary data.

* Some of the examples in section 8 include <CRLF> indicators, some
   do not. Some (like the last example) include <CRLF> in some places
   where they must appear, but not other places where they must appear.

Thank you for considering these questions and comments.
I hope they are useful.

Sincerely,

Bob Simons
Satellite Data Product Manager
Environmental Research Division
NOAA Southwest Fisheries Science Center
1352 Lighthouse Ave
Pacific Grove, CA 93950-2079
(831)658-3205
bob.simons at noaa.gov

The contents of this message are mine personally and
do not necessarily reflect any position of the
Government or the National Oceanic and Atmospheric
Administration.
<>< <>< <>< <>< <>< <>< <>< <>< <><