VOCLASS example is wrong

[olebole]

The VOCLASS FITS keyword is defined to be as 'SPECTRUM 1.00'

SpectrumDM/doc/specfits.tex

Lines 122 to 124 in f485c3e

	\paragraph {\bf VOCLASS keyword:}
	We add a new keyword VOCLASS to describe the VO object represented by the
	FITS table. The value of VOCLASS should be 'SPECTRUM 1.00'.

but in the example it is set to 'Spectrum V1.0'

SpectrumDM/doc/example_fits1.tex

Line 12 in f485c3e

VOCLASS = 'Spectrum V1.0' / VO Data Model

What I don't understand here: why does the definition say "SHOULD" instead of "MUST"? Are there any use cases where it is set differently? Allowing a format indicator to deviate from its definition seems a bit weird to me. How can a IVOA compliant spectrum reader deal with this?

And who is "we" here? Why is the keyword "new" (it was already there in
1.0)?

[mcdittmar]

@olebole,

Recall.. the last update was kept to a limited scope to satisfy a specific request, so many things were left unchanged.

The document has 4 places where VOCLASS is mentioned, each of which has a different string!

• Section 3.7: Data Model Fields
  • Table 1: Field DataModel, FITS key VOCLASS, default="Spectrum-1.0"
• Section 9.1: FITS Serialization
  • page 74: VOCLASS keyword; The value of VOCLASS should be "SPECTRUM 1.00"
  • Table F.1: VOCLASS value if fixed; "SPECTRUM 1.0"
• Section 9.4: An instance example
  • VOCLASS = 'Spectrum V1.0'

I agree that the value should be fixed to be useful. I imagine most are just looking for "Spectrum" (case-insensitive) and/or looking at the options TYPE (VOSEGT keyword) "Spectrum".

In my opinion, the value in Section 3.7 should be normative.

Unfortunately, the language of the document really would indicate that the value is required, but not fixed. If missing, "Spectrum-1.0" should be assumed. Of course, since this is the key which determines what is to follow, I'm not sure you can assume anything if it is missing. In other words, in order to make that assumption, you must already have the knowledge that it is an IVOA compliant FITS Spectrum serialization.

I'll add an agenda item for the DM running meetings to discuss adding an Erratum, presumably unifying the strings to the default value 'Spectrum-1.0'. I'm not sure we can change the language regarding 'should' and retain backward compatibility.

Mark

[mcdittmar]

From DM list: http://mail.ivoa.net/pipermail/dm/2025-February/006570.html

Markus D. writes:
Let's fix this to Spectrum-1.0, because that's in line with the
syntax of similar things in the VO. While we're doing this, let's
also tell people that to determine if the file is something they can
process they should in general ignore the minor version, i.e., the
test would be hdr["VOCLASS"].startswith("Spectrum-1."), and that it's
case-sensitive.

Let's do an erratum. This is clearly an editorial oversight.
Volunteers?

[mcdittmar]

Markus D. writes: Let's fix this to Spectrum-1.0, because that's in line with the syntax of similar things in the VO. While we're doing this, let's also tell people that to determine if the file is something they can process they should in general ignore the minor version, i.e., the test would be hdr["VOCLASS"].startswith("Spectrum-1."), and that it's case-sensitive.

I'd be concerned about the backward compatibility..

• migrating all the examples to "Spectrum-1.0" is fine
• as for the test, we can add that this is the intent and providers SHOULD accommodate this, but we can't require it.