Vocabularies in the VO 2.0, first working draft

[Markus Demleitner]

Hi Mark,

Thats a lot for your feedback.

On Thu, 19 Sep 2019, Mark Taylor wrote:

> On Fri, 6 Sep 2019, Markus Demleitner wrote:
> 
> > The first working draft of the new Vocabularies in the VO 2.0 has
> > just hit the document repository at
> > http://ivoa.net/documents/Vocabularies/ (I suspect that URI might yet
>
>  - I wonder if the (somewhat detailed? somewhat heavy?) VEP 
>    process should be documented elsewhere.
>    It seems like the kind of thing that we might decide
>    wants revision following experience of use, and unlike
>    the syntax/semantics content of the rest of the document,
>    it doesn't hurt anything if it changes at short notice,
>    so it would be annoying to have to push through a new
>    document revision just to change the processes.

Hm... I have to say the need for a process is a large part of what made
me tackle this in the first place[1].  I give you there's a certain
risk the TCG at some point finds some new way of operating -- but then
our DocStd document (at least) is broken, too.

And of course, I've tried to relegate pure technicalities to a
non-normative appendix so we can do "breaking" changes without touching
the major version number.

>    So maybe: replace section 4.2 with a comment to the effect
>    that vocabulary updates will be managed by the Semantics WG
>    in consultation with the TCG, and break out the details
>    to a Note?  Or even a wiki page until we feel like it's
>    working smoothly?

If more people feel like that, I could very well imagine moving more of
the material to the non-normative appendix, but for now I'm leaning
towards defining the process normatively -- for one, because that's
not much different from what DocStd does, but also because at least
some vocabulary adaptors are worried that once they make their
vocabulary "public" in that sense, every Tom, Dick and Harry can
suddenly deprecate terms or add junk into "their" vocabulary.

By having it normative that all WGs must consent, I can at least tell
them "oh, you or your successors will always have a veto", which
perhaps can overcome some of their concerns.  So, at least that much
I'd like to retain in the normative part.

> I fixed a few typos (r5650).  I also have queries/suggestions on

Thanks!

>  - sec 1.3: "behind the hash character" - I'm not sure which [...]
>  - sec 2.2.11: "use case!\ref{uc:offline}" - I *think* that [...]

You're perfectly right on both.

>  - sec 3.1.1 and 3.2.1: skos:prefLabel is constrained to have
>    exactly one occurrence per concept but the text for
>    skos:definition seems to permit multiple occurrences.
>    Same applies to rdfs:label and rdfs:comment.
>    Is this intentional?  Having multiple definition/comment entries
>    sounds to me like it would be confusing and should be outlawed,
>    but maybe I'm missing something.

No, that's not intentional.  I was more attentive with the labels
because essentially all clients will want to pull these out.  I'm now
requiring unique definitions/comments, too.

>  - sec 3.1.1: "Definitions that contain the preferred label
>    itself are at least suspicious" - well I think I see what you're
>    getting at but at least in the case that the label is a single
>    english word such an occurrence is going to be reasonable.
>    I'd be inclined to lay off the veiled threats, but it's not a
>    strong opinion.

Uh... "veiled threats".  I guess you caught me there and I didn't do
enough veiling :-)

You see, with my Semantics chair hat on I'd really like to be able to
point to something normative when telling people that "Something that
frobnicates" is most likely not a helpful definition for the term
"frobnicator" -- and you'd be surprised how many of the definitions
we already publish have pretty much that form.

I give you that'd not be a problem as long as everyone agrees what
"frobnicates" means -- but realistically that's the exception rather
than the rule.

Still, people shouldn't feel threatened when they read the spec.  I've
toned down the thing to "recursive definitions (i.e., those using the
label itself) should be avoided whenever possible."  Is that better?

>  - sec 3.1.2: appears to be missing the mandatory skos:definition element.

Hmpf.  That's a bad example in more than one way, thus.  Which made
me notice that the object types (currently all in preliminary) all
don't have a description.  Ouch.  That's serious work to do.  But we
knew that, as these things largely are also in the UAT, and the
Simbad TAP service again has a different convention.

>  - Appendix A: I'm tempted to say that you should be more specific
>    about the file formats (CSV variant details, e.g. how to escape
>    commas; what's INI format).  But on reflection as long as there

I've added CSV details.  Strictly definiting the INI style... hm.  If
other people feel this should be properly defined, speak up and I'll
do it.  Otherwise, I'll adopt the excuse...

>    are examples in place (I haven't so far looked at them) then it
>    probably is sufficient detail for this non-normative, and possibly 
>    subject to change, text.

...suggested by Mark.

Since all these changes are rather small, I've taken the liberty to do
them all in one commit, rev 5661 on volute.  Apologies for having
smuggled in another restriction on our RDF/XML into that commit by
accident; I should have committed that separately.

Thanks again for the review,

           Markus


[1] I mention in passing that I've wanted to have a couple of new terms
in the datalink vocabulary since the last Sidney interop 2015 (proof: 
https://wiki.ivoa.net/internal/IVOA/InteropOct2014Semantics/datalinkvoc.pdf)