Spectral 2.0 - Document update

[Markus Demleitner]

Hi Mark,

On Thu, Jun 04, 2015 at 12:43:14PM -0400, CresitelloDittmar, Mark wrote:
> We have been exercising the Java library on the Spectrum-2.0 files
> delivered by Marcus' service.

Is there any chance that could be extended into a basic validator for
SDM2 files?  I don't think a fancy UI is needed, something I can
upload my files to and get back a text file with not-too-cryptic
error messages would perfectly do.

> It's been a pretty smooth process.  Below are a few issues we note with the
> serialization.

I've put in some changes based on your feedback:

> #UType Prefix
>   + uses "spec2" where document states "spec"
>     (Discussion item)
>     You mentioned that you did this in your implementation notes,
>     explaining that you feel it is the correct approach.  I think
>     we need other opinions expressed to make an informed decision
>     on the intent of the UType prefix.

Other opinions would definitely be great.  I'm leaving things at
spec2 for now, as I think it should be for incompatible (major
version) changes, but on closer inspection there doesn't seem to be a
deep technical reason for having separate utypes from a server
perspective.  My main concern would have been to enable simulataneous
SDM1 and SDM2 annotation, but that doesn't work with ad-hoc utypes
one way or the other.

> #Groupings
>   These PARAMrefs are in the wrong Group.  These would be interpreted
>   as Custom metadata on those groups which are instances of the the
>   specified element.  Since the PARAMs are ungrouped, they will define
>   the element (again) in the expected location.

The spec says "We use the VOTable GROUPS construct to aid
readablility. It is not a requirement for users to make use of this
construct for all elements of the model" (p. 88) -- so, I believe
given the current spec language I'm within bounds.  That said, I
*could* move

>   + Curation
>     - contains DataID element "spec:DataID.DatasetID"
>   + DataID
>     - contains ObsConfig element "spec:ObsConfig.Bandpass"
>     - contains ObsConfig element "spec:ObsConfig.Instrument"
>     - contains ObsConfig element "spec:ObsConfig.DataSource"

-- but the stuff generating these is sharing code with SDM1, and to
fix this, I'd have to duplicate the metadata definition of the two
versions just  to shuffle around these four fields.  Or I write some
magic code somewhere doing the shuffle.  Or I uglify the SDM1
serialisations.  As I don't really like any of these, unless it bugs
you significantly, I'd leave things as-is.

> #UnModeled PARAM/PARAMref elements - Utype issue
>   + No such element in SpectralDM
>     spec:Access.Format

PARAM remains, utype gone.

>     spec:Access.Reference

That containes the URL the file was pulled from, with the utype (like
the others here) translated from their ssa brethren.  I've nuked the
utype now, but: Shouldn't we have something like "Original URL of the
dataset" in SDM, too?

[Incidentally, I've never understood why SSA needs a different data
model and wish all the string manipulation magic going between SSA
and SDM1/2 utypes weren't necessary; that'd have avoided these bugs,
too.]

>     spec:Access.Size

PARAM remains, utype gone.

>     spec:AstroCoords.Position2D.Value2     <== NOTE: this is in the Char
> group.

utype on the PARAM is now spec2:SpatialAxis.Coverage.Location.Value

>     spec:Target.pos.spoint

utype on the PARAM is now spec2:Target.pos

>   + Misspelled (is that spelled correctly?)
>     spec:Char.SpectralAxis.CalibrationSatus  <= "Satus" s/b "Status"

Fixed.

Thanks for looking at this stuff -- further reports appreciated.


Cheers,

        Markus