VODataService 1.2, PR ready for RFC?

[Markus Demleitner]

Hi Mark,

Thanks for your comments.  Below is what I made of them.

Meanwhile, it seems I'll have to do another document release for RFC
anyway, so it'd be great if I could take out the three todo notes
that are still in already by then.  So, if you have any preferences
for the following questions, would you speak up now? 

(1) vs:InputParams are currently restricted to SimpleDataTypes.  I
don't think anyone is, at this point, doing anything with these type
names, so I'd say we can liberalise this with impunity.
Specifically, I'd like to be able to use VOTableDataType there, too,
as I hope to make our clients' lives easier by not requiring them to
understand lots of different type systems.  So, unless someone
protests now, the constraint of InputParams to SimpleDataTypes will
go.

If anyone has a word of encouragement, I'd additionally *recommend*
putting VOTableDataTypes in there.  

(2) Abusing footprint/@ivo-id to say what kind of footprint will be
returned is, admittedly, brazen, as ivo-id is understood everywhere
else as the identifier of the thing described.  What we're doing here
is more akin to standardID attributes.  The clean thing would be to
add such a standardID attribute and forget about ivo-id (I don't see
footprint services with registry records of their own any time soon).

On the other hand, I usually consider existing practice as fairly
sacrosant, and people have been dumping the MOC URI into
footprint/@ivo-id for quite a while now.  So, unless someone
protests, I'll sanction reality rather than do the proper thing.

(3) Services like simbad (xamin, too, I think) don't use SQL schemas.
For these, we now say they should put "default" into schema/name.
That's kind of lame.  We could also make the name attribute of schema
optional instead, which would be better overall but might actually
break VODataService parsers (incl. TAP clients).  I doubt it, though.

If nobody speaks up on this... hm.  Not sure yet what I'll do for the
PR.

On to Mark's comments:

On Mon, Jul 22, 2019 at 11:34:49AM +0000, Mark Taylor wrote:
> On Fri, 19 Jul 2019, Markus Demleitner wrote:
> 
> > I've uploaded VODataService PR-2019-07-15 to the document repository
> > -- http://www.ivoa.net/documents/VODataService/20190715/ --, and this

>   - sec 2.1: "As recommend by" -> "As recommended by"

All the typos reported are fixed in Volute rev. 5561.  Btw (for
everyone else, too), feel free to commit such simple corrections
yourself.  It's version control, so in the unlikely event that I
disagree with a change, it's not hard to revert it.

>   - sec 3.2, footnote 4: "Version 1.1 of MOC will give a normative
>       specification of ASCII MOCs, which is expected to exactly
>       match the non-normative proposal in version 1.0.":
>       The current MOC 1.1 draft doesn't *exactly* match the non-normative
>       proposal from MOC 1.0 (e.g. the MOCORDER may be provided in 1.1,
>       but not 1.0).  Maybe by the time that VODataService 1.2
>       gets close to REC MOC 1.1 will be accepted, in which case the
>       reference can just be made to MOC 1.1, but until then, just
>       remove the term "exactly"?

I changed it to "essentially", which I think reflects the general
intention.  And yes, MOC 1.1 should be through before VODataService,
so we can probably replace this with an actual reference later.

>   - sec 3.2: the first item in the list of Elements on p.21, with
>       Meaning "An STC 1.0 description..." doesn't seem to have
>       an element name or a Type value.

Oh dang.  Why does everything always become annoyingly complicated as
soon as it approaches STC?  The missing name and type is because the
schema just does a ref to the actual definition, which is in the STC
schema (which in turn isn't even REC and probably will never be), and
the XSLT that generates documentation out of the schema doesn't
handle that.

I've added some half-assed support for @ref to ivoatex's
documentation generation, so the thing now reads:

  \item[Element \xmlel{stc:STCResourceProfile}]

  An STC 1.0 description of the location of the resource's data on the
  sky, in time, and in frequency space, including resolution.   This is
  deprecated in favour of the separate spatial, temporal, and spectral
  elements.

  This element is imported from another schema.  See there for details.

Doing better automatically is hard in XSLT 1 (e.g., figure out where
the "there" for details is).  Since STCResourceProfile is deprecated
anyway and we should keep people from trying to figure it out, I
think that's still good enough.  If anyone disagrees or we need
xs:element/@ref for things we actually want to do, we'll have to
think harder.

>   - sec 3.2: the "string of the form [horrible regex]" Type entries
>       for the temporal and spectral elements are almost unreadable
>       by humans (or at least by me).  I suspect this text is
>       autogenerated from the XSD (in fact I vaguely remember making
>       this complaint before), but is there any chance of replacing
>       it with something more digestible?  If not, at the very least
>       add an example in a Comment for temporal as has been done for
>       spectral.

I think an RE for "whitespace-separated pair of XSD float literals"
won't ever be pretty.  You could argue that dumping these REs into
the text is a questionable thing, but I guess having the REs is
useful in other cases, and trying to predict what these cases are in
the XSLT smells of overengineering.

I've added an example to the documentation string for temporal.  In
spectral, there's been one already.  Perhaps that helps already.


>   - vs:Table XSD: should the @type for the nrows element be
>        xs:nonNegativeInteger instead of xs:integer?
>        But I don't suppose in practice that would capture any
>        genuine errors, so if there's some preference for less-obscure

Being more precise there sounds like a good idea, in particular
because I can imagine about 20 ways in which this could become -1...
So, it's NonNegativeInteger now (which is the only change I've put
into a changelog).

>   - sec 3.5.1: The vs:InputParam attributes @use Allowed Values
>       lists the value "optional" twice.

The second "optional" is the default value; an ivoatex bug swallowed
to label, which is fixed now.

       -- Markus