==================== IVOA Simple Image Access ==================== Official bibliographic entry for published version :cite:p:`2015ivoa.spec.1223D`. :Status: SIA 2.1 WD 2022-04-25 .. role:: raw-latex(raw) :format: latex .. .. _`SIA:acknowledgments`: Acknowledgments =============== The authors would like to thank all the participants in DAL-WG discussions for their ideas, critical reviews, and contributions to this document. .. _`SIA:introduction`: 1 Introduction ============== The Simple Image Access (SIA) protocol defines several capabilities to support discovery and access to astronomical image datasets of any dimension. Typical image datasets include 2-D spatial images, spectral data cubes, and cube and hypercube data of higher dimensions as well as derived image data products. The underlying :doc:`ObsCore <../ObsCore/ObsCore>` data model is a simplified view on the typical image datasets derived from observational data, which have some combination of spatial, spectral (including velocity and redshift), time, and polarization axes. For complete access to datacubes, the SIA-2.0 specification makes use of features defined in :doc:`DataLink <../DataLink/DataLink>` :cite:p:`2023ivoa.spec.1215B`. It also makes use of AccessData services, as well as custom data services. .. container:: float :name: SIA: .. raw:: latex \centering |image| :raw-latex:`\label{fig:architecture}` SIA defines data discovery and metadata capabilities that work with other DAL services to enable image and data cube access. The basic interface for the capabilities defined in this specification are described in :doc:`DALI <../DALI/DALI>` :cite:p:`2017ivoa.spec.0517D`. :doc:`DataLink <../DataLink/DataLink>` can be used with SIA for finding access URL(s) for files, related resources, and data services such as AccessData (in development). SIA services also support VOSI-availability and VOSI-capabilities :cite:p:`2017ivoa.spec.0524G` resources. The :doc:`ObsCore <../ObsCore/ObsCore>` data model has been defined in \cite{std:OBSCORE}, it contains and organizes the minimal set of metadata necessary to discover datasets of interest for a specific purpose. The metadata returned from the SIA data discovery request is defined by the :doc:`ObsCore <../ObsCore/ObsCore>` data model and serialized according to the ObsTAP specification :cite:p:`std:OBSCORE`; this may be extended with additional metadata (columns) in the future. A future version of SIA may define a separate resource for accessing the complete data model metadata for a single dataset once such a model is available. Data discovery responses are returned in :doc:`VOTable <../VOTable/VOTable>` :cite:p:`std:VOTABLE` format unless an alternate format is requested. .. _`SIA:the-role-in-the-ivoa-architecture`: 1.1 The Role in the IVOA Architecture ------------------------------------- SIA specifies standardID values for each capability, as defined by :doc:`VODataService <../VODataService/VODataService>` :cite:p:`std:VODS11`. SIA services may be registered in an IVOA Registry using the SimpleDALRegExt :cite:p:`std:DALREGEXT` extension schema. .. _`SIA:changes-from-sia-1.0-to-sia-2.0`: 1.2 Changes from SIA-1.0 to SIA-2.0 ----------------------------------- Virtual Observatory access to astronomical images has been available via the SIA-1.0 protocol for over a decade. Many such services have been implemented since 2002, and SIA-1.0 :cite:p:`std:SIAP` was formally standardized as an IVOA Recommendation in 2009. The legacy SIA standard however pre-dates much of the VO technology developed since 2002, and is limited to two-dimensional images. SIA-2.0 is multi-dimensional and fully integrated with the modern VO architecture and related standards. SIA-2.0 differs from legacy SIA-1.0 in the following aspects: - The capabilities for dynamic access to image datasets are expanded in scope, but are separated from data discovery and download of whole image datasets. A separate "AccessData" specification currently under development will define the more advanced dynamic data access functionality. Automated virtual data generation and discovery (as in SIA-1.0) is not currently supported but is being considered for a future version of SIA. - Description of Image datasets is now provided by the more abstract :doc:`ObsCore <../ObsCore/ObsCore>` data model, providing more comprehensive high level dataset metadata, most of which is common to other classes of astronomical data. Most of the attributes of the model can be queried using standard parameters, where SIA-1.0 only standardized positional queries. - The version of :doc:`VOTable <../VOTable/VOTable>` used in the protocol (2.1) has been updated and distinguishes between UCD and UType attributes. SIA-1.0 used a custom class of UCDs that pre-dated what are now UTypes, where :doc:`ObsCore <../ObsCore/ObsCore>` specifies standard UCD and UType values for use in the :doc:`VOTable <../VOTable/VOTable>` output. - Most elements of the SIA-2.0 service interface are standardized across all DAL interfaces, as defined separately by the :doc:`DALI <../DALI/DALI>` interface standard. - SIAV2 supports the new :doc:`DataLink <../DataLink/DataLink>` standard, providing additional capabilities for data access as well as the ability to link to related data products, as well as the VO Image data model standard currently under development, providing a full description of the structure of an image dataset. While some of the more advanced capabilities for dynamic access to multi-dimensional images are still under development, the initial specification provides the capability to discover and download multi-dimensional image datasets via a service interface consistent with current VO standards .. _`SIA:current-and-future-support`: 1.3 Current and Future support ------------------------------ These are the list of changes which will be considered in a later version of this protocol (SIA-2.1): - The protocol should support a detailed metadata capability. In the current design, this capability will take a single parameter with an identifier (typically a publisher dataset identifier from a data discovery response) and return a document with detailed metadata about the dataset. The primary usage is to drill-down to the detailed metadata after discovery - The standardID for the metadata capability will probably be : ivo://ivoa.net/std/SIA#metadata-2.1 - The parameter language should be extended to support case-insensitivity, wildcards, and pattern recognition. - The :doc:`DALI <../DALI/DALI>` UPLOAD facility will be defined in order to allow queries based on values stored in a file. - The protocol will also support an option for virtual data discovery. With this option, controlled by usage of an optional parameter, the query can force the discovery of virtual datasets with best matching to the input parameter constraints - COLLECTION and FACILITY currently provide query parameters provide selection on service defined set of strings. It would be good to define standardized lists of those at IVOA level for next version. - Visibility data and event lists are not considered as valid DPTYPES in this version due to complexity of data access functionalities for those dataset types. .. _`SIA:motivating-use-cases`: 1.4 Motivating Use Cases ------------------------ Below are some of the more common use cases that have motivated the development of the SIA specification. While this is not complete, it helps to understand the problem area covered by this specification. .. _`SIA:simple-data-discovery`: 1.4.1 Simple Data Discovery ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Simple data discovery entails finding services that provide parameter based discovery of images and datacubes, querying the service(s) with a few well known kinds of queries that cover greater than 95% of use, and getting back easily parsed summary metadata about each available data product. The service discovery would be performed with an IVOA Registry search using a new service type defined for SIA-2.0. The query for data would need to allow for querying in position, energy, time, and polarization: - find data that includes specified coordinates (e.g. for some object) - find data in the circle with coordinate centre and radius - find data in a range of longitude and latitude - find data within a specified simple polygon (one region, no holes, less than half the sphere) - find data containing a specified energy (e.g. wavelength) or in a specified range of energy values - find data obtained at a specified time (e.g. including a time instant) or during a specified range of times - find data obtained with specified polarization (Stokes) states - find data within a specified range of spatial resolution - find data within a specified range of field-of-view - find data within a range of exposure (integration) time Queries can also combine any of these kinds of constraints (e.g. query using position and energy, position and time, etc.). Queries should be easily formulated with parameter-value pairs. .. _`SIA:get-detailed-metadata`: 1.4.2 Get Detailed Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The data discovery phase returns a subset of the available metadata. Clients may need additional detailed metadata (as defined by the ImageDM specification) in order to make decisions or perform computations required to access the data (e.g. using a separate low-level data access service as described in the draft AccessData specification). The client must be able to easily figure out if detailed metadata is available and, using an identifier from the discovery response, make a call to a web service to retrieve the detailed metadata. .. _`SIA:sec:sync`: 1.4.3 Download Complete Datasets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The client should be able to download complete datasets with information available in the discovery response. If the dataset is a single file, the service should provide an access URL to the file; if it is multiple files, then an access URL to a :doc:`DataLink <../DataLink/DataLink>` service [9] can be provided, but the client must be able to easily distinguish these two scenarios. .. _`SIA:sec:async`: 1.4.4 Access a Datacube with Operations: Too Big to Download ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In many cases, datacubes are too large to download and process locally, so the client must be able to perform remote operations. Data discovery could be performed using any discovery protocol (SIA, :doc:`TAP <../TAP/TAP>` with :doc:`ObsCore <../ObsCore/ObsCore>`, etc.). The client must be able to easily figure out if a low level access service is available for a discovered dataset. This could be using a URL provided in the response or by calling an associated :doc:`DataLink <../DataLink/DataLink>` service. Access operations include basic filtering (cut out a subsection of the data), transformations, or other pixel-level operations or even analysis. With current version of the AccessData specification, we will only cover extracting a simple subset of an image or datacube. .. _`SIA:sec:examples`: 1.5 Scope and Related Documents ------------------------------- This document can support use cases 1.4.1, 1.4.3, and 1.4.4; support for 1.4.2 has been deferred to a future version. Some of the support for these use cases is provided by the separate capabilities defined in the :doc:`DataLink <../DataLink/DataLink>` and AccessData specifications. Together, these three specifications, plus :doc:`TAP <../TAP/TAP>` :cite:p:`2019ivoa.spec.0927D`, and within the framework provided by :doc:`ObsCore <../ObsCore/ObsCore>`, and the future image and cube data model provide a set of capabilities required to support a broad range of use cases. .. container:: float :name: SIA: .. raw:: latex \centering |image1| :raw-latex:`\label{fig:architecture}` Each box in the above diagram shows a single capability. The SIA query capability is defined in this specification; the SIA metadata capability will be defined in a later version of this specification, once the ImageDM is completed. :doc:`DataLink <../DataLink/DataLink>` and AccessData are separate specifications. The dashed lines represent optimisations that are mentioned in use cases above, where subsequent service usage should be easy to discover and invoke. .. _`SIA:sec:parameters`: 2 Resources =========== The SIA data discovery capability is implemented as a synchronous resource conforming to the DALI-sync specification. .. raw:: latex \begin{tabular}{lll} \sptablerule \textbf{resource type}&\textbf{resource name}&\textbf{required}\cr \sptablerule \texttt{\{required\}}&\texttt{service specific}&{yes}\cr \texttt{DALI-examples}&\texttt{/examples}&\texttt{no}\cr \texttt{VOSI-availability}&\texttt{/availability}&\texttt{yes}\cr \texttt{VOSI-capabilities}&\texttt{/capability}&\texttt{yes}\cr \sptablerule \end{tabular} An SIA service must have at least one {query} resource; it could have multiple {query} resources (e.g. to support alternate authentication schemes where the path is different). All {query} resources must be siblings of the VOSI-capabilities resource; this limitation enables a client with just the URL for an SIA query resource (e.g. from a Datalink service descriptor) to find the VOSI-capabilities resource and discover all the capabilities provided. .. _`SIA:sec:query`: 2.1 {query} resource -------------------- The {query} resource is a synchronous web service resource that conforms to the DALI-sync description. The implementer is free to name (set the path of) this resource however they like; the client will find the resource path using the VOSI-capabilities resource. As a DALI-sync resource, the parameters for a request may be submitted using an HTTP GET (query string) or POST action. All parameters for the {query} resource defined below must be supported by the service. Services must accept parameters and apply the constraints such that if a (:doc:`ObsCore <../ObsCore/ObsCore>`) record does not satisfy the constraints it is not included in the response. If the metadata for a field is not known (null), the constraint cannot be satisfied. The :doc:`ObsCore <../ObsCore/ObsCore>` data model defines which fields may be null and which must have a value. For example, if dataset(s) have unknown time coverage (t_min and t_max in :doc:`ObsCore <../ObsCore/ObsCore>`), a query with the TIME parameter must not return the record(s); queries without the TIME constraint could still return such records, so the caller can discover such dataset(s). Client requests may include zero or more of the query parameters. All query parameters are multi-valued which means multiple occurrences of the parameter=value pairs as specified in the :doc:`DALI <../DALI/DALI>` recommendation are permitted. The constraints from multiple occurrences of a parameter are combined with a logical OR operator. The constraints from different parameters are combined with a logical AND operator. Query parameters for numeric fields accept a single floating point value or a range of values with optional lower and upper bounds. Such range values are encoded using the :doc:`VOTable <../VOTable/VOTable>` array serialisation (space separated). If the lower or upper bound is not specified, the range is open-ended. In :doc:`VOTable <../VOTable/VOTable>` arrays this uses the special values -Inf or +Inf. For example, the interval [300,600] is: :: 300 600 The open-ended interval [300,infinity) (all values greater than or equal to 300) is: :: 300 +Inf The open-ended interval (-infinity,600] (all values less than or equal to 600) is: :: -Inf 600 The open-ended interval (-infinity,infinity) (all values) is: :: -Inf +Inf If specified, the boundary value is always included in the interval. The units for numeric values are specified for each parameter and never included in the value. Except where explicitly noted (see :ref:`SIA:sec:ID`), query parameters for text or string fields are always case-sensitive and indicate an exact match. The sections describing query parameters make use of fixed reference systems and units to simplify client and service implementation. These choices are not suitable for all domains; the values are chosen to enable the query resource to be used to search for most standard observational astronomy data. If they are not suitable for a specific domain of interest (e.g. planetary science) then it is feasible to write a very short standard that re-uses the SIA query capability but redefines the hard-coded systems and units. This new standard would have a new standardID to distinguish services that implement it from those that implement the capability defined here. .. _`SIA:sec:POS`: 2.1.1 POS ~~~~~~~~~ The POS parameter defines the positional region(s) to be searched for data. The value is made up of a shape keyword followed by coordinate values. A POS constraint is satisfied if the specified shape intersects the bounds (s_region in the :doc:`ObsCore <../ObsCore/ObsCore>` data model) of the observation. The allowed shapes are: .. raw:: latex \begin{tabular}{ll} \sptablerule \textbf{Shape}&\textbf{Coordinate values}\cr \sptablerule \texttt{CIRCLE}&\texttt{ }\cr \texttt{RANGE}&\texttt{ }\cr \texttt{POLYGON}&\texttt{ ... (at least 3 pairs)}\cr \sptablerule \end{tabular} A circle at (12,34) with radius 0.5: :: POS=CIRCLE 12.0 34.0 0.5 A range of [12,14] in longitude and [34,36] in latitude: :: POS=RANGE 12.0 12.5 34.0 36.0 A polygon from (12,34) to (14,35) to (14,36) to (12,35) and (implicitly) back to (12,34): :: POS=POLYGON 12.0 34.0 14.0 35.0 14. 36.0 12.0 35.0 | The inside is always assumed to be the smaller of the region to the left and the region to the right so only polygons smaller than half the sphere can be specified. | A band around the equator: :: POS=RANGE 0 360.0 -2.0 2.0 The north pole: :: POS=RANGE 0 360.0 89.0 +Inf Although it is not really useful, the whole sky can be expressed: :: POS=RANGE -Inf +Inf -Inf +Inf This syntax for circles and polygons is in the same style as STC-S, but with no reference positions, coordinate systems, units, or geometric operators (union, intersection, not). Coordinate values are floating point right ascension (RA) and declination (DEC) in ICRS and the units are always degrees. Valid coordinate values are in [0,360] for longitude and [-90,90] for latitude (or NaN). .. _`SIA:sec:BAND`: 2.1.2 BAND ~~~~~~~~~~ | The BAND parameter defines the energy interval(s) to be searched for data. The value is an open or closed energy interval. The interval always includes the bounding values. A BAND constraint is satisfied if the interval intersects the energy coverage of the observation ([em_min,em_max] in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with spectral coverage that overlaps 500 to 550nm: :: BAND=500e-9 550e-9 Find data with wavelength longer than 300m: :: BAND=300 +Inf Find data with wavelength shorter than 21cm: :: BAND=-Inf 0.21 Find data that includes 21cm: :: BAND=0.21 The scalar value 550, equivalent to [550,550]: :: BAND=550 Searching using a scalar value should match any data that includes the specified value; searching using an interval will find any data with energy coverage that intersects the specified interval. Energy values used in the BAND parameter are always assumed to be observed wavelength in meters. The :doc:`ObsCore <../ObsCore/ObsCore>` data model does not define a specific reference frame for values of em_min and em_max; values in the BAND parameter are assumed to be in the same (unspecified) frame as the content (e.g. no specific frame or transformation should be assumed). .. _`SIA:sec:TIME`: 2.1.3 TIME ~~~~~~~~~~ The TIME parameter defines the time interval(s) to be searched for data. The value is an open or closed interval with numeric values (interpreted as Modified Julian Dates). A TIME constraint is satisfied if the interval intersects the time coverage of the observation ([t_min,t_max] in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). A range of MJD values: :: TIME=55123.456 55123.466 An instant in time: :: TIME=55678.123456 Values used in the TIME parameter are always interpreted as specified in :doc:`DALI <../DALI/DALI>` in the section on literal values: UTC time scale and UNKNOWN reference position :cite:p:`std:STC`. Modified Julian Date values are always in days. .. _`SIA:sec:POL`: 2.1.4 POL ~~~~~~~~~ | The POL parameter defines the polarization state(s) to be searched for matching data. | Find data with unpolarized intensity: :: POL=I Find data with standard circular polarization: :: POL=V Find right or left circular polarized data: :: POL=RR POL=LL Find data with any of IQU components: :: POL=I POL=Q POL=U The POL parameter constrains values of the pol_states column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model; possible values for the POL parameter are also defined by :doc:`ObsCore <../ObsCore/ObsCore>`. .. _`SIA:fov`: 2.1.5 FOV ~~~~~~~~~ | The FOV parameter defines the range(s) of field of view (size) to be searched for data. This constraint is satisfied if the specified range includes the size of the field of view (s_fov column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with field of view between 1 and 2 degrees: :: FOV=1.0 2.0 Find data with field of view larger than 1.0 degrees: :: FOV=1.0 +Inf Find data with field of view smaller than  1 arcmin: :: FOV=-Inf 0.017 Find data with very small (< 0.01 deg) or very large (> 2 deg) field of view: :: FOV=-Inf 0.01 FOV=2.0 +Inf Values used in the FOV parameter are always interpreted as angles expressed in degrees (same units as the s_fov column in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). .. _`SIA:spatres`: 2.1.6 SPATRES ~~~~~~~~~~~~~ | The SPATRES parameter define the range(s) of spatial resolution to be searched for data. This constraint is satisfied if the specified range includes the spatial resolution of the data (s_resolution column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with resolution better than 0.2 arcsec: :: SPATRES=-Inf 0.2 Find data with resolution larger than 1.0 arcsec: :: SPATRES=1.0 +Inf Find data with resolution between 0.1 and 0.2 arcsec: :: SPATRES=0.1 0.2 Values used in the SPATRES parameter are always interpreted as angles expressed in arcsec (same units as the s_resolution column in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). .. _`SIA:specrp`: 2.1.7 SPECRP ~~~~~~~~~~~~ | The SPECRP parameter define the range(s) of spectral resolving power to be searched for data. This constraint is satisfied if the specified range includes the resolving power of the data (em_res_power column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with resolution better than 1000: :: SPECRP=1000 +Inf Find data with resolution less than 500: :: SPECRP=-Inf 500 Find data with resolution between 10000 and 20000: :: SPECRP=10000 20000 Values used in the SPECRP parameter are dimensionless (:math:`\lambda`/:math:`\Delta`\ :math:`\lambda`, as for the em_res_power column in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). .. _`SIA:exptime`: 2.1.8 EXPTIME ~~~~~~~~~~~~~ | The EXPTIME parameter defines the range(s) of exposure times to be searched for data. This constraint is satisfied if the specified range includes the exposure time of the data (t_exptime column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with exposure time less than 60 seconds: :: EXPTIME=-Inf 60 Find data with exposure time longer than 10 minutes: :: EXPTIME=600 +Inf Find data with exposure time between 10 and 30 minutes: :: EXPTIME=600 1800 Find data with very short (< 2 sec) or very long (> 20 min) exposure time: :: EXPTIME=-Inf 2 EXPTIME=1200 +Inf Values used in the EXPTIME parameter are always expressed in seconds (same units as the t_exptime column in :doc:`ObsCore <../ObsCore/ObsCore>`). .. _`SIA:timeres`: 2.1.9 TIMERES ~~~~~~~~~~~~~ | The TIMERES parameter define the range(s) of temporal resolution to be searched for data. This constraint is satisfied if the specified range includes the temporal resolution of the data (t_resolution column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model). | Find data with resolution better than 1.0 sec: :: TIMERES=-Inf 1.0 Find data with resolution larger than 1.0 sec: :: TIMERES=1.0 +Inf Find data with resolution between 1.0 and 2.0 sec: :: TIMERES=1.0 2.0 Values used in the TIMERES parameter are always expressed in seconds (same units as the t_resolution column in the :doc:`ObsCore <../ObsCore/ObsCore>` data model). .. _`SIA:sec:ID`: 2.1.10 ID ~~~~~~~~~ The ID parameter is a string-valued parameter that specifies the identifier of dataset(s). Values of the ID parameter are compared to the obs_publisher_did column of the :doc:`ObsCore <../ObsCore/ObsCore>` data model. Note that IVOIDs MUST be compared case-insensitively. As publisher dataset identifiers in the VO generally are IVOIDs, implementations will usually have to use case-insensitive comparisons here. .. _`SIA:collection`: 2.1.11 COLLECTION ~~~~~~~~~~~~~~~~~ The COLLECTION parameter is a string-valued parameter that specifies the name of the data collection. The value is compared with the obs_collection from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. .. _`SIA:facility`: 2.1.12 FACILITY ~~~~~~~~~~~~~~~ The FACILITY parameter is a string-valued parameter that specifies the name of the facility (usually telescope) where the data was acquired. The value is compared with the facility_name from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. .. _`SIA:instrument`: 2.1.13 INSTRUMENT ~~~~~~~~~~~~~~~~~ The INSTRUMENT parameter is a string-valued parameter that specifies the name of the instrument with which the data was acquired. The value is compared with the instrument_name from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. .. _`SIA:dptype`: 2.1.14 DPTYPE ~~~~~~~~~~~~~ The DPTYPE parameter is a string-valued parameter that specifies the type of data. The value is compared with the dataproduct_type from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. For the SIA {query} resource, the only values that should be returned for dataproduct_type are *image* and *cube*, so this parameter can be only really be used to select one of these. .. _`SIA:calib`: 2.1.15 CALIB ~~~~~~~~~~~~ The CALIB parameter is a integer-valued parameter that specifies the calibration level of the data. The value is compared with the calib_level from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. To find raw data: :: CALIB=0 CALIB=1 To find calibrated data: :: CALIB=2 To find calibrated data and more highly processed data products: :: CALIB=2 CALIB=3 .. _`SIA:target`: 2.1.16 TARGET ~~~~~~~~~~~~~ The TARGET parameter is a string-valued parameter that specifies the name of the target (e.g. the intention of the original science program or observation). The value is compared with the target_name from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. .. _`SIA:format`: 2.1.17 FORMAT ~~~~~~~~~~~~~ The FORMAT parameter specifies the format returned by the access link. The value is compared with the access_format column from the :doc:`ObsCore <../ObsCore/ObsCore>` data model. This column describes the format of the response from the access_url (see 3.1.3) so the values could be data file types (e.g. application/fits) or they could be the :doc:`DataLink <../DataLink/DataLink>` MIME type (:cite:`2023ivoa.spec.1215B`, \cite{std:TSV}). .. _`SIA:releasedate`: 2.2 RELEASEDATE --------------- The RELEASEDATE parameter specifies the range of release dates to be searched for data. The limits are compared to the obs_release_date optional attribute of the :doc:`ObsCore <../ObsCore/ObsCore>` data model. They are expressed as 2 ISO 8601 dates in the general case. A single value is searched for an exact match. As the obs_release_date attribute is optional, the service self description (:ref:`SIA:sec:selfdesc`) informs the user of the availability of this parameter. RELEASEDATE queries for services not providing the release_date attribute SHOULD provide an empty response. .. _`SIA:maxrec`: 2.2.1 MAXREC ~~~~~~~~~~~~ The MAXREC parameter is defined in :doc:`DALI <../DALI/DALI>` and allows the client to limit the number or records in the response. A service implementation may also impose default and maximum values for this limit. However the limit is determined, if the output is truncated due to the limit the server must indicate this using an overflow (section :ref:`SIA:sec:succesful`) indicator except in the the special case of MAXREC=0, where the service respond with metadata-only (normal output document with no records). .. _`SIA:upload`: 2.2.2 UPLOAD ~~~~~~~~~~~~ The :doc:`DALI <../DALI/DALI>` UPLOAD parameter is not used by this version of SIA. The use case of uploading lists of coordinates is covered by the multiple-valued parameters values. .. _`SIA:sec:selfdesc`: 2.2.3 Service PARAMETER self description ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any service SHOULD include a :doc:`DataLink <../DataLink/DataLink>` service descriptor in the :doc:`VOTable <../VOTable/VOTable>` output to describe itself. This descriptor would describe the supported query parameters (standard and custom), including list of values for those with a fixed list (COLLECTION, INSTRUMENT, FACILITY, DPTYPE, CALIB, and FORMAT). This is particularly important for those parameters where the fixed list is not standardized by any specification such as COLLECTION, INSTRUMENT and FACILITY. .. _`SIA:availability-vosi-availability`: 2.3 Availability: VOSI-availability ----------------------------------- A web service with SIA capabilities must have a VOSI-availability resource :cite:p:`2017ivoa.spec.0524G` as described in :doc:`DALI <../DALI/DALI>` . .. _`SIA:capabilities-vosi-capabilities`: 2.4 Capabilities: VOSI-capabilities ----------------------------------- A web service with SIA capabilities must have a VOSI-capabilities resource :cite:p:`2017ivoa.spec.0524G` as described in :doc:`DALI <../DALI/DALI>` . The standardID for the {query} capability is :: ivo://ivoa.net/std/SIA#query-2.0 All DAL services must implement the /capabilities resource. The following capabilities document shows the minimal metadata and does not require a registry extension schema: .. code:: xml http://example.com/sia2/capabilities http://example.com/sia2/availability http://example.com/sia2/query Note that the query resource does not have to be named as shown in the accessURL(s) above. Multiple capability elements for the query and the metadata resources may be included; this is typically used if they differ in protocol (http vs. https) and/or authentication requirements. .. _`SIA:sec:queryresponse`: 3 {query} response ================== .. _`SIA:sec:succesful`: 3.1 Successful Query -------------------- The response from a successful call to the {query} resource is a table consistent with ObsTAP responses as described in \cite{std:OBSCORE}. The :doc:`ObsCore <../ObsCore/ObsCore>` data model specifies all the (:doc:`VOTable <../VOTable/VOTable>`) field names, utypes, UCDs, and units to use in the response, as well as which fields must have values and which are allowed to be empty (null). The {query} response must contain the required :doc:`ObsCore <../ObsCore/ObsCore>` fields and may contain additional fields (from :doc:`ObsCore <../ObsCore/ObsCore>` or custom fields from the service provider). Examples are provided below (section :ref:`SIA:sec:Examples`). Successfully executed requests should result in a response with HTTP status code 200 (OK) and a response in the format requested by the client or in the default format for the service. The default output format is :doc:`VOTable <../VOTable/VOTable>`. Other output formats can be specified by the RESPONSEFORMAT parameter (see :cite:`2017ivoa.spec.0517D`). The service should set the following HTTP headers to the correct values where possible. .. raw:: latex \begin{tabular}{ll} \sptablerule \textbf{Content-Type}&\textbf{mime-type of the response}\cr \sptablerule \texttt{Content-Encoding}&\texttt{encoding/compression of the response (if applicable)}\cr \sptablerule \end{tabular} Since the {query} response is usually dynamically generated, the Content-Length and Last-Modified headers cannot usually be set. .. _`SIA:related-service-metadata`: 3.1.1 Related Service Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :doc:`DataLink <../DataLink/DataLink>` specification gives a recipe for including additional resources in :doc:`VOTable <../VOTable/VOTable>` that enable the client to invoke services using values from the table as parameter values. If the provider implements a :doc:`DataLink <../DataLink/DataLink>` service for the data being found via SIA, the {query} response should include a description for invoking the :doc:`DataLink <../DataLink/DataLink>` service, usually using values from the obs_publisher_did column. If the provider implements an AccessData capability for the data being found via SIA and this capability can be invoked directly using an identifier in the {query} response, the {query} response should include a description for invoking this capability, usually using values from the obs_publisher_did column. .. _`SIA:sia-query-service-descriptor`: 3.1.2 SIA query Service Descriptor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :doc:`DataLink <../DataLink/DataLink>` specification describes a mechanism for describing a service within a :doc:`VOTable <../VOTable/VOTable>` resource and recommends that services can describe themselves with a special resource with name="this". SIA {query} responses should include a descriptor describing both standard and custom query parameters (if applicable). The descriptor for a service with standard parameters (see :ref:`SIA:sec:query`) would be: .. code:: xml This :doc:`VOTable <../VOTable/VOTable>` resource should be included in the output from all queries; it is especially useful for MAXREC=0 queries since inclusion of the self descriptor would mean that all inputs and outputs would be fully described. .. _`SIA:use-of-access_url-and-access_format`: 3.1.3 Use of access_url and access_format ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the SIA service is only dealing with simple data (one file per result), the access_url column may be a link directly to that file, in which case the access_format column should specify the file format (e.g. application/fits). If the data provider implements a :doc:`DataLink <../DataLink/DataLink>` service for the data being found via the SIA query capability, they may put a URL to invoke the :doc:`DataLink <../DataLink/DataLink>` links capability (with ID parameter and value) in the access_url column; if they do this, they must also put the standard :doc:`DataLink <../DataLink/DataLink>` MIME type in the access_format column. .. _`SIA:sec:error-codes`: 3.2 Errors ---------- The error handling specified for DALI-sync resources applies to service failure. If the requested format is :doc:`VOTable <../VOTable/VOTable>`, the error document must be :doc:`VOTable <../VOTable/VOTable>` as described by :doc:`DALI <../DALI/DALI>`, except when the service is broken. If the requested format is one of the plain text (csv or tsv) formats, the error document should also be plain text using the text/plain content-type. The error message must start with one of the strings in the following table, in order of specificity: .. raw:: latex \begin{tabular}{ll} \sptablerule \textbf{Error}&\textbf{Meaning}\cr \sptablerule UsageFault&Invalid input (e.g. invalid input parameter value\cr \sptablerule TransientFault&Service is not currently able to function\cr \sptablerule FatalFault&Service cannot perform requested action\cr \sptablerule DefaultFault&General error (not covered above)\cr \end{tabular} In all cases, the service may append additional useful information to the error strings above. If there is additional text, it must be separated from the error string with a colon (:) character, for example: :: UsageFault: invalid BAND value -2 .. _`SIA:sec:Examples`: 4 Examples ========== | This section presents two examples of queries and responses corresponding to the following scenarios : | How do I query a SIAV2 service containing IRAS-IRIS images in a circle of 0.1 deg around position 2.8425 +74.4846 selecting 200 and 60 micron bands ? | Note: Spaces in parameter values must be URL-encoded as %2B or +; we leave this out of the example to make it easier to read. | :raw-latex:`\footnotesize `http://dalservices.ivoa.net/sia2/query?POS=CIRCLE 2.8425 74.4846 0.1 &BAND=0.0002&BAND=0.00006&COLLECTION=IRAS-IRIS .. code:: xml Data product type Calibration level Data collection to which dataset belongs Free syntax Observation Identifier Publisher s ID for the dataset ID URL used to access dataset Content or MIME type of dataset Dataset estimated size Target name Spatial Position RA Spatial Position Dec Spatial Field of view "diameter" Spatial support Spatial resolution FWHM Time coordinate Lower limit Time coordinate Higher limit Exposure time Time resolution Spectral coordinate Lower limit Spectral coordinate Higher limit SPECTRAL Resolving power UCD specifying the quantity on Observable axis Enumeration of Polarization sates Facility name Instrument name
cube 1 IRAS-IRIS I422B2H0 ivo://cds.u-strasbg.fr/IRAS-IRIS/25MU/I422B2H0 image/fits 1600 I422B2H0 0.000000 80.000000 0.5 POLYGON 30.0 200.0 32.0 200.0 32.0 198.0 30.0 198.0 1000 1.0 0.21 0.21 5.0 Stokes IRAS-IRIS
cube 1 IRAS-IRIS I408B1H0 ivo://cds.u-strasbg.fr/IRAS-IRIS/12MU/I408B1H0 image/fits 1600 I408B1H0 0.000000 70.000000 0.5 POLYGON ICRS 30.0 200.0 32.0 200.0 32.0 198.0 30.0 198.0 1000 1.0 0.21 0.21 5.0 Stokes IRAS-IRIS
cube 1 IRAS-IRIS I422B1H0 ivo://cds.u-strasbg.fr/IRAS-IRIS/12MU/I422B1H0 image/fits 1600 I422B1H0 0.000000 80.000000 0.5 POLYGON ICRS 30.0 200.0 32.0 200.0 32.0 198.0 30.0 198.0 1000 1.0 0.21 0.21 5.0 Stokes IRAS-IRIS
| How do I query a service containing radio cubes from Alma operated by NRAO in a circle of 0.1 deg around position 180.47 -18.70 in the CO band in the range 800 microns to 900 microns and made in the time range between Mjd=55708 and 55710 ? | Note: Spaces in parameter values must be URL-encoded as %2B or +; we leave this out of the example to make it easier to read. | :raw-latex:`\footnotesize `http://dalservices.ivoa.net/sia_b?REQUEST=query&POS=CIRCLE 180.475 -18.70 0.01 &BAND= 0.0008 0.0009&TIME= 55708 55710&COLLECTION=ALMA .. code:: xml DALServer SIAP Version 2.0 (vao-fall2013) Data product type Calibration level Data collection to which dataset belongs Free syntax Observation Identifier Publisher s ID for the dataset ID URL used to access dataset Content or MIME type of dataset Dataset estimated size Target name Spatial Position RA Spatial Position Dec Spatial Field of view "diameter" Spatial support Spatial resolution FWHM Time coordinate Lower limit Time coordinate Higher limit Exposure time Time resolution Spectral coordinate Lower limit Spectral coordinate Higher limit SPECTRAL Resolving power UCD specifying the quantity on Observable axis Enumeration of Polarization sates Facility name Instrument name
image 1 ALMA_test ALMA test data: Antennae_South CO3_Line Full_velocity_map ivo://nrao/vo#siav2model:373 image/fits 2250000 180.475103 -18.8855694 0.027 POLYGON 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000871035586716119 0.000873082347755277 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South CO3_2Line Velocity_map_cutout ivo://nrao/vo#siav2model:373 image/fits 292456 180.474988373509 -18.8799902066141 0.0097 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000874109339630009 0.000870797535056077 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South CO3_2Line Full_integrated_intensity ivo://nrao/vo#siav2model:374 image/fits 2250000 180.475103 -18.8855694 0.027 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000874109339630009 0.000871035586716119 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South CO3_2Line Full_data_cube ivo://nrao/vo#siav2model:379 image/fits 157500000 180.475103 -18.8855694 0.027 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000874109339630009 0.000871035586716119 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South CO3_2Line Cube_cutout ivo://nrao/vo#siav2model:379 image/fits 20471920 180.474988373509 -18.8799902066141 0.0097 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000874109339630009 0.000872463699874965 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South CO3_2Line full_dispersion_map ivo://nrao/vo#siav2model:381 image/fits 2250000 180.475103 -18.8855694 0.027 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000871035586716119 0.000874109339630009 29753.745800131965 phot.flux I ALMA
image 1 ALMA_test ALMA test data: Antennae_South.CO3_2Line.Clean.pcal1.image.mom.weighted_dispersion_coord.fits ivo://nrao/vo#siav2model:381 image/fits 292456 180.474988373509 -18.8799902066141 0.0097 POLYGON ICRS 180.4607706 -18.8991286 180.4607706 -18.8720092 180.4894354 -18.8720092 180.4894354 -18.8991286 3.6e-5 55709.129226 55709.129226 0.000870797535056077 0.000874109339630009 29753.745800131965 phot.flux I ALMA
Appendices ========== .. _`SIA:changes`: A Changes ========= .. _`SIA:rec-sia-2.0-20151223`: A.1 REC-SIA-2.0-20151223 ------------------------ Fix typos. .. _`SIA:pr-sia-2.0-20151029`: A.2 PR-SIA-2.0-20151029 ----------------------- | Changed open-ended interval bounds from NaN to -Inf or +Inf for consistency with :doc:`VOTable <../VOTable/VOTable>` double values. | Formatting fixes and regenerated table of contents. .. _`SIA:pr-sia-2.0-20150730`: A.3 PR-SIA-2.0-20150730 ----------------------- Editorial and organisational changes from TCG review. .. _`SIA:pr-sia-2.0-20150610`: A.4 PR-SIA-2.0-20150610 ----------------------- | Changed the serialisation of numeric ranges in parameter values to use standard :doc:`VOTable <../VOTable/VOTable>` array format (space s eparated) so that parameters can be correctly described as accepting an array of numeric values rather than a string. Removed support for ISO8601 (timestamp) format from TIME parameter. | Added subsection for MAXREC parameter. Changed use of UNKNOWN (concept from STC) coordinate system to a plain text description. Clarified that numeric arguments to POS are floating point values (in examples and text). | Moved section comparing SIA-1.0 and SIA-2.0 earlier in the introduction. | Added example output for queries. | Add restriction that query resources must be a sibling of VOSI-capabilities. | Many minor clarifications and tweaks as recommended by TCG review. .. _`SIA:pr-sia-2.0-20141020`: A.5 PR-SIA-2.0-20141020 ----------------------- | Added section to the introduction describing the conceptual difference between SIA1.0 and SIA-2.0 and related specifications. | Clarified that all text or string query parameters are case-sensitive in this initial version. Added valid ranges of coordinate values for POS parameter. | Added IVOA architecture document and replaced get-gory-details with “SIA metadata” in the DAL architecture diagram. | Fixed the status text to be the right text for PR. | \_ Fixed numerous small typos and removed some cruft related to REQUEST. | Added some missing references. .. _`SIA:pr-sia-2.0-20140707`: A.6 PR-SIA-2.0-20140707 ----------------------- Promoted from WD to PR. .. _`SIA:wd-sia-2.0-20140707`: A.7 WD-SIA-2.0-20140707 ----------------------- | Added query parameters for remaining useful :doc:`ObsCore <../ObsCore/ObsCore>` fields and clarified that all query parameters are required and how null values for :doc:`ObsCore <../ObsCore/ObsCore>` fields are treated in queries. | Removed REQUEST parameter, as per discussions at the interop. | Removed standard error message labels for authentication and authorization failures since these are difficult to implement consistently in different web service platforms. | Changed the error message strings to use the word Fault (following :doc:`DataLink <../DataLink/DataLink>` and GWS-WG style) since Error has specific meaning in some platforms. .. _`SIA:wd-sia-2.0-20140505`: A.8 WD-SIA-2.0-20140505 ----------------------- | FORMAT and UPLOAD parameters are still TBD. | Added FOV, SPATRES, and EXPTIME parameters to query :doc:`ObsCore <../ObsCore/ObsCore>` fields s_fov, s_resolution, and t_exptime respectively. | Removed the BOX from POS shape list. | Fixed BAND parameter to specify that values are vacuum wavelength in meters with UNKNOWN reference position. | Clarified TIME parameter to specify values are UTC time scale with UNKNOWN reference position (as in :doc:`DALI <../DALI/DALI>`). | Marked text related to the metadata capability as placeholder(s) that are only informational in the SIA-2.0 specification. | Removed the section on DALI-examples because it didn’t add anything. | Added missing query constraints to the use cases in 1.2.1 (from CSP summary). | Clarified relationship between query parameters are fields/columns in the :doc:`ObsCore <../ObsCore/ObsCore>` data model. | Added standard error message strings. .. _`SIA:wd-sia-2.0`: A.9 WD-SIA-2.0 -------------- This is a major rewrite of previous drafts after several meetings, prototypes, and architectural changes. A real change log will begin with the next draft. .. |image| image:: archdiag.png :width: 90.0% .. |image1| image:: schema.png :width: 90.0%