Comments on SIA Version 1.0

This page summarises comments I have after working on implementing a SIA server python script for ESO and a SIA C++ client for stellarium. The comments are based on the SIAP working draft document version 1.0. available here: http://www.ivoa.net/Documents/latest/SIA.html

Errors in the document

• In the example from section 7.1, the PARAM tags describing all the supported FIELD in a METADATA query should have a datatype and arraysize attribute to comply with VOTable 1.1 specifications.
• In the example from section 7.1, the OPTION tag contain text data between <OPTION> and </OPTION> while this is forbidden by the VOTable standard (at least it is what is in the SIA xml schema v1.0 xsd file). The text should be in <OPTION value="text"/>

Suggestions

• Section 4.2 says that the RESOURCE element should contain an INFO with name="QUERY_STATUS" telling whether the query was successful or not. The problem is that the VOTable standard specifies that the INFO tag in a RESOURCE must be located before the TABLE tag (at least it is what is in the SIA xml schema v1.0 xsd file). This means that we must tell whether the query was successful before outputing any row of data. This causes an obvious problem in case of streaming server. Note that as far as I could see on many existing implementations, the INFO is output after the TABLE and therefore the document is not VOTable 1.1 compliant. A solution to this problem is either to modify the VOTable standard to allow INFO to be output after TABLE, or to encapsulate the INFO with name="QUERY_STATUS" in another RESOURCE located after the TABLE.
• It would be nice to have a new version of the document with updated UCD+ (see http://wiki.eurovotech.org/twiki/bin/view/VOTech/SiaUcd2Ucdp for a translation table)
• In section 4.2, for some output FIELD, the physical unit is not specified (for example for the RA and DEC position). However, for some other it is specified like for VOX:Image_Scale where the document says that it must be in degree per pixel. It would be convenient to have a well defined unit for each field when possible. This really simplify the implementation of a parser, since units as defined in the VOTable standard (see http://cdsweb.u-strasbg.fr/doc/catstd-3.2.htx) are very complex to parse. I propose to adopt and specifiy to use degree (deg) and pixel (pix) wherever possible.
• What is the use of the ucd VOX:BandPass_Unit when unit should already be specified in the FIELD tag? If we want to force users to use one of "meters", "hertz" and "keV" it would be simpler to define that the unit attribute of the VOX:BandPass_RefValue/HiLimit/LoLimit should be one of "m", "Hz" or "keV" as defined by the VOTable standard. This also is more consistent with the previous point.
• How to format in output datatype=int and arraysize=* like for VOX:Image_Naxis? "512,320" or "512 320"?
• It would be nice that VOX:Image_Title be unique.
• The returned image size: in section 4.1.2, it is specified that if SIZE=0, the server must return the images with which the given point intersects. The problem is that it also define in this section that in this case, returned images sizes will be service-defined. There is thus a conflict with the NAXIS parameter (more or less solved by saying in section 4.1.3 that parameters MUST be consistent). It would be easier to define that the returned image size is specified only by NAXIS and that if NAXIS=0, the image size is service-defined. After all the ROI and the image size have no reason to be linked.

Ambiguities for the management of input parameters

When I was implementing my SIA server in python, I tried to follow as much as possible the standard. However there are some cases where the behaviour is undefined, or where the standard allows unconsistent inputs.

Current standard

First let's define some words that will be used in this document:

from my understanding of the SIA 1.0 standard, an input parameter can be:

• Supported or Unsupported: whether it is taken into account by the server or not. From the SIA specification, Unsupported parameters should be silently ignored.
• User-Required: if the parameter MUST be present in the query. Section 7.2 mentions that these parameters are POS, SIZE and FORMAT (Although this last one is not consistent with 4.1.4). User-Required parameters MUST be supported by the server. Note that in the SIA 1.0 standard, these parameters are refered as "required", but we prefer the term "User-Required" in this document to avoid confusion.

the value for an input parameter can be:

• Legal or Illegal : if it complies to the possible values described by the SIA specification.
• Supported or Unsupported: if it is understood by the server or not. For example, a server may be able to return images with CFRAME=ICRS, but not with CFRAME=FK4. In this case ICRS is Supported while FK4 is Unsupported.

Table 1: this table summarize the informations for all the Standard Parameters as defined in SIA Version 1.0. Cells with * indicate that some clarifications/correction have been proposed in table 3.

Input Parameter	User-Required	Server Supported	Domain of legal values	Default value	Unit
POS	yes*	MUST	<0..360>,<-90..90>*	-	degree
SIZE	yes*	MUST	<0..360>[,<0..180>]*	-	degree
INTERSECT	no	MAY	one of OVERLAPS,COVERS,ENCLOSED,CENTER	OVERLAPS**	-
NAXIS	no	MAY	<0..inf>[,<0..inf>]	Determined from POS and SIZE**	pixel
CFRAME	no	MAY	one of ICRS,FK5,FK4,ECL,GAL,SGAL	ICRS**	-
EQUINOX	no	MAY	undefined*	B1950 if CFRAME=FK4, J2000 otherwise**	-
CRPIX	no	MAY	<int>[,<int>]	Image center**	pixel
CRVAL	no	MAY	<double>,<double>	transformed center of the image (see document)**	degree*
CDELT	no	MAY	<double>[,<double>]	"implied or service specific"**	degree/pix
ROTANG	no	MAY	<double>	0**	degree
PROJ	no	MAY	one of TAN, SIN, ARC etc..	TAN**	-
FORMAT	yes***	MUST	combination of ALL, GRAPHIC, METADATA, GRAPHIC-ALL, GRAPHIC-jpeg,png,gif, <string>	ALL***	-
VERB	no	MAY	0 or 1 or 2 or 3	undefined*	-

* Must be clarified or defined in the SIA document.

** Unconsistency. Default values for non-MUST parameters cannot be defined other than "service-specific". If we really want to give a default value for them, then the server MUST support them.

** * Unconsistency, a User-Required parameter should not have default value, or a parameter with a default value should not be User-Required.

Problems

Table 2: the following table show the behaviour of my server for all the possible combinations of input param/value that a SIA server have to manage: the notes give informations when the standard is not clearly defined for some cases.

	Value for this param is
Input Parameter is	Legal Supported	Legal Unsupported	Illegal (Unsupported)	Not Given
User-Required (Supported)	OK	-	ERROR (1)	ERROR (2)
Supported	OK	Empty Table (3)	ERROR (4)	Default Value used (5)(6)
Unsupported	ignored	ignored	ignored	-

Notes:

(1) : Not clearly specified in the SIA document, but an example is given in section 4.3.2.

(2) : Not clearly specified in the SIA document, it is only mentioned in section 7.1 that some parameters are required, but without further explanations. Insection 7.1 the parameter FORMAT is refered as User-Required, however in section 4.1.4, a default value is given for it (FORMAT=ALL). This should not happen. Either a parameter is User-Required, and in this case no default value is needed, either it is not User-Required, and a default value can be given. In this case it is likely that we don't want FORMAT to be a required parameter.

(3) : For example, when the user requests a file format which is not supported by the server.

(4) : This one is unspecified in the standard. For example if the user request INTERSECT=TYPOERROR, the server will return with ERROR status.

(5) : This works if a default value is defined for the parameter. E.g if CFRAME is not given, "ICRS" will be used by default, or if INTERSECT is not given, "OVERLAPS" will be used by default. However this means that the server MUST support the default value for all non-MUST parameters! If the default value is not supported, the server cannot silently use another default value since it would be unexpected by the client!

(6) : If no default value is defined by the SIA standard, the behaviour is unspecified. This concerns only the VERB parameter.

Solution

It follows from (5) that if an input parameter is Supported by the server and the default value for it is not supported, the behaviour is unspecified. For example, a server which provides image in the FK5 and ECL frame but not ICRS cannot support the default value. Either the standard decide that this server does not respect the SIA standard, either the default value for CFRAME should be defined as "SERVICE_DEFINED".

To clarify all of this, I propose that for each input parameter we define precisely:

• Whether it is Required, i.e. whether the USER MUST give a value for it otherwise we return a status = ERROR
• The domain of values for it to be Legal: for example the DEC part of POS must be included in [-90;90] etc.. If the value is outside the legal domain, the query would return status=ERROR
• Its default value if it is not a Required parameter. If the parameter MUST NOT necessarily be supported by the server, its default value MUST be "SERVICE_DEFINED", and nothing else (we have to keep in mind that giving a precise default value such as CFRAME=ICRS by default implicitely forces the server to support the parameter, and therefore it MUST be supported).

Table 3: Below is the same table as before with the proposed modifications in bold italic:

Input Parameter	User-Required	Server Supported	Domain of legal values	Default value	Unit
POS	yes	MUST	<0..360>,<-90..90>	-	degree
SIZE	yes	MUST	<0..360>[,<0..180>]	-	degree
INTERSECT	no	MUST	one of OVERLAPS[,COVERS,ENCLOSED,CENTER]	OVERLAPS	-
NAXIS	no	MAY	<0..inf>[,<0..inf>]	SERVICE_DEFINED	pixel
CFRAME	no	MAY	one of ICRS,FK5,FK4,ECL,GAL,SGAL	SERVICE_DEFINED	-
EQUINOX	no	MAY	one of J2000, b1950, <double>	SERVICE_DEFINED	-
CRPIX	no	MAY	<int>[,<int>]	SERVICE_DEFINED	pixel
CRVAL	no	MAY	<double>,<double>	SERVICE_DEFINED	degree
CDELT	no	MAY	<double>[,<double>]	SERVICE_DEFINED	degree/pix
ROTANG	no	MAY	<double>	SERVICE_DEFINED	degree
PROJ	no	MAY	one of TAN, SIN, ARC etc..	SERVICE_DEFINED	-
FORMAT	no	MUST	combination of ALL, GRAPHIC, METADATA, GRAPHIC-ALL, GRAPHIC-jpeg,png,gif, <string>	ALL	-
VERB	no	MAY	0 or 1 or 2 or 3	SERVICE_DEFINED	-

-- FabienChereau - 16-Feb-2007