desise format for vocabularies

[Markus Demleitner]

Hi Paul,

On Tue, Oct 01, 2024 at 08:58:23AM +0000, Paul Harrison via semantics wrote:
> I have been trying to use the desise format of the vocabularies and
> feel that it is rather unnatural that he “deprecated" and
> “preliminary" keys are actually of a string type rather than
> boolean given their intention and that their logical meaning is
> really determined by their presence or not. The optional nature of

Well -- that was one of these optimisation decisions that *may* seem
unwise in retrospect; but it seemed clumsy to have "deprecated":
False and "preliminary": False on almost all terms.  Both of these
are relatively rare occurrences.

While the effects on the transfer size by having these "defaults" (if
you will) everywhere probably don't matter much these days, I'd argue
that the (human) readability of desise documents profits a lot from
this decision, and hence I'd still argue that was a wise thing to do.
Even in machine readable formats, human readability is a big win.

> the key is also at odds with what is said in the second paragraph
> of
> https://www.ivoa.net/documents/Vocabularies/20230206/REC-Vocabularies-2.1.html#tth_sEc3.2.1
> where it states that all the keys are mandatory.

That refers to the keys of the top-level object (uri, flavour, and
terms).  In the list of keys of the values of the terms deictionary,
there are explicit indications of whether or not they are mandataory.
True, the exposition could be a bit improved here.  A PR is most
welcome if you have good ideas for improvements.

> I feel that it would be nice if the desise format did in fact make
> these keys mandatory and boolean in type to reduce the amount of
> interpretation code needed by clients.

Well... if you look at 3.2.2, the pattern for "see if a term is
deprecated" is (IMHO) simply:

  "deprecated" in voc["terms"][term]

(ok, that's for Python, but a is-key-present test ought to be rather
straightforward in any language/library expressive enough to make
working with JSON fun).  The alternative you propose

  voc["terms"][term]["deprecated"]

does not seem so dramatically simpler to me than that to justify a
breaking change in desise.

Changing the pattern in desise would also introduce another asymmetry
with the "proper" RDF serialisations, which have triples with the
#deprecated and #preliminary properties in the same way, with RDF
blank nodes as objects.  Sure, you could re-define these properties,
too, and make them "boolean" (in some sense).  But again I doubt that
would have substantial practical benefits.

Convincing enough?

Thanks,

           Markus