msdemlei
commented
4 years ago Adding a name to datalink resources is perhaps a good idea, but "to help identifying the meaning" isn't telling implementors how they should pick names.
I guess the intent is that clients can show these names in UIs to let users choose between different datalink services on a single resource; in that case, advice on the typical length of such a name ("avoid names longer than 40 characters") will help sensible use. Now... to see where this is going, let's assume there's a datalink service ("{links}") and one of those unfortunate direct SODA blocks on a table.
The client knows which one the datalink service is because of the standard id, and it can tell the SODA block as well by the standard id as well. Hmmm... I start becoming uncertain if there should be a dialog that gives a choice between the two in the first place... Ok -- can we be a bit more concrete here what the names will be used for? If we can't, my suggestion would be to drop the name thing.
Dropping the name recommendation would also be supported if I look at the examples provided. Take "{links} for Obscore" as an example. First, it's a description, not a name, and second, it doesn't give any information that's not already there in other form (the links part is the standardId, the obscore part is in the metadata of the table this references). I can't really see how this would help anyone. Similarly, "My SIA service" sets a similarly unfortunate precendent of mixing the obvious with the useless.
For recommending descriptions on service descriptors, I see a lot more potential, but again, it would be good if the examples shown set a good precedent. "Links resources to datasets" is a zero information that just further confuses the already muddled terms "resource" and "dataset". Can't we rather say "This datalink service gives access to the raw data for the discovered datasets as well as to catalogues of extracted sources" or something of the kind? Operators stating why they're even offering a datalink service sounds like something that might help users.
"This is service SIA for so and so", on the other hand, isn't helpful, as it doesn't tell users anything they couldn't see from other info. Unfortunately, I can't see the purpose of the example as such, and so I can't propose a better explanation (and would rather suggest to drop the whole example).
"A nice container to share space" at least is somewhat witty, but in order to set a good precendent I'd rather say something like "Datasets discovered here are automatically available in Example Institution's VOSpace under the URI produced here" (though I again have to admit that I don't really understand why one would do this).
Instead of "Custom APOADIMO spectrum recalibration service" I'd say "This service lets you retrieve the spectra discovered uncalibrated, with flux calibration, and continuum normalised (where some spectra are now availble in continuum normalisation because the pipeline failed to identify a continuum)" or something like that (where the service this was taken from can't actually do that, but that's beside the point).
Bottom line here: let's nudge implementors away from useless and non-informative descriptions and towards descriptions that actually tell users things they didn't already know.
As to "RESOURCES these RESOURCES should be nested": I think this tries to solve a problem that doesn't exist -- clients need to pair up tables and service descriptors by following the reference(s) from the PARAM(s) in the service descriptor to the FIELDs and PARAMs in the table, and no nesting of RESOURCEs can help there. Also, if we are only talking should here, clients can't really optimise any parsing strategy based on any such rule. So: I claim this doesn't help anyone and is too vague anyway. Let's drop it.
Similarly, I can't see what the "self-describing service descriptor" example is supposed to accomplish and would suggest to drop it again. Why would one even want to find that "self description", let alone "unambiguous"ly? And once one has found it, what's the intended use of the information obtained in this way?
If we do something like this this "self description", it needs to be made clear what the standards status of this is: is it a MUST? Is having @name="this" a MUST in this kind of thing?
Summing up: The one thing I'd take over from the PR is the recommendation to have descriptions in service descriptors; but the examples for these descriptors ought to be changed so they nudge implementors in the right direction.
To the PR as it is: No, let's not merge it.
mbtaylor
Bonnarel
The examples now show the new features described in the pull request