SLAP RFC Discussion

See the PR latest revised version at: http://www.ivoa.net/Documents/latest/SLAP.html

July 20, 2009 Page created to encapsulate the discussion of the Simple Line Access Protocol RFC process

SLAP Use:

SLAP Implementations:

• SLAP Server Name: IASD
  • Type: Observational
  • Publisher: ESA
  • Service Description: SLAP Access to ISO Astronomical Spectral Lines Database
  • Contact: ESA-VO team
  • Spectral Coverage: IR
  • Number of Records: 300 transitions
  • Comment: Client: VOSpec

• SLAP Name: LERMA
  • Type: Theoretical
  • Publisher: Observatoire de Paris
  • Service Description: LERMA SLAP access to the CDMS and JPL molecules correlated to the Basecol database
  • Contact: N. Moreau & M.L. Dubernet
  • Spectral Coverage: millimetric, sub-millimetric
  • Number of Records: 37500 transitions
  • Comment: Client developed by N. Moreau

• SLAP Name: NIST
  • Type: Observational
  • Publisher: National Institute of Standards and Technology
  • Contact: Yuri Ralchenko
  • Service Description: SLAP Access to NIST Atomic Spectra Database
  • Spectral Coverage: Multiple Coverage
  • Number of Records: 144000 transitions

• SLAP Name: CIELO
  • Type: Observational
  • Publisher: ESA
  • Service Description: SLAP Access to XMM-Newton observed spectral lines from CIELO Database
  • Contact: M. Guainazzi & the rest of ESA-VO team
  • Spectral Coverage: X-Ray
  • Number of Records: 2700 transitions

• SLAP Name: CHIANTI
  • Type: Observational
  • Publisher: Astrogrid using ESAVO DALToolkit
  • Contact: Kevin Benson
  • Service Description: A database for astrophysical emission line spectroscopy
  • Spectral Coverage: Multiple Coverage

SLAP-like Implementations:

• SLAP Name: STSCI SLAP
  • Type: Observational
  • Publisher: STSCI
  • Contact: Randy Thompson
  • Service Description: SLAP prototype of HST lines using ssa data model
  • Spectral Coverage: NIR-Optical
  • Not fully compliant reason: It makes use of Spectral Data Model utypes

• SLAP Name: ALMA internal SLAP
  • Type: Observational
  • Publisher: ALMA Archive Group at The University of Manchester
  • Contact: Stewart Williams, Andrew Markwick-Kemper, Sandra Etoka & Gary Fuller
  • Service Description: Internal SLAP services to propagate line list within the project. IVOA spectral line list data model used in database schema
  • Spectral Coverage: Radio
  • Client: Splatalogue
  • Not fully compliant reason: It contains unidentified lines

Comments:

BobHanisch (9/10/09)

Abstract: The text here is very tentative (“could be too simple...” “will be studied in this document”) and inappropriate for an Abstract, and in particular inappropriate for a standards document. Define the standard and express restrictions and caveats as footnotes or appendices.

JesusSalgado (10/16/09) Text modified accordingly with your suggestions

Overview: Add citation for SSLDM document. [1] in reference list. In the second paragraph, remove the tentative language (“intended to be”).

JesusSalgado (10/16/09) Done

Section 3, 3rd paragraph: what is intended by “must/should/may”? This paragraph is very confusing, suggesting that a MUST parameter could be non-compulsory, for example. It might be clearer, combined with the next paragraph, as “This document describes standard query parameters for SLAP services. Some SLAP services might make use of extra parameters, not cited in this document, to support additional filtering and selection.”

JesusSalgado (10/16/09) Done

Section 3, last paragraph, wording would be better as “Since it is awkward to compile all such extra parameters in a document such as this one, a general mechanism is described. As will be explained later, the discovery of these extra parameters by VO client applications or by the registry relies on an implementation of the format=metadata input parameter. The exact expected response when this parameter appears in the query will be discussed in Section 5.”

JesusSalgado (10/16/09) Done

4.1 The text and formatting make it very confusing to discern the two parts of the URL. The description of the base URL should be more clearly separated from the description of the constraints, with the same indentation and bullet style. The first sentence should be complete and stand-alone, as in “A URL with two parts is used to transmit the spectral line query as an HTTP GET request.” Then,

1) A base URL...

2) A set of constraints expressed as...

The final example line in this section is written as if it is a legal form of query constraint, which I don’t think it is.

JesusSalgado (10/16/09) Modified

4.2 In the definition of REQUEST, I think “server” should be “service”. “Valid values for SLAP” should be “Valid values for REQUEST are”

JesusSalgado (10/16/09) Modified

I’d suggest, instead of “To have backwards compatibility with older SLAP implementations, if the REQUEST parameter does no appear in the query, the default value is queryData (see example of use in next section)” writing “If the REQUEST parameter does not appear in the query, the default value is queryData.” [Again, this is a specificaiton of a standard... it does not need reasons and rationale for everything, just the facts.]

JesusSalgado (10/16/09) Modified

Similarly, I would delete “The use of REQUEST is mandatory to provide upwards compatibility with future versions.” First, there is no need to explain why, and second, how do you know what future versions of the specification will have as mandatory?

JesusSalgado (10/16/09) Deleted

In the last sentence of 4.2, delete “If desired,” and delete the comma midway through the sentence.

JesusSalgado (10/16/09) Modified

4.3 Section title should be “Compulsory Parameters”. The subsequent text is repetitive. Make the first sentence to the point. “The service MUST support the WAVELENGTH parameter, defined as:” In the actual definition, replace “in the vacuum” with “in vacuum”.

JesusSalgado (10/16/09) Modified

4.4 In the paragraph beginning with “Energy Level range” I think “compliant” should replace the word “compulsory”. In the explanation of TEMPERATURE, “score” is probably not the right word. “Sort”? “Rank”? “Order”?

JesusSalgado (10/16/09) Sort

In the explanation of PROCESS_NAME, the “next point” should be “next section”. There is also a typo in “redshift”.

JesusSalgado (10/16/09) Modified

4.5 Instead of “Free query parameters”, perhaps “Additional query parameters”? Again, I think “score” is not quite the right word here. See above.

JesusSalgado (10/16/09) Modified

“...will be studied in the next section” should be “...will be defined...”.

JesusSalgado (10/16/09) Modified

“construct on the fly a form” would be better as “dynamically construct a form”

JesusSalgado (10/16/09) Modified

I would delete the last paragraph in 4.5 as it is about uses of the registry and not germane to the definition of SLAP.

JesusSalgado (10/16/09) Modified

5 I think there is continued mixing of registry and SLAP issues here and that this could be simplified.

“Simple Spectral Line services advertise their availability by registering with a registry service, which may provide the mechanisms to fully characterize the service including its non-compulsory and additional parameters. Alternately, the FORMAT=METADATA parameter or REQUEST=getCapabilities can be used to ascertain the service’s full capabilities.”

JesusSalgado (10/16/09) Modified

Use consistent spelling of “implementer”, here and elsewhere.

JesusSalgado (10/16/09) Modified

5.2 Is this needed in this document at all? I’d drop it, and then merge 5.1 into 5.

JesusSalgado (10/16/09) Modified

6. Add citation [6] to VOTable. Item 1, “addition” --> “additional” Item 4, “the following UCDs” suggests that a list follows immediately, but it doesn’t. I think this refers to Section 6.1.

JesusSalgado (10/16/09) Modified

6.1 “in the vacuum” --> “in vacuum”.

JesusSalgado (10/16/09) Modified

slap.QueryScore, as noted above, I think a term like “rank”, or perhaps “relevance”, would be better. Not sure if people have used this already; if so, I would not push very hard for this change. “sorter” --> “sorted”

JesusSalgado (10/16/09) Score is in line with current SSAP, so we would prefer to maintain it as it is

Further down (p. 15 in the .doc version), “LATEX” should be “LaTeX” and “convection” should be “convention”. A citation to the LaTeX manual needs to be provided. (Leslie Lamport, “LaTeX: A Document Preparation System.” Addison-Wesley, 1986)

JesusSalgado (10/16/09) Modified

p. 16, “enclosed by squares” --> "enclosed by square brackets”

JesusSalgado (10/16/09) Modified

p. 17, top, “previous point” --> “previous section”

JesusSalgado (10/16/09) Modified

Did not read Apps. B, C, and D.

JesusSalgado (10/16/09) Thanks for your comments.

Ray Plante

Abstract, p.2, last sentence.

a bit of word-smithing for style:

• consider collapsing text into a single paragraph
• consider rewriting (what is now) the last paragraph:

Thus, an implementation of the service may support additional search parameters (some which may be custom to that particular service) to more finely control the selection of spectral lines.

JesusSalgado (10/16/09) Modified

Contents, p.3

Entries "UTYPE" through "Size" seem spurious.

JesusSalgado (10/16/09) Modified

s1, p.3, Overview

I think it would be useful to add some words that explicitly call out the consistency with SSAP via the adoption of current conventions for DAL service interfaces. Perhaps something like this:

The SLAP interface has intentionally been made similar to that of SSAP and SIAP (v2.0) through the adoption of current IVOA Data Access Layer conventions, including:

• queries encoded as URLs
• the use of standard input parameters, REQUEST and VERSION,
• the syntax for specifying numeric ranges and value lists,
• the use of VOTable for encoding search results,
• the mechanism for handling errors, and
• the retrieval of service metadata.

JesusSalgado (10/16/09) Modified

s4.2, required parameters

Maybe I missed this: Is a query with no parameters after the base URL legal? Or must the query include certain parameters? It seems that s4.1 and s4.2 only indicate what the service must support. A statement about the parameters required to be in the query should be given.

JesusSalgado (10/16/09) Modified

s4.1, p5-6, range constraints

I'm not sure putting the description of the range syntax in an appendix is appropriate as it reflects a requirement that can determine whether a service is compliant or not. Putting it into the appendix would be okay if s4.1. made a statement like:

A parameter value represents a range constraint when it matches the syntax for range values as defined in the SSAP protocol [ref] section 8.7.2.

JesusSalgado (10/16/09) Modified

In this case, the standard is defined explicitly by the other document; the appendix, then, provides a summary of that syntax so that the reader need not go to that document to understand the syntax. We also keep the examples in section 4.1 for the same reason.

s4.2, p.6, Input Parameters, para. after REQUEST bullet

Change "does no appear" to "does not appear"

JesusSalgado (10/16/09) Modified

s4.2, p.6, Input Parameters

In general, I'm finding the presentation of the parameters clunky. Here, it says, "...define the following standard parameters:" and what immediately appears is only one parameter. Some of the description of REQUEST is part of a bullet and some is not, and it is not clear what the utility of the bullet is. I recommend the following:

• make s4.3 and s4.4 subsections of 4.2 (i.e. 4.2.x). (This is motivated by the fact that the 1st paragraph of s4.2 applies to all input parameters.)
• created a subsection 4.2.1 "Standard Parameters" to contain the definitions of REQUEST and VERSION.
• further divide 4.2.1 into 2 subsections, one for each parameter, using either the style from SIA v1.0 (s4.1, explanation of parameter is set in definition style) or SSA (s8, where each parameter has its own number subsection. (I would prefer the SSA style.)
• do not use bullets to set off the definition of parameter.

JesusSalgado (10/16/09) Document modified in this line

s4.3, s4.4 Compulsory/Non-compulsory Parameters

The same problem described above applies here to, but also the presentation causes redundant statements to be made; see "Emission probability" and EINSTEIN_A parameter. So, following on the item above, I would recommend that one of the suggested presentation styles be adopted here as well. In either style, related parameters can be grouped together to provide a place for general explanation of them as a group.

JesusSalgado (10/16/09) Modified

s4.3, s4.4, use of ucd/utype reference

This is a very useful thing to have; however, we need a place to explicitly state what this annotation means. I recommend that in s4.2 a paragraph be added something like (assuming my recommended re-org):

The following subsections define reserved parameters. In addition to the description of the functional role the parameter plays in constraining a query, each definition also includes, when applicable, a UCD [ref] and/or UType [ref] that indicate the semantic meaning of the parameter. The UType names refer to those defined in the Simple Spectral Line Data Model [ref].

JesusSalgado (10/16/09) Modified

s4.3, p.7, Compulsory input

I recommend changing this section title to "Required Input" for consistency with s2.1. The text should make clear that the requirement is on the service to support the parameter rather than the requirement on its inclusion in the query (if in fact that is the case--did I misread this?).

JesusSalgado (10/16/09) Already modified to Standard Parameters and note added

s4.5, p.10, Free query parameters

Use of "free" may not be immediately clear to all readers; I recommend that you refer to these as "custom parameters" and explicitly define this as meaning a parameter that is specific to and defined by a service instance.

JesusSalgado (10/16/09) Modified

s4.5, p.10, first paragraph

change "point 3" to "section 3".

JesusSalgado (10/16/09) Modified

s4.5, p.10, last sentence

we need to avoid vague statements about the future like this. Either the discover process is well defined in this document, or it is considered out of scope of this document.

JesusSalgado (10/16/09) Modified as per Bob's suggestions

s5.2, p.12, Registering a Complant Service

This document cannot go forward in the recommendation process with a statement like this still included. Either this mechanism for registering is spelled out here or it is out of scope. More specifically, this section should say that it is expected that users can discover a service instance through an IVOA-compliant registry [ref to RI]. The description of the instance in a registry is an XML document that complies with the VOResource resource description standard [ref to VOResource]. In particular, the description is recognized as a instance of a SLAP service when it complies with the SLAP VOResource extension. That extension should then either be spelled out in that section or in an external document via an explicit reference.

JesusSalgado (10/16/09) Section 7 added as per suggestions including references. Detailed description of registry negotiation is out of the scope of present document

s6, p.12, Successful Output, use of utype, ucd

The use of utypes and ucds need some clarification. In particular, how is a client meant to uniquely identify a standard column? Must it match all of the attributes stated in the individual column definitions? Or would utype or ucd be sufficient? This should be spelled out, and these rules will affect when a utype or ucd is required to be included. I would suggest the following rules:

• When a standard column can appear multiple times with the same utype but different units, the column is uniquely identified by its utype and unit.
• Otherwise, a standard column is uniquely defined by its utype.

Given this, standard columns must include the defined utype. I think that a standard column must also include the defined ucd. Non-standard columns should provide utypes and ucd when applicable, and utypes should preferentially be drawn from the SSLDM when applicable. The numbered items under S6 should be revised to reflect these rules.

JesusSalgado (10/16/09) Modified

s6, p.12-15, namespace definitions

this section indicates that the response must include xmlns prefix definitions for the data models when they are referenced:

• xmlns:ssldm="http://www.ivoa.net/xml/DmSSLDM/v1.0"
• xmlns:slap="http://www.ivoa.net/xml/DalSlap/v1.0"
• xmlns:char="http://www.ivoa.net/xml/DmCHAR/v1.13"

I do not believe these are defined anywhere else (i.e. in other documents). Although these URIs identify data models, I believe this is completely consistent with the XML standard. I note, however, that the base URI is also used to refer to IVOA XML Schemas; in particular, these are intentionally made resolvable to the actual XML Schema document itself. In order to remove the ambiguity as to whether a particular IVOA URI is resolvable or not, could we change the base URI to "http://www.ivoa.net/dm/"?

JesusSalgado (10/16/09) Now in line with current SpectrumDataModel schema location, e.g., http://www.ivoa.net/xml/SimpleSpectrumLineDM/SimpleSpectrumLineDM-v1.0.xsd format

s6.1, p.13, Standard output fields

I recommend changing "Syntax is free" to something more specific, like:

There is no required syntax, but it is recommended that common species and transition notation be used when applicable.

JesusSalgado (10/16/09) Modified

s6.1., p.14, last bullet

Style recommendation: the last two bullets on the page are related; can we make the last one just a new (indented) paragraph so that it appears logically connected to the previous bullet?

JesusSalgado (10/16/09) Modified

s6.1, p.15, ssldm:Line.*Level.configuration

I feel "We have selected the LATEX convention" is a bit too wishy-washy; is this a standard defined by example? To tighten this up, its important to know (and state) is this syntax expected to be parsable, or is it just for display purposes? Special, non-verbatim display by a client is possible in the simple cases (of just superscripts) but it would get limiting if arbitrary LaTeX commands were included. I would recommend a statement such as this:

There is no required syntax for this string; however, it is recommended that a LaTeX-styled syntax be employed.

Then proceed with the examples.

JesusSalgado (10/16/09) Modified

s6.1, p.15, ssldm:Line.*Level.quantumState

recommend these edits for clarity

• change "The format would be...:" to "The format must comply with the following syntax:"
• change "i.e., every quantum number is defined by:" to "where:"
• use this style for each bullet: "label is a legal value for the model component given by ssldm:Line.initial...".

JesusSalgado (10/16/09) Modified

s6.1, p.16, 2nd para

change "squares" to "square brackets" (yes?)

JesusSalgado (10/16/09) Modified

s6.1, p.16, after "ssldm:Process.type"

stray bullet

JesusSalgado (10/16/09) Modified

s6.1, p.16, "ssldm:Process.type" example

Should quotes appear in the value? I'm not sure I see the need for them. (Does it have something to do with the VOTable syntax for array values, which is not applicable to strings?) Plus, when this value appears as a PARAM, then single quotes must be used to enclose the full attribute value.

JesusSalgado (10/16/09) Modified

Appendix B

p.18, first para.: change "proposed syntax" to "recommended syntax".

JesusSalgado (10/16/09) Modified

Appendix B

p.18-20: It's not clear that this should be a appendix. It defines some additional columns. Are these actual standard columns that clients can count on, or is it just a suggestion? If it is the former, then it should not be an appendix.

JesusSalgado (10/16/09) This should not be used, in general, by standard SLAP servers. It was added to give support to non-standard SLAP server of raw data, so we consider it should be an appendix to do not mix these parameters with the standard ones

Appendix D

change "compulsory" to "required" for consistency with section 2.1. (BTW, this appendix is very helpful.)

JesusSalgado (10/16/09) Modified

-- RayPlante - 16 Sep 2009

RFC period comments from Working and Interest Groups

Applications

Data Access Layer

-- JesusSalgado & AurelienStebe 10-Sep-09

JesusSalgado (10/16/09) Reference to SSAP added as per Ray's suggestion. That should cover the standard way to handle errors in DAL protocols

Data Modeling

Grid & Web Services

Resource Registry

• VOResource extension schema has been created and uploaded to IVOA pages

-- AurelienStebe & JesusSalgado 10-Sep-09

JesusSalgado (10/16/09) Registration section considered out of the scope of present document. Document updated in this line as per Bob's and Ray's comments

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

OGF Astro-RG (MasatoshiOhishi)

(1) In section 4.3, WAVELENGTH is designated as a compulsory parameter, which I agree. However, it is not common in the radio or submillimeter range to use wavelength. The common practice for radio astronomers is to use "frequency" rather than "wavelength". I would suggest to add "frequency" as another compulsory parameter. In this case MHz/GHz(/THz) need to be added as allowed "units".

(2) Section 4.4, Energy Level range; I think the units for the energy levels should be more flexible. In the X-ray region it is common to use eV (keV, MeV, etc.). Similarly, wave number (cm-1) is also used in the IR region. In many cases it is very convenient to express the energy levels in Kelvin or in MHz.

(3) Section 6. If we add FREQUENCY as a compulsory parameter, we need to update this section, too.

(4) Page 16, expression of the quantum states; it is unclear to me how this document is going to express the quantum states for the inversion lines (e.g., NH3) or molecules with internal rotation (e.g., CH3OH, (CH3)2O).

-- MasatoshiOhishi

Replied by JesusSalgado

• First, thanks for your comments.

-- JesusSalgado - 03 Sep 2009

Theory

TCG

TCG Review: Working and Interest Groups

Applications

Data Access Layer

Sec1, pg 3, 2nd para: "physics of the problem force to do it" I think should be "force us to do it"

Sec1, pg 3, last para: "two steps processes" should be "two step"

Sec 4.2.4, pg 10, 2nd para: "... the way to notify to a VO client the implementation or not of these parameters ...." Better wording might be "client applications can discover whether a particular parameter is implemented through the FORMAT=METADATA....."

Sec 6, pg 12: Item 4 says "Each row of the output VOTable MUST contains FIELDs where the following UCDs have been set", however no UCDs are ever listed

Page 17: Quotes should be removed from the example box (they aren't used elsewhere)

App B, pg 19, 2nd para: "This correction is most of the times quite complex" better as "This correction is often quite complex...."

MikeFitzpatrick - 23 Jun 2010

Replied by JesusSalgado

Thanks for the comments. The text has been updated following your recommendations -- JesusSalgado - 10 Sep 2010

Data Modeling

Grid & Web Services

The document is well written and I approve it. -- MatthewGraham - 16 Jul 2010

Resource Registry

Semantics

The following typos should be fixed, but other than these, I approve the document. SD.

p10 ucd="phys.at.transProb" -> "phys.atmol.transProb" p12 & 21 ucd="obs.id" -> "meta.id;obs" p24 ref 10 first author is Preite-Martinez

VO Event

Approved. -- RobSeaman - 15 Sep 2010

VO Query Language

VOTable

Data Curation & Preservation

I appreciate the authors' careful attention to comments raised previously.

I would like to see a change log included in the document listing differences between this version and the version of July 2009.

BobHanisch 28 May 2010

Replied by JesusSalgado

Thanks ot you for the careful review. I have added a change log table to better track the changes.

-- JesusSalgado - 10 Sep 2010

Theory

Comments on the PR-SLAP-1.0-20091016.pdf document.

(1) I have noted a mispelling of the word ENERY (last example on page 6): INITIAL_LEVEL_ENERY<=1.6E-17

(2) Is there a general agreement in IVOA on using LaTeX for mathematical formulae or greek letters? There was some discussions during the last INTEROP on using the MathML W3C recommendation. Is MathML applicable/useful in your case?

-- HerveWozniak - 26 May 2010

Replied by JesusSalgado

Typo corrected About the use of MathML, it is an interesting alternative to a LaTeX representation. However, it is not clear for me yet how to serialize this inside a VOTable response due to the XML. We would prefer to wait for a more deeper discussion between the IVOA before to go in this line.

-- JesusSalgado - 10 Sep 2010

TCG

The document is well structured and easy to understand.

Two minor comments:

• as agreed, in the abstract, please add the link to the newly agreed IVOA Architecture
• (typo) on page 11, the "MUST" should be put in bold like all similar words in the document

A more open question, to be tackled in coordination with the Registry WG from (section 7 and Ref [12])

• Should SLAP use an extension to the VOResource or the newly defined SimpleDALRegExt ?

Assuming these points will be addressed for the final version, I approve the document.

ChristopheArviset - 25 june 2010

Replied by JesusSalgado

• Link to the IVOA Architecture added
• Typo corrected
• In order to do not delay the process and as SimpleDALRegExt does not deal with SLAP services yet, we maintain the link to the specific VOResource extension and we will update the xsd to point to SimpleDALRegExt as soon as this was ready.

-- JesusSalgado - 10 Sep 2010

<-- 

 

 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
 
-->