Obscore 1.1 errata page

[Markus Demleitner]

Hi DM,

On Fri, Nov 30, 2018 at 04:04:09PM +0100, Laurent Michel wrote:
> The errata page for Obscore 1.1 has been open:
> 
>      https://wiki.ivoa.net/twiki/bin/view/IVOA/ObsCore-1_1-Errata
> 
> The erratum 1 contains 6 items. 5 have been discussed on the list and the
> 6th (missing facily_name) has been detected during the document review.
> Please consider reviewing it and discuss it on this list.

While I think I'm ok with most of the issues raised (I'd propose a
different URI UCD, but I don't care enough to quarrel), I'd say the
form of the Erratum needs to be substantially improved -- remember,
Errata essentially become part of the REC, and implementors will read
this with the expectation of clearly learning what's wrong and what
needs to be fixed (and they'll not appreciate language like "This
looks like simply a typo", I suppose).

I'd therefore suggest to split this erratum into at least two
separate errata; I could well see:

(a) Invalid UCDs 

(b) Inconsistent Metadata in Table 5

Further more, the Erratum (or future Errate) would, I think, win a
lot if it (they) followed the recommended top-level structure
(DocStd, p.  12), viz,

Rationale

Change in Standard

Impact Assessement

-- for (b), the "Change in Standard" section should probably be just
the entire Table 5 with changes marked in, perhaps, red.  For (a),
I'd say something like[1]

  Rationale

  ObsCore gives mandatory UCDs for the fields that make up the schema.
  Unfortunately, while constructing the UCDs of some columns, invalid
  or overspecific UCDs were chosen.

  This concerns 

  (a) obs_publisher_did and publisher_id columns; both are required to
  have meta.ref.uri;meta.curation.  This is invalid by the UCD
  standard, as meta.curation is a primary word.

  (b) o_stat_error is required to have stat.error;phot.flux.  Since
  ObsCore tables can also contain products in which the observables are
  not flux-like, this is overspecific.


  Change in Standard

  On PDF p. 56 (Table 7), in the row for obs_publisher_did, replace 
  meta.ref.uri;meta.curation with meta.curation;meta.ref.uri.

  On PDF p. 58 (Table 7), in the row for publisher_id, replace 
  meta.ref.uri;meta.curation with meta.curation;meta.ref.uri.

  On PDF p. 59 (Table 7), in the row for o_stat_error, replace
  stat.error;phot.flux with stat.error.

  On PDF p. 62, in the FIELD definition for obs_publisher_did, replace 
  meta.ref.uri;meta.curation with meta.curation;meta.ref.uri.


  Impact Assessment

  ObsCore clients normally use column names or perhaps utypes to
  identify data model members.  The change of the UCDs proposed here
  should not impact them.

  Clients not aware of ObsCore will profit from the proposed change;
  for obs_publisher_did and publisher_id, they will no longer produce
  diagnostics for invalid UCDs, and for os_stat_error they will not be
  mislead any more.

Or so -- future implementors will be grateful.

          -- Markus


[1] I've put in meta.curation;meta.ref.uri instead of meta.ref.ivorn (or
ivoid, whatever) -- for one, it's more specific, and for a second,
in practice people put all kinds of things there, not just ivoids.
That's particularly true for the pubDID, and I totally see that a DOI
is at least as good as an ivoid.