Simple Spectral Access RFC

This document acts as RFC centre for the Simple Spectrum Access Protocol, PR V1.01. Further information on the SSA protocol and associated Spectrum data model can be found on the Collaborative Page for the SSA Interface.

Note that although early SSA implementations included a getCapabilities operation for returning service metadata, specification of this has been deferred to SSA V1.1. The V1.0 specification being reviewed here mentions getCapabilities (and getAvailability) but does not specify the contents of the metadata returned. The older FORMAT=METADATA construct is specified instead. This will eventually be deprecated, but allows SSA V1.0 to go forward immediately while we work to specify these additional operations for V1.1.

To add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your WikiName so authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Discussion about any of the comments or responses should be conducted on the data access layer mailing list, dal@ivoa.net.

Comments

• First sample comment (by BrunoRino): ...
  • Response (by authorname): ...

• Concerning input parameter BAND: In a band range: Is the first parameter expected to be smaller than the second one or can a service accept e.g. band=2000/1000? Is band=/ considered as a valid band range? (by UlrikeStampa)

• • Response by MarkusDolensky:

Yes to the example of the open interval for BAND.

Omitting both values indicates an infinite range which accepts all values.
(sect. 8.7.2)

A specific order is not required except that a list of ranges is processed from left to right and any matching values in any interval shall be returned (logic OR).

• • Response by DougTody:

Since many parameters can accept ranges or range-lists, the detailed semantics of range list parameters are specified once in section 8.7.2 rather than for each parameter. As this section specifies, if numerical ordering of the range-list is required for query processing, it is the responsibility of the service to sort the list, or re-order the range values. In the case of BAND it is clear that such an expression says the same thing regardless of the order in which the elements are given.

• Page 49, Query response example, 3rd line: there is "//" missing in the schema location (by IgorChilingarian)

• • Response by MarkusDolensky: Thanks for spotting Igor.

• Section 4.1.1 expressly states that valid queries don't have to specify all mandatory parameters. Some of them are thus defaulted when missing (i.e. SIZE, FORMAT) but how to deal with POS, BAND and TIME when omitted (especially POS)? Second, does a POS=, (empty list, section 8.7) and a missing POS situation have to be considered as equivalent? In general, how to deal with irrelevant parameters (eg for theoretical spectra)? (by HerveWozniak)

• • Response by DougTody:

This is an important and subtle point. Most parameter values are used only to constrain the query. There is not necessarily any default value if a parameter is not given. If no value is specified for a parameter, e.g., SIZE, then all it means is that it is not used to constrain the query; other parameters must be used to constrain the query instead.

The case of theory data is discussed in section 4.1. A service must support a mandatory parameter, like SIZE, but this does not necessarily mean that the parameter is valid for the data in question. If the query specifies an explicit position (or TIME etc.), and this quantity is undefined for the data in question, then the service should not find any matching data.

The case of something like PARAM=, with no value given, has not been addressed. This would appear to be the same as PARAM="". In general specifying the empty string is not the same as unset, although it may not matter for a parameter such as POS. This needs more thought. In the meantime, it has not been addressed by the current spec.

Here is the list of questions, suggestions, and typos. We understand that some issues may not be resolved in this version of SSAP, but still think useful to be considered for a future version. We hope we have made ourselves clear as sometimes the issues are rather tricky to explain.

1. Query response metadata:
   1. We suggest adding the datatype of each output metadata element, including the allowed cardinality, in the corresponding tables in the specification document. This makes it much easier to find this information, which now is spread out through the text.
   2. For Associations, we would like to see an example how to deal with the case of a single row belonging to two or more different associations. Do the values of each of the different attributes (Type, ID and Key) get listed in their respective column and in the same order? Seems natural but should be specified formally. See 3) and 4) below.
   3. Also on Associations. In the examples an Association gets a GROUP in the VOTable. If we have multiple Associations we will have correspondingly multiple groups. Should all of these have FIELDRef-s to the same column (Association.Key)? Is that allowed in VOTable? Should there be an indication which “sub-column” inside this column is referred to by the Association? Is it allowed in the SSA query result to have multiple Association.ID/Key/Type columns?
   4. Similar questions as for the Association apply to other “multiplicity > 1” elements such as DataID’s CreatorDID, Date, and Version for a dataset created from multiple parent sets.
   5. In Appendix A on p50: In <Group ID= “Association” …> <FIELDref ref =”AssocID”> :Is this correct? Are AssocKey and AssocID mixed up here or do we misunderstand this?
2. Query input parameters:
   1. We think that it would be helpful if the syntax for each input parameter were expressed in a concise, and precise form in the tables. Possibly even using regular expressions in complex cases. Currently the precise format is spread out through the text, e.g., the description of BAND is almost a page.
   2. (Similar comment by H. Wozniak) We think the document needs a proper description of how the service should act when the value of a request parameter is not specified properly, i.e. how to handle syntactic errors. Related to this we think the document needs a description (or rethink) how to handle nulls and how to handle the case where a parameter is supported, but not all its possible values. For example, our service supports only numerical specification of the BAND parameter, what should we do when someone submits BAND=J. In the latter case the document specifies that no rows should be returned. We believe that a better result would be an error/warning message indicating that the service does not understand the request.
   3. How to handle unsupported parameter: It is mentioned in sec 4.1 on p17 that the service should allow a query to the request including an unsupported parameter, assuming a logical value ALL Should the service first do syntax checking?
   4. How should we specify the allowed syntax of custom input parameters in FORMAT=METADATA?
      1. Specifying datatype=char and arraysize=* does not give the actual allowed syntax, see the case for POS.
      2. How can we indicate to a client that a certain parameter allows range-list values?
3. We find the description of the various data set identifiers confusing.
   1. Must all such identifiers in this spec (CreatorDID, DatasetID, and PublisherDID) adopt the IVOA Identifiers standard (http://www.ivoa.net/Documents/latest/IDs.html)? Is it what was intended by the “IVOA” in statements such as “The IVOA dataset identifier …” (p32, p33).
   2. What is the DatasetID ? It is introduced in a table on p.32 but not described in the text as far as we can see.
4. Note on p34: “If the same dataset is replicated at several locations with multiple publishers, it is possible to set up an association group to indicate this fact.” : This seems only relevant if all of these datasets are published by a single SSA service instance, can therefore show up in a single query result, and such an association can be useful. Otherwise it seems only to complicate matters.
5. A typo in the table on p33: “Data curated” should be “Date curated”
6. There is description on version negotiation for SSAP, but no mention of which version of datamodel should be used. Is it arbitrary, or is there a one to one relationship between SSAP and Spectrum DM? Or something else?
7. In sec 4.1.2 on p21 table of recommended and optional query parameters: inconsistency in the datatype of a parameter whose value is true/false: FLUXCALIB false string, WAVECALIB true string, COMPRESS true boolean
8. Typo on p26: In an example of service protocol there is an extra ‘/’.
9. It is not explicitly stated in the text that it is mandatory to repeat the query parameters in the result. Should it be ? (See the example in Appendix A)
10. Does service metadata require UCD? See sec 4.2.3-4.2.5. Tables have UCD column without any value in it.
11. In sec 4.2.6.8 on p36: In the table “Calibrated”, in the following text it is “calibrated”. It is stated that parameter values are case sensitive in 8.7.1
12. Text in sec7 on p39, starting with “ … is required to obtain an acref,” to “ … implementation of existing services” is almost literally replicated in section 7.1. Is this necessary?
13. In sec 7.1: If the client issues a HTTP GET request using this URL, and the request is successful, the client will receive a document of the type given in query response column with the UTYPE Access.Reference.: Should it be UTYPE Access.Format?
14. In sec 8.2.2 on p40: … shall comprise no more than two integers separated by decimal points,…: Should it be ‘three’ integers instead of ‘two’ as there are three levels of versioning?
15. In sec 8.3.2 on p.42: In Table 1, ‘/’ is missing.
16. In sec 8.3.3 on p 43: In Table 2 http://host[:port]/path[?{name[=value]&}]: Should this be http://host[:port]/path[?[name[=value]{&name[=value]}]] ?
17. A consistent style of references/citations is suggested. For example, the following different ways of referring were encountered:
    1. p3 (Rixon et al. 2007).
    2. p11 McDowell, Tody, et.al, 2007
    3. p19 [RSM, Hanisch et.al, 2005]
    4. p25 [Dolensky 2006]
    5. p43 Internet Assigned Numbers Authority(IANA) [2], etc
    6. Also some of RFCs referred in the text are missing in the reference list or some references in the list are not referred in the text, for example, [Allen et al. 2003]