RegTAP 1.1

[Mark Taylor]

Hi Markus et al.

On Thu, 7 Dec 2017, Markus Demleitner wrote:

> Since I guess VOResource 1.1 won't change terribly much any more, I
> went ahead and put up RegTAP 1.1 on the document repository, also in
> celebration of the REC's fourth birthday:
> 
> http://ivoa.net/documents/RegTAP/20171206/index.html

This (still) looks like a generally well-written and well-edited document.
I don't have any comments on the subtantive changes to the RegTAP model.
I haven't spotted any problems with them, though I haven't thought them
through in great detail.

But I have one or two comments on peripheral issues.  Some, but not all,
of these are inherited from earlier versions of the RegTAP document.
They are presented below in roughly increasing order of pickiness.

Data model identifier:
---------------------
Section 7 discusses "declaring support for the data model Registry 1.0"
by adding an element to the RegTAP capability:

   <dataModel ivo-id="ivo://ivoa.net/std/RegTAP#1.0"
     >Registry 1.0</dataModel>

This document discusses RegTAP 1.1, so I *think* that all the "1.0"s
in the above should be replaced by "1.1".

Column data types:
-----------------
The listed types for each table column tabulated in sections 8.1-8.14
have changed since RegTAP 1.0.  They used to be things like
"VARCHAR(*)" and "REAL(1)".  Now they are things like "char(*)"
and "float(1)" (I'm not sure if this text is auto-generated or
if the change is intentional).  There are a few issues here.

  - This change is not noted in the change log Appendix E.1

  - The headings of these tables in the text still say "ADQL types",
    but the listed values are now VOTable types.

  - "TIMESTAMP(1)" has been changed to "char(*)" for column
    "created" in table "rr.resource".  The textual description
    hasn't changed however, and it doesn't say how to serialize
    the creation time in a char(*).  Presumably some mention of
    ISO-8601 or DALI would be in order.  There may be other
    similar cases in other tables/columns, I haven't checked.

  - Usages like "float(1)" as opposed to "float" seem questionable
    with reference to recent discussions about whether for VOTable
    arraysize a missing value is equivalent to a value of "1".

  - In general I would favour type descriptions in this context
    which are not tied to VOTable (or ADQL), since as I understand
    it it's the data model not the serialization that is being
    defined here.  Compare discussions near
    http://mail.ivoa.net/pipermail/dal/2017-September/007813.html
    The current TAP 1.1 working version (since volute revision 4286,
    currently unpublished) has adopted this suggestion and describes
    column types as e.g. "string" or "integer".
    In this case there might be an argument for distinguishing
    "unicode string" and "ASCII string" or similar.

standard_id in Examples:
-----------------------
The example in Sec 10.1 includes the clause

   WHERE standard_id like 'ivo://ivoa.net/std/tap%'

but 10.2 (and some others) has

   WHERE standard_id='ivo://ivoa.net/std/sia'

I've got a feeling there's a good reason that the pattern-matched
form makes sense for TAP but not for SIA, but I've forgotten
what it is.  Since these examples are intended to be pedagogical,
and in case other readers are as ill-informed/forgetful about IVOID
as me, it would be nice to add some text explaining the discrepancy
(or avoid it if there is no good reason).

IVORN:
-----
The term "IVORN" is used several times (I count 15) in the text.
My understanding is that this term is deprecated following section
1.1 of IVOID 2.0.

QName example:
-------------
The formatted text renders the QName example in sec 5 as
"http://www.ivoa.net/xml/ConeSearch/v1.0ConeSearch".
I think this is missing some curly brackets that have been
eaten by LaTeX.

Formatting:
----------
It looks a bit surprising to have some lowercase XML element
and attribute names rendered in smallcaps (e.g. "The STATUS attribute
of VR:RESOURCE ..." in sec 8.1 - LaTeX and the browser know those are
lower case strings, but humans may not).  This appears to be the work
of the \vorent macro.  But probably anybody paying enough attention
to notice can work out what's going on, so it's not a very big deal.

Typos:
-----
Section 9:
   ivo_string_agg(expr VARCHAR(*), deli VARCHAR(*)) -> VARCHAR(*)
      - "deli" -> "delim"

Appendix A:
   /capability/maxImageSize/lat
   The image size in the latitude (Dec.) direction in pixels (sia-1.0).
   /capability/maxImageSize/long
   The image size in the longitude (R.A.) direction in pixels (sia-1.0).
      - "image size" -> "maximum image size"?

   \item[/full]If true
      - "true" -> "\texttt{true}"? (cf. \item[/format/@isMIMEType])

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/