resolve #90 (ObsCore example) and resolve #91 (relax content-type) #93

pdowler · 2023-02-01T00:06:20Z

resolve #90 (ObsCore example)
resolve #91 (relax content-type in response headers)
make INFO element with standardID a MUST

Hopefully these are final changes before PR.

resolve ivoa-std#91 (relax content-type in response headers) make INFO element with standardID a MUST

jd-au

The changes look good to me.

pdowler · 2023-02-01T00:21:48Z

Will give other authors a chance to comment.

Bonnarel · 2023-02-01T06:55:16Z

Le 01/02/2023 à 01:21, Patrick Dowler a écrit :

Will give other authors a chance to comment. — Reply to this email directly, view it on GitHub <#93 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMP5LTDTBS7HXCLVRN7A26DWVGUCPANCNFSM6AAAAAAUNB6ETQ>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

OK for me. François

msdemlei · 2023-02-01T08:29:45Z

On Tue, Jan 31, 2023 at 04:21:58PM -0800, Patrick Dowler wrote: Will give other authors a chance to comment.

I'm fine with the drift of the comment, and feel free to merge. However, I'm not quite sure why you went from MUST to {\bf must} in L507; by RFC whatever, that's equivalent, but I suspect people will still wonder whether there's any special meaning to the difference in typography. Similarly nitpicking, your "the content-type header of the response MAY be any value allowed by the VOTable specification" technically means "it can be anything at all". I'd prefer if this said the content-type header of the response MUST be one of the media types allowed by the VOTable specification, [and so on as it's now]

Bonnarel · 2023-02-01T08:32:40Z

Le 01/02/2023 à 09:29, msdemlei a écrit :

On Tue, Jan 31, 2023 at 04:21:58PM -0800, Patrick Dowler wrote: > Will give other authors a chance to comment. I'm fine with the drift of the comment, and feel free to merge. However, I'm not quite sure why you went from MUST to {\bf must} in L507; by RFC whatever, that's equivalent, but I suspect people will still wonder whether there's any special meaning to the difference in typography. Similarly nitpicking, your "the content-type header of the response MAY be any value allowed by the VOTable specification" technically means "it can be anything at all". I'd prefer if this said

yes good point Markus.

…

the content-type header of the response MUST be one of the media types allowed by the VOTable specification, [and so on as it's now] — Reply to this email directly, view it on GitHub <#93 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMP5LTGSG7ZWPSUXHQVHMRLWVINIHANCNFSM6AAAAAAUNB6ETQ>. You are receiving this because you commented.Message ID: ***@***.***>

mbtaylor

Generally agree but see comments. There should also be a note of this change in the Sec 5.1 change log.

mbtaylor · 2023-02-01T09:45:52Z

DataLink.tex

-a different format, the content-type header of the response MUST be
-``application/x-votable+xml'' with the
-``content'' parameter set to ``datalink'',
+a different format, the content-type header of the response MAY be any value


Agree with Markus, MAY doesn't make sense here, should be SHOULD (or possibly MUST)

mbtaylor · 2023-02-01T09:50:25Z

DataLink.tex

 </RESOURCE>
 \end{verbatim}
-
+As of this version, the {links} response {\bf must} include this INFO element


Suggest replacing "As of this version" with "From version 1.1 of this standard". Otherwise the text is likely to remain in future revisions and be confusing.

Also: DALI 1.1 4.4.3 says "The standardID of a service specification is the IVOA resource identifier for the StandardsRegExt record not including capability-specific fragments." Does that mean that the value attribute in this example should be value="ivo://ivoa.net/std/DataLink" instead of value="ivo://ivoa.net/std/DataLink#links-1.0" ?

yes, that's true of the standardID of the specification as used in a StandardsRegExt document. Here is is the standardID of the links endpoint itself, which is defined within that spec.

So I think it's OK.

pdowler · 2023-02-01T19:57:41Z

on MUST vs {\bf must}.... the document uses the latter form (or unformatted) everywhere else. I can make the change in the other direction if that's what we should be doing.

git blame didn't really help me figure out where this came from, but the section on conformance terms (eg MUST) was added by Mark. Otherwise we've all used unformatted and bold lowercase.

msdemlei · 2023-02-02T08:17:04Z

On Wed, Feb 01, 2023 at 11:57:52AM -0800, Patrick Dowler wrote: on MUST vs `{\bf must}`.... the document uses the latter form everywhere else. I can make the change in the other direction is that's what we should be doing.

I don't care at all, as long as it's halfway consistent so people don't wonder whether varied typography means something. In the current master, I still count two MAY, seven SHOULD, and two MUST (not counting the ones in the preamble). I note in passing that writing {\bf xy} has been (more or less) deprecated for about two decades now because it breaks NFSS (i.e., it would be trouble once we changed the base font in ivoatex). We should rather use \textbf{must}. I can make the edits either towards boring old MUST, \textbf{must} throughout or possibly even \rfcmust, \rfcshould, and \rfcmay (for eventual inclusion in ivoatex). While the latter may sound a bit overengineered, now that I think of it they may actually be useful for people writing validators... but that's probably another discussion. But then I'm grateful if you push whatever pattern you prefer into this PR...

note: not global search and replace: only used where applicable to something specified in this doc some minor editorial tweaks I noticed along the way

pdowler · 2023-02-03T18:27:02Z

along with this, the CADC datalink service you get to by querying the ivo://cadc.nrc.ca/argus TAP service now support the applicable DataLink-1.1 features:

always include the standardID INFO element
accept both VOTable mimetypes in RESPONSEFORMAT and set that same value in response header
include 3 new optional fields
added descriptions for the new fields

example for public data:

https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2ops/datalink?ID=ivo://cadc.nrc.ca/IRIS?f212h000/IRAS-25um

For CADC, link_auth is always optional and link_authorized is used, will remove our custom "readable" once our UI is adapted to use link_authorized).

We have not added the code to populate content_qualifier yet but it is feasible to do it - just don't have time right now.

mbtaylor

I think that defining the \rfc* macros with a trailing space is ... questionable.

I can see why you've done it, but (1) it's unusual practice, so people are likely to write "... \rfcmay\ ..." and get too much whitespace, also (2) you can't avoid extra whitespace if you want punctuation following them directly. You might argue that (2) is unlikely for a modal verb which sounds plausible ... but the "Conformance-related definitions" section up front contains text like 'The words "\rfcmust'', "\rfcshould'', ...' which end up including unwanted whitespace inside the quotes (and I also see at least one occurrence of '\rfcoptional.').

Also, ,can you summarise the content-type requirement changes in the change log in Section 5.1.

changed use of blinks command to use trailing backslash style

Removed usage of trailing backslashes after some \rfc* macros where they are not followed by whitespace. The point of the "\xxx\ " idiom is to prevent the whitespace that follows a macro from being interpreted as simply the macro name delimiter and thus swallowed. Writing "\xxx\ " stops that happening by placing a whitespace macro after the \xxx macro; if you write something like "\rfcoptional\." it is interpreted as the "\rfcoptional" macro followed by the "\." macro, which isn't what you want. An alternative way to ensure that the macro is terminated without swallowing following whitespace is to write "{\xxx}".

pdowler · 2023-02-06T22:54:44Z

Thanks Mark. Unsufficient latex-fu on my part :-)

resolve ivoa-std#90 (ObsCore example)

e91898c

resolve ivoa-std#91 (relax content-type in response headers) make INFO element with standardID a MUST

jd-au previously approved these changes Feb 1, 2023

View reviewed changes

mbtaylor reviewed Feb 1, 2023

View reviewed changes

pdowler dismissed jd-au’s stale review via 76f28c0 February 1, 2023 20:22

editorial tweaks

76f28c0

pdowler added 2 commits February 3, 2023 10:14

introduced macros for rfc must,should,etc and used them throughout doc

cfb661a

note: not global search and replace: only used where applicable to something specified in this doc some minor editorial tweaks I noticed along the way

update doc date in makefile

2ca86e2

mbtaylor requested changes Feb 3, 2023

View reviewed changes

pdowler and others added 3 commits February 6, 2023 10:58

remove space from rfc commands and use trailing backslash in content

e415973

added content-type and standardID changes to changelog

8772c07

changed use of blinks command to use trailing backslash style

mbtaylor approved these changes Feb 6, 2023

View reviewed changes

pdowler merged commit 8d23db3 into ivoa-std:master Feb 7, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

resolve #90 (ObsCore example) and resolve #91 (relax content-type) #93

resolve #90 (ObsCore example) and resolve #91 (relax content-type) #93

pdowler commented Feb 1, 2023

jd-au left a comment

pdowler commented Feb 1, 2023

Bonnarel commented Feb 1, 2023 via email

msdemlei commented Feb 1, 2023 via email

Bonnarel commented Feb 1, 2023 via email

mbtaylor left a comment

mbtaylor Feb 1, 2023

mbtaylor Feb 1, 2023

mbtaylor Feb 1, 2023

pdowler Feb 6, 2023

pdowler commented Feb 1, 2023 •

edited

Loading

msdemlei commented Feb 2, 2023 via email

pdowler commented Feb 3, 2023

mbtaylor left a comment

pdowler commented Feb 6, 2023

resolve #90 (ObsCore example) and resolve #91 (relax content-type) #93

resolve #90 (ObsCore example) and resolve #91 (relax content-type) #93

Conversation

pdowler commented Feb 1, 2023

jd-au left a comment

Choose a reason for hiding this comment

pdowler commented Feb 1, 2023

Bonnarel commented Feb 1, 2023 via email

msdemlei commented Feb 1, 2023 via email

Bonnarel commented Feb 1, 2023 via email

mbtaylor left a comment

Choose a reason for hiding this comment

mbtaylor Feb 1, 2023

Choose a reason for hiding this comment

mbtaylor Feb 1, 2023

Choose a reason for hiding this comment

mbtaylor Feb 1, 2023

Choose a reason for hiding this comment

pdowler Feb 6, 2023

Choose a reason for hiding this comment

pdowler commented Feb 1, 2023 • edited Loading

msdemlei commented Feb 2, 2023 via email

pdowler commented Feb 3, 2023

mbtaylor left a comment

Choose a reason for hiding this comment

pdowler commented Feb 6, 2023

pdowler commented Feb 1, 2023 •

edited

Loading