SLAP2.tex

\documentclass[11pt,a4paper]{ivoa}
\input tthdefs

\setlength {\marginparwidth }{4cm}
\usepackage{todonotes}
\usepackage{supertabular}
\usepackage{float}
\usepackage{tabularx}
\usepackage{enumitem}
\usepackage{url}



\lstset{flexiblecolumns=true,showstringspaces=False,
  language={},breaklines=true,breakatwhitespace=true}

\newcommand{\parexample}[1]{\noindent\quad\texttt{#1}}

\title{Simple Line Access Protocol}

\ivoagroup{Data Access Layer}

\author{Moreau, N.}
\author{Salgado, J.}
\author{Osuna, P.}
\author{Demleitner, M.}
\author{Guainazzi, M.}
\author{Dubernet, M.-L.}
\author{Tody, D.}
\author{Zwölf, C.M.}
\author{Lepetit, F.}


\editor{Moreau, N.}

\previousversion[https://ivoa.net/documents/SLAP/20101209/]{REC-1.0}

\def\ivoaDocauthors{Nicolas Moreau} 

\begin{document}
\begin{abstract}
The Simple Line Access Protocol (SLAP) is an IVOA
\textit{{Data Access protocol}} which defines a protocol for retrieving
spectral lines coming from various \textit{{Spectral Line Data
Collections}}  through a uniform interface within the VO framework.
These lines can be either observed or theoretical and will be typically
used to identify emission or absorption features in astronomical
spectra.

It makes use of the \href{https://dictionary.vamdc.eu/}{VAMDC dictionary} to define the query parameters and the returned data. This dictionary is actually the equivalent of a 
relational database view built on top of the data model defined in the \textit{VAMDC XSAMS schema 12.07}
\citep{std:XSAMS12.07}. The primary objective of this schema is to set up a framework for the correct exchange of atomic, molecular and particle-surface interaction processes data. It has been developed and is currently maintained by the \href{https://vamdc.org/structure/presentation/}{VAMDC Consortium}. Each quantity defined in the dictionary is clearly defined and related to a field in the VAMDC schema.

Physical units are described by using the standard VO Units syntax \citep{2014ivoa.spec.0523D}.

SLAP services can be registered in an IVOA \textit{Registry of Resources}
where they have a unique \textit{ResourceIdentifier}
\citep{2016ivoa.spec.0523D}.
They will be described using the Simple Line Access extension
\citep{2017ivoa.spec.0530P} of VOResource to specify their
compliance level with the SLAP standard and the accepted query
parameters.

The SLAP interface is meant to be reasonably simple to implement by
service providers. A basic query will be done in a wavelength range for
the different services, using the \{lines\} resource. The service
returns a list of spectral lines formatted as a VOTable.  An
implementation of the service may support additional search parameters
(some of which may be custom to that particular service) to control more finely the selection of spectral lines.
\end{abstract}

\section*{Acknowledgments}

The authors acknowledge the comments from the DAL WG members, from the
IVOA members in general and from the VAMDC Consortium members.

\section*{Conformance-related definitions}

% CHANGE FROM .DOC: this replaces the "Requirements for complicance"
% section that had some additional (but probably unused) language

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{http://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.

\section{Introduction}

This Simple Line Access Protocol (SLAP henceforth) in its first version \citep{2010ivoa.specQ1209O} made
use of the work done in the Simple Spectral Lines Data Model definition \citep{2010ivoa.spec.1209O}, as the source of the abstract representation of
a spectral line. This second version now relies on the standardization work made by 
the VAMDC Consortium in the XSAMS data model to describe quantities \citep{std:XSAMS12.07}.

Web services in the Virtual Observatory infrastructure share a common
interface, described in the Data Access Layer Interface 1.1
\citep{2017ivoa.spec.0517D}, a document describing behaviors that must be
implemented by all services concerning for example :

\begin{itemize}
\item the use of VOTable for encoding search results,
\item the mechanism for handling errors, and
\item the retrieval of service metadata.
\end{itemize}

Following these specifications, the SLAP interface is in many ways
similar to that of SSAP \citep{2012ivoa.spec.0210T} and SIAP (v2.0)
\citep{2015ivoa.spec.1223D}.  However, SIAP and SSAP protocols are
two-step processes. In the first step, the VO client application
requests metadata from the server. These metadata include links to
images or spectra. In the second step, the VO client application
requests the data from the server. In the particular case of Simple Line
Access Services, a service will be, in essence, a one-step process,
i.e., only one request is needed whose result includes both data and metadata and from that point
of view it looks more like the Simple Cone Search protocol
\citep{2008ivoa.specQ0222P}.

Even if no link to astronomical products is expected because of the
nature of the service, the metadata associated to each line could contain reference 
links to html pages, spectra files, spectral line profiles, etc. This is particularly useful for data citation
because when the output table contains a DOI it can be cited along the data to ensure proper credit to data provider.


\subsection{Role within the VO Architecture}

\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{role_diagram.pdf}
  \caption{Architecture diagram for this document}
  \label{fig:archdiag}
\end{figure}

Fig.~\ref{fig:archdiag} shows the role this document plays within the
IVOA architecture \citep{ivoaArchitecture}.

\subsection{Link with VAMDC standards}


The VAMDC Consortium is a consortium of Institutes and Research Institutions that share a common technical and political framework
 for the distribution and curation of atomic and molecular data. It developed a set of standards to enable the exchange
 of data within its infrastructure.

Among them, the \textit{VAMDC XSAMS schema 12.07} \citep{std:XSAMS12.07} provides a structured presentation of 
Atomic, Molecular, Particle and Surface Interaction data in an XML file. It is based on the physical representation of interaction
between various objects through description of the physical states and interaction characteristics. 

This data model has been used to build the \href{https://dictionary.vamdc.eu/}{VAMDC dictionary}. This is a list of keywords, with their definition, 
that can be used when writing queries in the VAMDC variant of the TAP protocol called 
VSS2 \href{https://standards.vamdc.eu/queryLanguage/vss2.html#introduction}.
This list of keywords can be considered as a view on the VAMDC data model and avoid the need to use the FROM clause in queries.

There are different types of keywords in the dictionary that will be used in this document :
\begin{enumerate}
\item Restrictables : the criteria that can be used to filter out data in VAMDC queries
\item Returnables : the data fields that will be contained in the output
\end{enumerate}

In the SLAP2 protocol, the query parameters are mapped to VAMDC restrictables and the output fields to VAMDC returnables.

\section{Spectral line service type}
\label{sect:service-type}

It is assumed that compliant spectral line services fall into one of two categories.

\begin{enumerate}
\item Observational line databases. Lines observed and identified in
real spectra collected by different instrument/projects.
\item Theoretical line databases. Servers containing theoretical
spectral lines will be included in this group.
\end{enumerate}

In both cases, the line description and the identification might be
already present in a scientific publication, which should always be
provided when available to guarantee the provenance of data.

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.

However, the theoretical line database services could make use of extra
parameters not cited in this document to filter out lines not expected
to be identified in an observed spectrum or to score the output lines
due to the application of physical models.

Examples:

\begin{itemize}
\item For the Stark-b database \citep{2012JPhCS.397a2019S} which provides widths and shifts of isolated lines of neutral and ionized elements due to electron and ion impacts, it is necessary to provide the perturber density and the temperature to filter the transitions.

\item For the NIST Atomic Spectra Database Lines \citep{NIST_ASD}
as it is extracted from the Saha-LTE model, ``\textit{The level
populations are calculated according to the Boltzmann distribution
within each ion and Saha distribution between the ion stages. Thus, to
calculate the spectrum from a single ion, e.g., C I, only
}\textbf{T}\textbf{\textsubscript{e}}\textit{ is required, while for the
spectrum from several ions of the same element (e.g., C I-V),
}\textbf{N}\textbf{\textsubscript{e}}\textit{ must be defined as
well.}''
\end{itemize}

At the same time, for observational spectral line databases, some
project specific search parameters may be used.

Example:

In ISO Astronomical Spectroscopy Database (IASD),
the observation number parameter can be used to select only the lines
observed during this ISO satellite observation.

Since it is not the role of a standard to compile service specific parameters, 
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 a VOSI-capabilities
endpoint \citep{2017ivoa.spec.0524G}.

\section{Use cases}
\label{sect:use-cases}

The SLAP protocol aims at covering some classic use cases, some of which
will be described below.

\subsection{Discovering the content of a database}
\label{sect:content-discovery}

In the context of a graphical user interface (be it a web interface or a
local standalone application) able to query SLAP services, an
application might need to provide the list of species available in a
service, in which the user could choose what he requires. To achieve
this, the application can send a query to the \{species\} endpoint of a
service and build a graphical list object from the content of the
returned VOTable.

By caching locally this list, one might also be able to implement an
auto-completion feature if the user wants to manually enter the name of
a species.

\subsection[Identifying a Single Line in a spectrum]{Identifying a Single Line in a spectrum}
\label{sect:line-id}

A user sees a feature in a spectrum with known (and reliable) spectral
calibration and now wants to know what might possibly be responsible for
it. Hence, they query a narrow spectral range and retrieve all known lines
from all services.

To select which of the candidate lines are plausible matches, users would
inspect line metadata such as the originating atom or molecule, the ionisation
state, oscillator strengths or quantum numbers to identify rotational or vibrational level.

\subsection{Restricting the lines search}
\label{sect:restricting-search}

\subsubsection{Finding available lines for a given species}
\label{sect:finding-all}

Using a mass spectrometer, researchers find a molecule with the sum formula C16H10 in a comet. They now want to figure out whether any line in the spectrum of the coma of the parent object corresponds to some molecule with that sum formula. Conversely, a researcher may want to find lines of Methane or perhaps even Methane with one hydrogen atom being replaced by a deuteron. 

In that case,  a first step could be to search in the list of available species if the \{species\} endpoint is available,
then using the \{lines\} endpoint with SPECIES or INCHIKEY parameters.

\subsubsection{Finding Well-Known Lines}
\label{sect:finding-known-line}

A user wants to display the Lyman series over a plot of a spectrum. Hence, a client needs to discover which service holds such data, select the appropriate records - presumably by their properties, perhaps even by their name -, and retrieve them. If multiple services hold the desired data, it might need to reconcile differing specifications. 

This could be done by defining H as the searched SPECIES and providing a narrow WAVELENGTH interval corresponding to each lines in the serie.

\subsubsection[Retrieving Spectral Lines for Cross-Identification]{Retrieving Spectral Lines for Cross-Identification}
\label{sect:line-cross-id}

Users may have various reasons to retrieve a larger number of spectral lines:

    When analysing a given spectrum, selecting spectral lines that may fit the ones in the spectrum, for instance to establish the source's chemistry or physical state. Depending on the prior knowledge of the source, they will want to constrain the matches to specific species in specific ionisation (or even excitation) states.

    When estimating the redshift of an object, features found in the spectrum need to be matched to the rest wavelengths.

    When computing theoretical spectra, a comparison to the (observed) ground truth is desirable.

The challenge in all these cases is that displaying all lines known obviously is impossible 
due to the sheer volume of the data, and it would not help users in any way. 
Hence, the client needs to have some idea of which lines can be expected to be strong given 
the physics of the emission's source region.

In broad spectral ranges, hundreds of thousands of lines may fall within the selected interval, 
whereas users typically need to display only a few dozen to a few hundred lines. 
Careful pre-selection can therefore reduce the amount of data transferred to and 
processed by the client by several orders of magnitude.

To achieve this, the service should support queries based on relevant filtering criteria, 
such as the Einstein A coefficient, the number of atoms in the molecule 
(to exclude overly complex species), and the upper-level energy, 
allowing users to remove lines that are unlikely to be present under the physical conditions 
of interest.


\clearpage\section{Query interface}
\label{sect:query-interface}

The SLAP resources are synchronous web service resources that conform to
the DALI-sync description \citep{2017ivoa.spec.0517D}. For a DALI-sync
resource, the parameters for a request may be submitted using an HTTP
GET (query string) or POST action.

\subsection{Resources}
\label{sect:dali-resources}

The table below shows the list of available resources for a
service and their mandatory status.

\begin{table}[htbp]
\centering
\caption{Description of available resources}
\begin{tabular}{p{4.806cm}p{4.894cm}p{4.951cm}}
\sptablerule
\textbf{Resource type}&
\textbf{Resource name}&
\textbf{Required}\\
\sptablerule
 DALI-sync &
 /lines &
 yes\\
 DALI-sync &
 /species &
 yes\\
 VOSI-availability &
 /availability &
 no\\
 VOSI-capabilities &
 /capabilities &
 yes\\
  DALI-examples &
 /examples &
 no\\
\sptablerule
\end{tabular}
\end{table}

In order to distinguish between resources when a service is declared in
a registry, the following standardIds will be used : 

\begin{itemize}
  \item \{lines\} : ivo://ivoa.net/std/SLAP\#lines-2.0
  \item \{species\} : ivo://ivoa.net/std/SLAP\#species-2.0
  \end{itemize}

\subsection{Input parameters}
\label{sect:input-pars}

As specified in the DALI recommendation, parameter names are not
case sensitive; a SLAP service must treat upper-, lower-, and mixed-case
parameter names as equal. Parameter values are case sensitive.
All query parameters are multi-valued which means multiple occurrences
of the parameter=value pairs as specified in the DALI recommendation are
permitted, excepting the MAXREC parameter which is single valued. 
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. In accordance with these rules, 
a query to search lines for both hydrogen and helium atoms at once can be written as follows : \\

SPECIES=H\&SPECIES=He \\
Query parameters for text or string fields are always case-sensitive and indicate an exact match. \\
Query parameters for numeric fields accept a single numeric value or a range 
of values with optional lower and upper bounds such as defined in the DALI specification \citep{2017ivoa.spec.0517D}. 

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 \\

\subsection{Pattern matching}
\label{sect:pattern-matching}

Some query parameters accept wildcards in order to provide extended search features. 
In that case, the shell wildcards will be used :

\begin{itemize}
  \item \textbf{*} matches any sequence of characters (including the empty one)
  \item \textbf{?} matches any single character
  \item \textbf{[seq]} matches the character set defined by seq. The sequence can contain either 
                       a list of characters ( e.g [abc] ) or an interval (e.g [a-c], [1-5])
\end{itemize}

All the wildcards are case-sensitive.

Examples : 
\parexample{SPECIES=CO*}  : all species starting with CO \\
\parexample{SPECIES=*OH} : all species ending with OH \\
\parexample{SPECIES=CO[2-3]} : CO2 and CO3 \\
\parexample{SPECIES=CH3?H} : CH3OH and CH3SH \\

At the moment, pattern matching is not used in any other IVOA protocol. If an IVOA standardized
way to do pattern matching were introduced in the future and it was not compatible with 
the current specification, this section would be updated in a future release of the standard.

\section{\{lines\} resource}
\label{sect:lines-res}

The purpose of this resource is to allow users/clients to search in a
wavelength range for spectral lines. This resource MUST be implemented
by a SLAP service. The most basic query parameters will be the minimum
and maximum value for the wavelength range. Additional parameters may be
used to refine the search or to model physical scenarios.

\subsection{Parameters}
\label{sect:lines-pars}

A service must support all the input parameters described in this section.
That means that the service must accept them as valid ones without
raising an error, and the parameters must be properly used to constrain
the query.

If one or several parameters can not be implemented in the context of a service, 
an error must be raised when the parameter is received in a query (see \ref{par:QUERY_STATUS} for the appropriate syntax).

\subsubsection{WAVELENGTH}

The \textbf{WAVELENGTH} parameter specifies the wavelength spectral range, 
to be specified in meters. This wavelength range will be interpreted as the wavelength in the vacuum of
the transition originating the line (ucd=\ucd{em.wl}; corresponding VAMDC restrictable is {\textquotedbl}RadTransWavelength{\textquotedbl} 
to be specified in Angstroms).

As the units in the spectral line database could be different than
meters, the service will need to translate from the selected units
(meters) to the internal ones. The selection of one type of units (in
this case the SI unit meters) will help to unify access to different
spectral line databases, even when in some cases, the unit selected
(meter) may not be the best one for the range on interest.

Example

To query for spectral lines in the wavelength range between 5.1 and 5.6
micrometers ( both values are included in search ):

\parexample{WAVELENGTH=5.1E-6 5.6E-6}

\subsubsection{SPECIES}

The \textbf{SPECIES} parameter would constrain the search to
the selected species. A list of different species
could be queried by specifying this parameter multiple times (ucd=\ucd{phys.atmol.element}).

Atom can be specified exactly by symbol (corresponding VAMDC restrictable is {\textquotedbl}AtomSymbol{\textquotedbl}) or names
like carbon or iron. 
Molecules can be specified by conventional molecular name (formula like CO2, CH4 or names like carbon dioxyde or water {\dots}) 
which might not be unique (corresponding VAMDC restrictable are {\textquotedbl}MoleculeChemicalName{\textquotedbl} and 
{\textquotedbl}MoleculeOrdinaryStructuralFormula{\textquotedbl}). 
The \{species\} endpoint is the recommended place to discover the correct syntax of a given species in a particular service, 
providing a pattern matching syntax.

Filter results for Iron only : 

\parexample{SPECIES=Fe}

Filter results for Carbon Dioxide molecule only:

\parexample{SPECIES=CO2}

\subsubsection{SPECIES\_MASS}

The \textbf{SPECIES\_MASS} parameter specifies the minimum and maximum possible mass value 
for the searched species, to be specified in Unified Atomic Mass Unit (u).  

The mass will be a float value greater than 0. The provided range will be interpreted as the 
mass of the chemical species  (ucd=\ucd{phys.atmol.element;phys.mass}; 
corresponding VAMDC restrictable are {\textquotedbl}AtomMass{\textquotedbl} for atoms and 
{\textquotedbl}MoleculeMolecularWeight{\textquotedbl} for molecules).

Filter all atoms chemical species between 0 and 12.011 u:

\parexample{SPECIES\_MASS=0 12.011}

\subsubsection{INCHIKEY}

InChI is an acronym for IUPAC International Chemical Identifier \citep{Heller2015}. 
It is a string of characters capable of uniquely representing a chemical substance. 
InChIKey is a compact chemical identifier derived from InChI. The InChIKey is always 
only 27-characters long. 

The \textbf{INCHIKEY} parameter (ucd=\ucd{phys.atmol.element}; corresponding VAMDC restrictable is {\textquotedbl}InchiKey{\textquotedbl}) 
constrains the search to the species corresponding the provided inchikey value. A list of different
inchikeys could be queried by specifying this parameter multiple times.

The \{species\} 
endpoint is the recommended place to discover the InChIkey of a given species in a particular service. You can also 
use the dedicated \href{https://species.vamdc.org/}{VAMDC Species service}. This service relies on the VAMDC Species
Database \citep{Zwölf2024} that regularly harvest the species for which data are available within the VAMDC infrastructure.

Filter results for neutral Iron atom (InChI=1S/Fe) only : 

\parexample{INCHIKEY=XEEYBQQBJWHFJM-UHFFFAOYSA-N} \\

When using this parameter, the user must pay attention to isotopes. 
The InChIKey is generated from the InChI which can contain isotope information. 
For example, the standard carbon monoxide CO, CO with $^{17}$O and CO with $^{18}$O 
each have a distinct InChIKey. A query using the InChIKey of CO will therefore 
not return lines of CO-17 or CO-18, and vice versa. \\

Some examples of InChI and InChIkey : \\ 
\parexample{CO : InChI=1S/CO/c1-2, InChIKey=UGFAIRIUMAVXCW-UHFFFAOYSA-N} \\
\parexample{CO-17       : InChI=1S/CO/c1-2/i2+1, InChIKey=UGFAIRIUMAVXCW-VQEHIDDOSA-N} \\
\parexample{CO-18       : InChI=1S/CO/c1-2/i2+2, InChIKey=UGFAIRIUMAVXCW-HQMMCQRPSA-N}


\subsubsection{ION\_CHARGE}

The \textbf{ION\_CHARGE} parameter specifies the minimum and maximum charge 
of an ion (ucd=\ucd{phys.atmol.element;phys.atmol.ionization}; 
corresponding VAMDC restrictable is {\textquotedbl}IonCharge{\textquotedbl}).
 
It will look for the ionized forms of the species specified in SPECIES
parameter. If it is not defined, the restriction will be applied to all
the ions available. If several SPECIES values have been
provided, the ion charge values will be applied to each one of them.

The charge will be an integer value greater than 0 for ionized species
(positive charge), less than 0 for negative charge (excess electrons), 0
for neutral. 

All lines related to Fe+ ion:

\parexample{SPECIES=Fe\&ION\_CHARGE=1}

All lines related to positively charged Fe ions and excluding the neutral form :

\parexample{SPECIES=Fe\&ION\_CHARGE=1 +Inf}

\subsubsection{LOWER\_LEVEL\_ENERGY}

The \textbf{LOWER\_LEVEL\_ENERGY} parameter specifies the minimum and maximum energy for the LOWER level of the transition, 
to be expressed in Joules (ucd=\ucd{phys.energy;phys.atmol.level}; corresponding VAMDC restrictable
 is {\textquotedbl}StateEnergy{\textquotedbl}).

Energy of lower level between 3.93E-18 and 3.94E-18 Joules:

\parexample{LOWER\_LEVEL\_ENERGY=3.93E-18 3.94E-18}

\subsubsection{UPPER\_LEVEL\_ENERGY}

The \textbf{UPPER\_LEVEL\_ENERGY} parameter specifies the minimum 
and maximum energy for the UPPER level of the transition, to be expressed in Joules (ucd=\ucd{phys.energy;phys.atmol.level}; 
corresponding VAMDC restrictable is {"StateEnergy"}).

Energy of upper level between 3.93E-18 and 3.94E-18 Joules:

\parexample{UPPER\_LEVEL\_ENERGY=3.93E-18 3.94E-18}


\subsubsection{EINSTEINA}

The \textbf{EINSTEINA} parameter constrains the 
transition probability by specifying the minimum and maximum Einstein A, defined as the probability 
per unit time s\textsuperscript{-1} for spontaneous emission in a bound-bound 
transition (ucd=\ucd{phys.atmol.transProb};corresponding VAMDC restrictable 
is {\textquotedbl}RadTransProbabilityA{\textquotedbl}).

Transition probability between 1.1E-7 and 1.2E-7 s-1:

\parexample{EINSTEINA=1.1E-7 1.2E-7}

\subsubsection{MAXREC}
\label{sect:lines-maxrec}

The MAXREC parameter, defined in DALI \citep{2017ivoa.spec.0517D}, allows the client to
limit the number of 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 indicator (\ref{par:QUERY_STATUS}) except in the special
case of MAXREC=0 where the service responds with metadata-only (normal
output document with no records).

This parameter is single valued and services must respond with an error if 
the request includes multiple values for it.\\

Display only 100 lines:

\parexample{MAXREC=100}

\subsubsection{RESPONSEFORMAT}
\label{sect:lines-responseformat}

The RESPONSEFORMAT parameter, defined in DALI \citep{2017ivoa.spec.0517D}, allows the client to specify the format 
of the response. SLAP2 services MUST support application/x-votable+xml and text/xml, 
both referring to VOTable output. If the parameter is omitted, the service MUST return application/x-votable+xml by default. 
The service MUST return an error if a format not supported is requested.


\subsubsection{Custom query parameters}

As we saw in Section 3, there is a need to have a general mechanism for
free query parameters to filter out or sort the table result.

Both for the non-compulsory parameters and/or for the free ones, client
applications can discover whether a particular parameter is implemented
through the VOSI-capabilities operation.

Using this information, a VO client would be able to dynamically
construct a form, where this information could be inserted.

\subsection{Response format}
\label{sect:lines-response-format}

The output returned by a SLAP service is a VOTable
\citep{2013ivoa.spec.0920O}, an XML table format, returned with a
MIME-type of {\textquotedbl}application/x-votable+xml{\textquotedbl}.
The table lists all the Spectral lines found in the server database that
match the query constraints.

It \textbf{MUST} contain a RESOURCE element identified with the tag
type={\textquotedbl}results{\textquotedbl} that \textbf{SHOULD} contain
a single TABLE element which contains the results of the query. The
VOTable is permitted to contain additional RESOURCE elements, but the
usage of any such elements is not defined here. If multiple resources
are present it is recommended that the query results be returned in the
first resource element.

The VOTable \textbf{MAY} contain references to other name spaces, like
SLAP, Characterization, etc. 

\subsubsection[RESOURCE element]{RESOURCE element}
\label{sect:resource-element}

The RESOURCE element contains several INFO elements that store metadata 
about the request execution and the queried service. 
These metadata facilitate the identification of the data provenance and enable the reproducibility 
of the query on the service. 
They are originally described in the Data Origin document \citep{ivoaDataOrigin1.1}, 
with the exception of QUERY\_STATUS, which is described in DALI 1.1 \citep{2017ivoa.spec.0517D}.

\paragraph{QUERY\_STATUS}\label{par:QUERY_STATUS}

It \textbf{MUST} contain an INFO with
name={\textquotedbl}QUERY\_STATUS{\textquotedbl}. Its value attribute
MUST be set to {\textquotedbl}OK{\textquotedbl} if the query is executed successfully,
regardless of whether any matching spectral lines were found. \ If an
overflow occurs (result exceeds MAXREC) the value attribute will be set
to {\textquotedbl}OVERFLOW{\textquotedbl}. \\

Successful query example : 
\begin{lstlisting}{language=XML}
<INFO name="QUERY_STATUS" value="OK" />
\end{lstlisting} 

Error example for a standard parameter :
\begin{lstlisting}{language=XML}
<INFO name="QUERY_STATUS" value="ERROR">Parameter TEMPERATURE is not supported</INFO>
\end{lstlisting}

\paragraph{request\_date}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}request\_date{\textquotedbl}. 

\begin{lstlisting}{language=XML}
<INFO name="request_date" value="2025-10-31T14:57:18+01:00" />
\end{lstlisting}

\paragraph{request}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}request{\textquotedbl} containing the full request 
URL including a query string. 

\begin{lstlisting}{language=XML}
<INFO name="request" value="https://myvo.org/slap2/lines?WAVELENGTH=9e-8+9.1e-8"/>
\end{lstlisting}

\paragraph{service\_ivoid}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}service\_ivoid{\textquotedbl} containing the ivoid 
of the service that executed the query. 

\begin{lstlisting}{language=XML}
<INFO name="service_ivoid" value="ivo://myvo.org/slap2"/>
\end{lstlisting}

\paragraph{service\_protocol}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}service\_protocol{\textquotedbl} containing the ivoid 
of the protocol. 

\begin{lstlisting}{language=XML}
<INFO name="service_protocol" value="ivo://ivoa.net/std/SLAP#lines-2.0"/>
\end{lstlisting}

\paragraph{publisher}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}publisher{\textquotedbl}. 

\begin{lstlisting}{language=XML}
<INFO name="publisher" value="Data center name"/>
\end{lstlisting}

\paragraph{last\_update\_date}

The RESOURCE element \textbf{SHOULD} contain an INFO with
name={\textquotedbl}last\_update\_date{\textquotedbl}.

\begin{lstlisting}{language=XML}
<INFO name="last_update_date" value="2025-09-20T12:00:00+01:00"/>
\end{lstlisting}

\subsubsection{The TABLE element}

Each table row represents a different spectral line. 
Suggested UCDs are given for every columns but services are allowed to use other UCDs if more appropriate.

\subsection{Standard output fields}

\paragraph{Canonical and Original Units}

The current specification requires a specific unit for each column containing
numerical values (for example, the wavelength in vacuum must be given in meters). 
However, the original unit in which the value was provided in the source database may be
different. For example, this standard provides wavelength in meters whereas the original
database may provide transitions in $cm^{-1}$, GHz or {\AA}.


To allow the user to know the original unit and the original value
before conversion, the service MAY provide an additional column where data
will be provided in the original unit.

The column name is formed by appending the \_original suffix to the
canonical column name. The ucd suggested for the canonical column is left
unchanged.

Examples :

\begin{itemize}
  \item \textbf{Canonical column} :
    \begin{lstlisting}[basicstyle=\small\ttfamily]
<FIELD datatype="double" unit="m" name="vacuum_wavelength" ucd="em.wl" />
    \end{lstlisting}
  \item \textbf{Column in original unit} :
    \begin{lstlisting}[basicstyle=\small\ttfamily]
<FIELD datatype="double" unit="nm" name="vacuum_wavelength_original" ucd="em.wl" />
    \end{lstlisting}
\end{itemize}

\subsubsection{vacuum\_wavelength}

Exactly one field \textbf{MUST} have name={"vacuum\_wavelength"},
with datatype={"double"}, unit={"m"} and
ucd=\ucd{"em.wl"}, containing the wavelength in
vacuum of the transition originating the line in meters. 
The corresponding VAMDC returnable is  {"\textbf{RadTransWavelength"}}.
This value must not be NULL.

One field MAY have name="vacuum\_wavelength\_original" with the same attributes
as the canonical column, except for the unit, to provide the wavelength 
in its original publication unit.

\subsubsection{vacuum\_wavelength\_error}

Exactly one field \textbf{MUST} have name={"vacuum\_wavelength\_error"},
with datatype={"double"}, unit={"m"} and
ucd=\ucd{"stat.error;em.wl"}, containing the total error for the wavelength in
vacuum of the transition originating the line in meters. 

The corresponding VAMDC returnable is  {"\textbf{RadTransWavelengthAccuracy"}}.
This value may be NULL if the value is unknown.

One field MAY have name="vacuum\_wavelength\_error\_original" with the same attributes
as the canonical column, except for the unit, to provide the wavelength error
in its original publication unit.


\subsubsection{observed\_wavelength}

At most one field \textbf{MAY} have name={"observed\_wavelength"}, with
datatype={"double"}, unit={"m"} and ucd=\ucd{"em.wl"}, containing the observed wavelength in the vacuum of 
the transition originating the line in meters, as it was observed. 
This may be used by observational spectral line databases. 
The corresponding VAMDC returnable is  {"\textbf{RadTransWavelength}"}.


\subsubsection{line\_title}

Exactly one field \textbf{MUST} have name={"line\_title"}, with
datatype={"char"}, arraysize={"*"} and ucd=\ucd{"meta.title"}, containing a small description identifying the line.
The corresponding VAMDC returnable is {"\textbf{RadTransComment}"}.

Note that this line title is only a short string representation to be
used in the clients for display. There is no required syntax, but it is
recommended that common species and transition notation be used when
applicable. This value must not be NULL.

Examples:
\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
  \item \verb|H I|
  \item \verb|N III 992.873 A|
  \item \verb|H2 0-0 S(1)|
  \item \verb|H2 v=1, J=2 -> v=0, J=0|
  \item \verb|H Lyman alpha|
  \item \verb|H I, 2p 2P0 1/2 -> 1s 2S 1/2|
  \item \verb|N III 23.79941 nm|
  \item \verb|N III 2s 2p (3P0) 6p, 2P, J=3/2 -> 2s2 2p, 2P0, J=1/2|
  \item \verb|OH 2509.9 GHz|
  \item \verb|OH X2Pi, v=0, J=5/2, +, F2 -> X2Pi, v=0, J=3/2, F2, -|
  \item \verb|CO 115.27 GHz|
  \item \verb|CO v=0, J=1 -> v=0, J=0|
  \item \verb|H2 1-0 S(0)|
  \item \verb|H2 v=1, J=2 -> v=0, J=0|
  \item \verb|H2 1Sigma_g+ v=1, J=2 -> 1Sigma_g+ v=0, J=0|
\end{itemize}

In case of corrected but unidentified lines, some examples could be:

Examples: \verb|M31 1001.784 A|, \verb|011910191 800.2 A|

\subsubsection{species\_name}

Exactly one field \textbf{MUST} have 
name={"species\_name"}, with  datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}.
In the case of an atom, the corresponding VAMDC returnable is {"\textbf{AtomSymbol}"}.
If this is a molecular line, the corresponding VAMDC returnable is  {"\textbf{MoleculeChemicalName}"}.\\
Example of valid values are : Fe for a iron line or CH4 for a methane line.
This value must not be NULL.

\subsubsection{species\_mass}

At most one field \textbf{MAY} have name={"species\_mass"}, with  datatype={"float"} and ucd=\ucd{"phys.mass"}. 
The field contains the atom mass or the molecular weight of the species, to be specified in Unified Atomic Mass Unit (u). 
For an atom, the corresponding VAMDC returnable is {"\textbf{AtomMass}"}. 
If this is a molecular line, the corresponding VAMDC returnable is {"\textbf{MoleculeMolecularWeight}"}.

\subsubsection{inchikey}

Exactly one field \textbf{MUST} have name={"inchikey"}, with datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the inchikey \citep{Heller2015} of
the species of this line. For an atom, the corresponding VAMDC returnable is  {"\textbf{{AtomInchiKey}}"} 
and {"\textbf{{MoleculeInchiKey}}"} for a molecular line.
This value must not be NULL.

\subsubsection{inchi}

Exactly one field \textbf{MUST} have name={"inchi"}, with
datatype={"char"}, arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the inchi of the
species of this line. The corresponding VAMDC returnable is  {"\textbf{{AtomInchi}}"} 
for an atomic line and  {"\textbf{{MoleculeInchi}}"} for a molecular line.
This value must not be NULL.

\subsubsection{ion\_charge}

Exactly one field \textbf{MUST} have name={"ion\_charge"}, with
datatype={"int"} and ucd=\ucd{"phys.atmol.ionization"}, containing the charge of the species origin of the line. 
The corresponding VAMDC returnable is {"\textbf{AtomIonCharge}"} for an atomic line and {"\textbf{{MoleculeIonCharge}}"} for a molecular line. This value must not be NULL.

\subsubsection{lower\_level\_description}

Exactly one field \textbf{MUST} have name={"lower\_level\_description"}, with datatype={"char"}, arraysize={"*"} 
and ucd=\ucd{"meta.title;phys.atmol.level"}, containing a full description of the lower level of the transition originating the line. 
The corresponding VAMDC returnable is  {"\textbf{AtomStateDescription}"} for an atomic state and {"\textbf{MoleculeStateDescription}"} for a molecular state.
This value may be NULL.

Examples:
\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
  \item \verb|H2 v=0, J=0|
\end{itemize}

\subsubsection{upper\_level\_description}

Exactly one field \textbf{MUST} have name={"upper\_level\_description"}, with datatype={"char"}, arraysize={"*"} 
and ucd=\ucd{"meta.title;phys.atmol.level"}, containing a full description of the upper level of the transition originating the line. 
The corresponding VAMDC returnable is  {"\textbf{AtomStateDescription}"} for an atomic state and  {"\textbf{MoleculeStateDescription}"}  for a molecular state.
This value may be NULL.

\begin{itemize}[label={\small$\bullet$}, itemsep=0pt, parsep=0pt]
  \item \verb|H2 v=1, J=2|
\end{itemize}

\subsubsection{einstein\_a}
At most one field \textbf{MAY} have name={"einstein\_a"}, with
datatype={"double"}, unit={"1/s"} and ucd=\ucd{"phys.atmol.transProb"}, containing Einstein A value, 
defined as the probability per unit time s\textsuperscript{-1} for spontaneous emission in a bound-bound transition. 
The corresponding VAMDC returnable is  {"\textbf{RadTransProbabilityA}"}.

\subsubsection{lower\_level\_energy}

At most one field \textbf{MAY} have name={"lower\_level\_energy"}, with
datatype={"double"}, unit={"J"} and ucd=\ucd{"phys.energy;phys.atmol.level"} 
describing the energy for the lower level of the transition which originates this line. 
The value must appear in Joules to unify results.
The corresponding VAMDC returnable is  {"\textbf{StateEnergy}"}.

One field MAY have name="lower\_energy\_original" with the same attributes
as the canonical column, except for the unit, to provide the energy of the lower level
in its original publication unit.

\subsubsection{upper\_level\_energy}

At most one field \textbf{MAY} have name={"upper\_level\_energy"}, with
datatype={"double"}, unit={"J"} and
ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the upper level of the transition which originates this line. 
The value must appear in Joules to unify results. The corresponding VAMDC returnable is {"\textbf{StateEnergy}"}

One field MAY have name="upper\_energy\_original" with the same attributes
as the canonical column, except for the unit, to provide the energy of the upper level
in its original publication unit.

\subsubsection{reference\_doi}

One or more fields \textbf{SHOULD} have name={"reference\_doi"}, with ucd=\ucd{"meta.ref.doi"}, datatype={"char"} and
arraysize={"*"}, to specify a digital object identifier
attached to this reference. The corresponding VAMDC returnable is  {"\textbf{SourceDOI}"}.

\subsubsection{reference\_uri}

One or more fields \textbf{SHOULD} have name={"reference\_uri"},
with ucd=\ucd{"meta.ref.uri"}, datatype={"char"} and
arraysize={"*"}, to specify an http link that contains a scientific publication related to the spectral line. Since the URL will often contain metacharacters, the URL is normally enclosed in an XML CDATA section ({\textless}![CDATA[...]]{\textgreater}) or otherwise encoded to escape any embedded metacharacters. The corresponding VAMDC returnable is {"\textbf{SourceURI}"}.


\subsubsection{reference\_additional\_uri}

One or more fields \textbf{MAY} have name={"reference\_additional\_uri"} with ucd=\ucd{"meta.ref.uri"}, datatype={"char"}, arraysize={"*"} and free names, to specify URLs that contains extra information related to the spectral line. Same criteria than before about the CDATA section.
The corresponding VAMDC returnable is  {"\textbf{SourceURI}"}.

\subsection{Non-standard output fields}
\label{sect:lines-nonstd}

In many occasions, extra scientifically interesting parameters may be
added to the output. Implementers are encouraged to add descriptions and
UCDs to the return fields to clarify the meaning of this information
whenever possible.


\section{\{species\} resource}
\label{sect:species}

A simple spectral service \textbf{MUST} support a resource listing all
the species for which lines are available. This operation returns the
complete list of species available in the service. The
output returned by the service is a VOTable, an XML table format,
returned with a MIME-type of
{"application/x-votable+xml"}.

Several restriction parameters are defined to perform some 
search operations on the species list. If none of those parameter is used 
in the user query, the complete list of species will be returned.

A service must support all the input parameters described in this section. 
That means that the service must accept them as valid ones without raising an error, 
and the parameters must be properly used to constrain the query. 
If one or several parameters can not be implemented in the context of a service, 
an error must be raised when the parameter is received in a query 
(see \ref{par:QUERY_STATUS} for the appropriate syntax).

\subsection{Parameters}
\label{sect:species-optional-parameters}

\subsubsection{SPECIES\_TYPE}

The \textbf{SPECIES\_TYPE} parameter specifies the type of species expected in the response. 
The possible values are {"atom"} and {"molecule"}. 
If the parameter is not used in the query then both atoms and molecules are returned.

Returns all the molecules :

\parexample{SPECIES\_TYPE=molecule}


\subsubsection{INCHIKEY}

The \textbf{INCHIKEY} parameter tests the existence of a given 
inchikey in the service data among the data shared by the service.

Returns the molecular hydrogen : \\
\parexample{INCHIKEY=UFHFLCQGNIYNRP-UHFFFAOYSA-N} \\



\subsubsection{INCHI}

The \textbf{INCHI} parameter defines an expression accepting pattern matching 
(see \ref{sect:pattern-matching} for exact syntax) to search for species by their InChI identifier. 
This allows searching easily for isotopologues of a given species.

Examples: \\
Returns the molecular hydrogen, exact match : \\
\parexample{INCHI=1S/H2/h1H} \\
Look for CO molecule isotopologues, InChI starting with the given chain : \\
\parexample{INCHI=1S/CO/c1-2*}


\subsubsection{NUMBER\_OF\_ATOMS}

The \textbf{NUMBER\_OF\_ATOMS} parameter specifies the number of atoms in the returned species.

There is no equivalent VAMDC restrictable for this parameter.

Di-atomic molecules:

\parexample{NUMBER\_OF\_ATOMS=2}

Molecules containing 2 to five atoms :

\parexample{NUMBER\_OF\_ATOMS=2 5}

\subsubsection{SPECIES}

The \textbf{SPECIES} parameter defines an expression accepting pattern matching 
(see \ref{sect:pattern-matching} for exact syntax) to perform a search 
in the list of species provided by the service.

Returns carbon monoxide and carbon dioxide :
\parexample{SPECIES=CO*}

Returns Cobalt atom :
\parexample{SPECIES=Co}

Returns all the species whose formula ends with "OH" :
\parexample{SPECIES=*OH}

\subsubsection{STOICHIOMETRIC\_FORMULA}

For molecules it is constituted by an alphabetical suite of the atomic constituents followed
 by the total number of their occurence (purely ASCII), for example CO2, NH3, CH4.

The \textbf{STOICHIOMETRIC\_FORMULA} parameter defines an expression accepting pattern matching 
(see \ref{sect:pattern-matching} for exact syntax) to perform
a search in the list of stoichiometric formula provided by the service.

Returns methanol and its isotopologues (e.g. \textsuperscript{13}CH$_3$OH, CH$_3$O\textsuperscript{17}H) :
\parexample{STOICHIOMETRIC\_FORMULA=CH4O}

\subsubsection{MAXREC}

The MAXREC parameter, defined in DALI \citep{2017ivoa.spec.0517D}, allows the client to
limit the number of records in the response 
( see \ref{sect:lines-maxrec} for the complete parameter description ).

Display only 10 species:

\parexample{MAXREC=10}

\subsubsection{RESPONSEFORMAT}

The RESPONSEFORMAT parameter, defined in DALI \citep{2017ivoa.spec.0517D}, allows the client to specify the format 
of the response ( see \ref{sect:lines-responseformat} for the complete parameter description ).

\subsection{Response format}
\label{species-output}

The global metadata returned by a SLAP service for the \{species\}
resource are identical to the output of the \{lines\} resource (see section~\ref{sect:resource-element}).

\subsection{Standard output fields}
\label{species-fields}

\subsubsection{species\_name}

Exactly one field \textbf{MUST} have
name={"species\_name"}. The
corresponding VAMDC returnable is  {"\textbf{AtomSymbol}"} for an atom
and {"\textbf{MoleculeChemicalName}"} for a molecule.

This is the conventional molecule name, e.g. CO2, NH3, FeH, Carbon, Methane ... and it may not be unique.

In both cases, datatype={"char"},
arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the name of a
species for which at least one spectral line is available in
the service. This value must not be NULL.

\subsubsection{ion\_charge}

Exactly one field \textbf{MUST} have name={"ion\_charge"} with datatype={"int"} and ucd=\ucd{"phys.atmol.ionization"}, 
containing the charge of  the considered chemical species. The corresponding VAMDC returnable is {"\textbf{{AtomIonCharge}}"} 
for an atom and  {"\textbf{{MoleculeIonCharge}}"} for a molecule. This value must not be NULL.

\subsubsection{inchikey}

Exactly one field \textbf{MUST} have name={"inchikey"}, with
datatype={"char"}, arraysize={"*"} and ucd=\ucd{"phys.atmol.element"}, containing the inchikey 
of the chemical species.

The corresponding VAMDC returnable is  {"\textbf{{AtomInchiKey}}"} for an atom and {"\textbf{{MoleculeInchiKey}}"} for a molecule. 
This value must not be NULL.

\subsubsection{inchi}

Exactly one field \textbf{MUST} have name={"inchi"}, with datatype={"char"}, arraysize={"*"} and ucd=\ucd{"phys.atmol.element"}, 
containing the inchi of the species. The corresponding VAMDC returnable is {"\textbf{AtomInchi}"} for an atom 
and {"\textbf{MoleculeInchi}"} for a molecule. This value must not be NULL.

\subsubsection{species\_stoichiometric\_formula}

Exactly one field \textbf{MUST} have
name={"species\_stoichiometric\_formula"}, datatype={"char"},
arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the stoichiometric formula of a species for which at least one spectral line is available in the service. For an atom, the atom symbol can be used as a value.

The corresponding VAMDC returnable is {"\textbf{MoleculeStoichiometricFormula}"} in the case of a molecule. The value is not defined for an atom. This value may be NULL.

\subsubsection{species\_type}

Exactly one field \textbf{SHOULD} have
name={"species\_type"}, datatype={"char"},
arraysize={"*"}. It will describe the type of species, possible values are
{"atom"} or {"molecule"}

\subsubsection{number\_of\_atoms}
At most one field \textbf{SHOULD} have name={"number\_of\_atoms"}, with  datatype={"int"}. 
The field contains the number of atoms contained in the considered species.
There is no equivalent returnable in the VAMDC dictionary.

Example of valid values are : 1 for the hydrogen atom, 3 for the water molecule.


\section{VOSI-capabilities}

A compliant simple spectral line service \textbf{MUST} provide a
\{capabilities\} resource used to query the service metadata:

\nolinkurl{http://example.com/slap2/capabilities}

This resource will return the capability metadata as described in IVOA
Support Interfaces document. The DALI-sync resources will
be identified through the standardID attribute:

\begin{inlinetable}
\begin{tabular}{p{4.8780003cm}p{8.736cm}}
\sptablerule
\textbf{DALI-sync resource} &
\textbf{standardID}\\
\sptablerule
\{lines\} &
{ivo://ivoa.net/std/SLAP\#lines-2.0} \\
\{species\} &
{ivo://ivoa.net/std/SLAP\#species-2.0}\\

\end{tabular}
\end{inlinetable}

An example of such a document could be: 

\auxiliaryurl{vosi-capabilities.xml}

\section{Registration and discovering of SLAP resources}

Users can discover a service instance through an IVOA-compliant
registry. The description is recognized as an instance of a SLAP
service when it complies with the SLAP VOResource metadata extension
schema \citep{2017ivoa.spec.0530P}.

\appendix

\section{SLAP services for uncorrected and unidentified lines}
\label{app:unidentified}

In the specific case where services wish to make available line lists derived from observations 
(for example, a list of unidentified lines), the wavelengths of these lines must be corrected for 
any possible shifts (for example, redshift) before being made accessible via SLAP.

The reason for that is, if a user wants to compare two different SLAP
service outputs or to compare one SLAP service output to one SSAP
service output, the data comparison requires previous correction. This
correction is often quite complex and it should be done by the data
providers, the ones who have the knowledge and expertise to correct the
data properly, and not by a client application, as this process is prone
to scientific errors.

Even if a SLAP-like service cannot be registered in the IVOA as standard
SLAPs because it provides only uncorrected lines, the creation of
services for internal project consumption could be desirable.

If a service is able to provide both corrected and uncorrected lines,
the service could be registered as soon as a default call to the service
only returns the corrected lines as output. The following optional
parameter could be used to select other types of lines.

\begin{itemize}
\item {\bfseries CORRECTION\_STATUS}
A service MAY have a search parameter called CORRECTION\_STATUS.
This parameter constrains the search to lines with a certain level
of identification. The possible values are:

\begin{itemize}
\item UNCORRECTED
\item CORRECTED
\end{itemize}

And the default value MUST be ``CORRECTED''
(ucd=\ucd{meta.id.cross;em.line})

\item {\bfseries IDENTIFICATION\_STATUS}
A service \textbf{MAY} have a search parameter called
IDENTIFICATION\_STATUS. This parameter would constrain the search to
lines with a certain level of identification. The
possible values are:

\begin{itemize}
\item UNIDENTIFIED
\item IDENTIFICATION\_UNCERTAIN
\item IDENTIFICATION\_PROVISIONAL
\item IDENTIFIED
\end{itemize}

(ucd=\ucd{meta.id.cross;em.line})

For theoretical line databases, identified will be synonymous to predicted.
\end{itemize}

For the output:

\begin{itemize}
\item Exactly one field \textbf{MAY} have name={\textquotedbl}correctionStatus{\textquotedbl}, datatype={\textquotedbl}char{\textquotedbl} and
ucd=\ucd{meta.id.cross;em.wl.central}, describing if the wavelength has been calculated.

Please note that for uncorrected lines, the compulsory field with name={"\textbf{vacuum\_wavelength}"} (corrected wavelength in vacuum)
will contain either the observed wavelength for ''Uncorrected'' or a
provisional assignment value.

\item Exactly one field \textbf{MAY} have name={"\textbf{identificationStatus}"}, with
datatype={\textquotedbl}char{\textquotedbl} and
ucd=\ucd{meta.id.cross;em.line}, describing the identification status of the line.

\end{itemize}


\section{SLAP valid response example}

\auxiliaryurl{lines-response-example.vot}

\section{Mapping between /lines endpoint parameters and VAMDC restrictables}

\begin{table}[H]
\centering
\small
\begin{tabularx}{\textwidth}{|p{4.5cm}|>{\raggedright\arraybackslash}X|}
\hline
\textbf{SLAP2 parameter name} & \textbf{VAMDC restrictable name} \\
\hline
WAVELENGTH           & RadTransWavelength                  \\
SPECIES              & AtomSymbol, Molecule\-Chemical\-Name, Molecule\-Ordinary\-Structural\-Formula \\
INCHIKEY             & InchiKey                            \\
SPECIES\_MASS        & AtomMass, Molecule\-Molecular\-Weight   \\
ION\_CHARGE          & IonCharge                           \\
LOWER\_LEVEL\_ENERGY & StateEnergy                         \\
UPPER\_LEVEL\_ENERGY & StateEnergy                         \\
EINSTEINA            & RadTransProbabilityA                \\
MAXREC               & Not available                       \\
RESPONSEFORMAT       & Not available                       \\
\hline
\end{tabularx}
\caption{ /lines endpoint parameters and VAMDC restrictables mapping table }
\end{table}


\section{Mapping between /lines endpoint output fields and VAMDC returnables}

\begin{table}[H]
\centering
\footnotesize
\begin{tabularx}{\textwidth}{|p{4cm}|>{\raggedright\arraybackslash}X|p{2.3cm}|p{1.5cm}|}
\hline
\textbf{SLAP2 field name} & \textbf{VAMDC returnable name} & \textbf{Requirements for compliance in SLAP2} & \textbf{Nullable} \\
\hline
vacuum\_wavelength                     & RadTransWavelength                                            & MUST    &  NO   \\
vacuum\_wavelength\_error              & RadTransWavelength\-Accuracy                                    & MUST    &  YES  \\
line\_title                            & RadTransComment                                               & MUST    &  NO   \\
species\_name                          & AtomSymbol, Molecule\-Chemical\-Name                              & MUST    &  NO   \\
species\_mass                          & AtomMass, Molecule\-Molecular\-Weight                             & MAY     &  YES  \\
inchikey                               & Atom\-Inchi\-Key, Molecule\-Inchi\-Key                            & MUST    &  NO   \\
inchi                                  & AtomInchi, MoleculeInchi                                      & MUST    &  NO   \\
ion\_charge                            & Atom\-Ion\-Charge, Molecule\-Ion\-Charge                          & MUST    &  NO   \\
lower\_level\_description              & Atom\-State\-Description, Molecule\-State\-Description            & MUST    &  YES  \\
upper\_level\_description              & Atom\-State\-Description, Molecule\-State\-Description            & MUST    &  YES  \\
observed\_wavelength                   & RadTrans\-Wavelength + RadTrans\-Wavelength\-Method = observed    & MAY     &  YES  \\
einstein\_a                            & RadTransProbabilityA                                          & MAY     &  YES  \\
lower\_level\_energy                   & StateEnergy                                                   & MAY     &  YES  \\
upper\_level\_energy                   & StateEnergy                                                   & MAY     &  YES  \\
reference\_doi                         & SourceDOI                                                     & SHOULD  &  YES  \\
reference\_uri                         & SourceURI                                                     & SHOULD  &  YES  \\
reference\_additional\_uri             & SourceURI                                                     & MAY     &  YES  \\
\hline
\end{tabularx}
\caption{/lines endpoint output fields and VAMDC returnables mapping table}
\end{table}

\section{Mapping between /species endpoint parameters and VAMDC restrictables}

\begin{table}[H]
\centering
\footnotesize
\begin{tabularx}{\textwidth}{|p{5.8cm}|>{\raggedright\arraybackslash}X|}
\hline
\textbf{SLAP2 parameter name} & \textbf{VAMDC restrictable name}\\
\hline
SPECIES\_TYPE                         & Not available                       \\
INCHIKEY                              & InchiKey                            \\
INCHI                                 & Inchi                               \\
SPECIES                               & AtomSymbol, Molecule\-Chemical\-Name, Molecule\-Ordinary\-Structural\-Formula \\
STOICHIOMETRIC\_FORMULA               & Molecule\-Stoichio\-metric\-Formula     \\
NUMBER\_OF\_ATOMS                     & Not available                        \\
MAXREC                                & Not available                        \\
RESPONSEFORMAT                        & Not available                        \\
\hline
\end{tabularx}
\caption{ /species endpoint parameters and VAMDC restrictables mapping table }
\end{table}



\section{Mapping between /species endpoint output fields and VAMDC returnables}

\begin{table}[H]
\centering
\footnotesize
\begin{tabularx}{\textwidth}{|p{5cm}|>{\raggedright\arraybackslash}X|p{2.5cm}|p{1.5cm}|}
\hline
\textbf{SLAP2 field name} & \textbf{VAMDC returnable name} & \textbf{Requirements for compliance}  & \textbf{Nullable}  \\
\hline
species\_name                     & AtomSymbol, Molecule\-Chemical\-Name    & MUST     &  NO   \\
ion\_charge                       & Atom\-Ion\-Charge, Molecule\-Ion\-Charge & MUST     &  NO   \\
inchikey                          & Atom\-Inchi\-Key, Molecule\-Inchi\-Key   & MUST     &  NO   \\
inchi                             & AtomInchi, MoleculeInchi                & MUST     &  NO   \\
species\_stoichiometric\_formula  & Molecule\-Stoichio\-metric\-Formula      & MUST     &  YES  \\
species\_type                     & Not available                    & SHOULD   &  YES  \\
number\_of\_atoms                 & Not available                    & SHOULD   &  YES  \\

\hline
\end{tabularx}
\caption{/species endpoint output fields and VAMDC returnables mapping table}
\end{table}

\section{Changes from Previous Versions}

\subsection{Changes from version 1}
\todo{fill in}
% these would be subsections "Changes from v. WD-..."
% Use itemize environments.

\bibliography{bibliography/ivoabib,bibliography/docrepo,bibliography/other}

\end{document}