VOSI 1.1 review

[Mark Taylor]

Brian,

On Tue, 12 Jul 2016, Brian Major wrote:

> > I have one suggestion for the text.
> > Currently it says:
> >
> >    The child resource must be named with the fully-qualified table
> >    name and without any intervening schema name.  For example:
> >
> >    \begin{verbatim}
> >    GET http://example.net/srv/tables/ivoa.ObsCore
> >    \end{verbatim}
> >
> >    would return a Table document describing the ivoa.ObsCore table
> >    in full detail.
> >
> > That is correct, but I find it slightly confusing (since in this
> > example the schema name "ivoa" is present, but not in virtue of the
> > schema/table hierarchy).
> 
> 
> Okay, yes, I can see how that could be confusing.
> 
> 
> > I would suggest instead:
> >
> >    The child resource must be named with the fully-qualified table name,
> >    as it appears in the name child of the corresponding Table element.
> >
> 
> I think we need to be more concrete (more than just the example) on how
> services must name their tables.  It would be nice if clients were able to
> discover individual tables intuitively (i.e., by naming convention) without
> first going to the full document at /tables to find out what the service
> named them.
> 
> Perhaps, instead of saying 'without database schema', we could say that a
> fully qualified table name is in the format: <database>.<table-name>

sounds reasonable ... but I think it's wrong.

The "official" table name must be the same in all the places it is used:

   - content of vosi:table/name element
   - values in table_name columns of TAP_SCHEMA tables
   - path fragment of VOSITables detail GET

As to what that name actually looks like, TAP 1.0 sec 2.6.2 says:

   "The value of the table_name should be the string that is
    recommended for use in querying the table; it may or may not
    be qualified by schema and catalog name(s) depending on the
    implementation requirements."

the thinking being that different ADQL implementations may have
different requirements for how you qualify or delimit table names;
the TAP implementation is best placed to tell the user how to
refer to the tables in ADQL query text.  When phrasing a query,
some other (more or less qualified or delimited or case-folded)
versions of the table name might work, but it's not guaranteed.

So, I don't think we want to mandate here <database>.<table-name>.
What we want to do is to be explicit that the string to use is
the "official" table name I've talked about above rather
than something put together from the schema/table structure in
the VOSI tables document.  Since the closest place that official
name appears is in the vosi:table/name element, I referred to
that in my suggested wording, but there might be better ways
to do it.  The term "fully-qualified" might be a bit confusing
here too, I think the intention is, again, "as qualified as
it needs to be when referring to that table in queries".

Markus or others who put me straight on this stuff when I was
confused about it a year or two back - please pipe up if I'm 
misrepresenting the standard or its intention.

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/