SSA V1.02 (updated in response to RFC)

Hi All -

The SSA specification has been updated in response to the RFC. The new version (V1.02) is available in the IVOA document repository now (http://www.ivoa.net/Documents/latest/SSA.html).

A summary of changes follows below.

Thanks to everyone who participated in the RFC; the specification is much improved as a result of these careful reviews.

• Doug, Markus, and the SSA authors

SSA RFC Revisons

Significant Changes

• Increased version number to 1.02.
• Added page numbers and a document title at the top of each page.
• Added TSAP use-case as Appendix A. Minor formatting changes.
• Updated example of standard metadata query response in Appendix C.
• Reworked and expanded the description of range-lists (8.7.2) to clarify the semantics in response to questions from the RFC.
• Revised 4.1 to clarify the semantics of the mandatory query parameters including support for theory data.
• Added a new section 8.7.3 on "Missing or null-valued parameters".
• Changed FLUXCALIB and WAVECALIB from boolean parameters to string-valued parameters, with the values "absolute", "relative", "normalized" (for WAVECALIB), and "any" (the default). The minimum acceptable calibration is specified, hence specifying "relative" will also find any data with an absolute calibration.
• Dataset.Collection specifies the IVOA identifier of the collection, rather than the shortname.
• Changed the units of Access.DatasetSize from bytes to KB, to emphasize that this is only intended to be an approximate estimate of the dataset size, used for execution planning. During the test implementations we have been having trouble getting people to return this value, as they mistakenly thought that a precise value was required. Switching to KB will emphasize this. The point was clarified in the text as well.
• Added a new section 2.6 introducing the concept of dataset identifiers. These are used later in the specification, but were never really defined.
• Added a new section 2.9 "UTYPEs and UCDs" introducing these two concepts and describing how they are used.
• Added SpectralAxis and FluxAxis to the Dataset metadata. Along with the SI scaling factors, these are optional for fully compliant spectra, but recommended ("should" provide) for native format spectra.
• In 4.2.4, added some additional discussion of how to deal with multiple Associations, where the same query response record may belong to more than one Association.
• In 4.2.2.2, when using the "@<field>" syntax to indicate an indirect Association.Key (e.g., "@format"), the reference was changed to use the VOTable ID of the table FIELD, rather than the UTYPE, to ensure that the reference is unique in the event of multiple instances of fields with the same UTYPE.
• In 4.1, added "If a service supports a parameter but the value given cannot be parsed or is otherwise illegal (as opposed to merely not matching any data) then an error response should be returned to the client."
• In 4.1.1.3 (BAND), added text to the effect that "If the service supports query by bandpass name but does not recognize an input bandpass name, it should return an error indicating that it does not recognize the named bandpass. If the service does not support query by bandpass name but is called in this way, it should return an error."
• In 8.2.1 clarified version number usage, and the relation of the SSA and Spectrum version numbers.
• In 4.2.5.1, added a paragraph noting that the access reference string should be URL encoded if it contains any reserved URL metacharacters such as "#".
• Modified the specification of MTIME and added a new metadatum Dataset.Deleted, to allow clients which use MTIME to track changes to data collections to discover when a dataset has been deleted (creation and modification were already supported). Dataset.Deleted is only returned in a MTIME query. After an unspecified period of time the service can permanently delete the reference to the deleted dataset. (Note that there may be other reasons for persisting dataset identifiers and associated dataset metadata, once such a dataset identifier has been published; for now we merely support client notification of deletion).
• In the description of the FORMAT parameter (4.1.1), added a note that the FORMAT value is case insensitive. Also clarified that FORMAT=fits refers to the SSA/Spectrum DM compliant FITS format, and that "native" should be used to access a native project specific FITS format, if any.
• In the section on the format=metadata query (6.1) added text to clarify that FORMAT=metadata is a special case of the queryData operation (this should be clear as the FORMAT parameter is part of the queryData operation, but implementations showed that people were confused about this). All operations must be specified explicitly with REQUEST.
• In the TSAP discussion (Appendix A) it appears that what was called a "getData" is actually a standard data query, hence the operation name was changed to queryData. Also added REQUEST parameters to the sample operations, as required by the protocol.
• I considered adding a new "Terminology" section as has been discussed, but this would overlap too much with existing sections such as on Levels of Compliance and Concepts, so I ended up just adding some more material to the Concepts section, e.g., to define "dataset", "data collection", "service", "operation", and so forth.
• In Characterization accuracy and error metadata table (4.2.5.11), removed the "Accuracy." field from the *.Calibration UTYPEs, to agree with changes to the Spectrum DM.
• The UTYPEs for the Char fill factor attributes all had to be changed to Char.*.SamplingPrecision.SamplingPrecisionRefVal.FillFactor to agree with changes in the Spectrum DM (surely a better/shorter name could have been chosen, but it is probably too late to do anything about this).
• Further minor changes to Appendix A (Theoretical Spectra) were required to agree with the SSA spec, particularly in the VOTables. Some of the UTYPEs and UCDs did not agree with the current spec (e.g., Curation.PublisherID not Curation.PubID), Collection is an IVOA identifier, and the like. There are some "VOX:" UCDs still in this which might preferably be locally-defined UTYPEs. Access.Format was changed from "spectrum/votable" to "application/x-votable+xml". An xmlns:ssa reference was added to the top of the VOTable.
• Added an Appendix D providing a summary of the SSA data model (produced from my data model spreadsheet). This presents the whole data model at a glance and includes things like datatype and arraySize which are missing from the tables within the document.

Minor Edits

• Modified 4.1.1.3 (BAND), where range-list syntax is first used, to be more explicit about redirecting the user to section 8.7.2 for details on the range list syntax.
• Tried to be more consistent in the use of fonts. The document font is now used for anything which is a name (UTYPE, UCD, RESOURCE, FIELD, PARAM, etc.), with a typewriter font used for literal examples of computer text (e.g., a MIME type).