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.}


\editor{Moreau, N.}

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

\def\ivoaDocdatecode{20250627} 
\def\ivoaDocname{SLAP2}
\def\ivoaDocversion{1.0}
\def\ivoaDocdate{2025-06-17}
\def\ivoaDocauthors{Nicolas Moreau} 
\def\ivoaDocstatus{WD} 
\def\ivoaDocid{IVOA-SLAP2-1.0}
\def\ivoaDoctype{WD}

\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 CHEMICAL\_ELEMENT 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 CHEMICAL\_ELEMENT 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.

Selecting the lines before retrieval is a significant optimisation in this case, as in wider spectra at least hundreds of thousands of lines will be within the spectral range, while it probably rarely makes sense to plot more than a hundred or so. Hence, careful selection of lines can reduce the volume of data transferred and processed by the client by several orders of magnitude.

To make good on this promise, the service need to be queryable such that lines suspected to be strong for some combination of chemistry, temperature, and pressure can be filtered out with some accuracy. 

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

CHEMICAL\_ELEMENT=H\&CHEMICAL\_ELEMENT=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 range values
are encoded using the VOTable array serialisation (space separated). If the
lower or upper bound is not specified, the range is open-ended. In 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.

\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{MAXREC}

The MAXREC parameter, defined in DALI, 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{CHEMICAL\_ELEMENT}

The \textbf{CHEMICAL\_ELEMENT} parameter would constrain the search to
the selected chemical element. A list of different chemical elements
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}). 
Molecules can be specified by conventional molecular name (formula like CO2, CH4 or names like carbon or water {\dots}) 
which might not be unique (corresponding VAMDC restrictable is {\textquotedbl}MoleculeChemicalName{\textquotedbl}). 
The \{species\} endpoint is the recommended place to discover the correct syntax of a given species in a particular service.

Filter results for Iron only : 

\parexample{CHEMICAL\_ELEMENT=Fe}

Filter results for Carbon Dioxide molecule only:

\parexample{CHEMICAL\_ELEMENT=CO2}


\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 chemical element 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}


\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{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 chemical element specified in CHEMICAL\_ELEMENT
parameter. If it is not defined, the restriction will be applied to all
the ions available. If several CHEMICAL\_ELEMENT 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{CHEMICAL\_ELEMENT=Fe\&ION\_CHARGE=1}

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

\parexample{CHEMICAL\_ELEMENT=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{TEMPERATURE}

The \textbf{TEMPERATURE} parameter specifies the minimum and maximum expected temperatures of the object, to
be specified in Kelvin (ucd=\ucd{phys.temperature};corresponding VAMDC restrictable
is {\textquotedbl}EnvironmentTemperature{\textquotedbl}). This parameter would be used (in particular for
theoretical spectral line databases) to sort the lines in the output
using physical models.

Temperature between 10 and 50 Kelvins:

\parexample{TEMPERATURE=10 50}

\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{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{Successful output}
\label{sect:lines-output}

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 :
\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 application/x-www-form-urlencoded 
form of the query parameters in the query part of the URL. 

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


\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"}}.
The NULL value is not authorized.

\subsubsection{vacuum\_wavelength\_original}

At most one field \textbf{MAY} have name={"vacuum\_wavelength\_original"},
with datatype={"double"} and ucd=\ucd{"em.wl"}. If present, this field will contain the wavelength in vacuum 
of the transition originating the line, expressed in the original unit used in the source database
(if the value was not originally provided in meters).
The content of the unit attribute specifies the original unit in accordance with 
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.

The corresponding VAMDC returnable is  {"\textbf{RadTransWavelength"}}.


\subsubsection{vacuum\_wavelength\_error}

Exactly one field \textbf{MUST} have name={"vacuum\_wavelength\_error"},
with datatype={"double"}, unit={"m"} and
ucd=\ucd{"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"}}.
The NULL value is authorized if the value is unknown.

\subsubsection{vacuum\_wavelength\_error\_original}

Exactly one field \textbf{MAY} have name={"vacuum\_wavelength\_error\_original"},
with datatype={"double"} and ucd=\ucd{"em.wl"}, containing the total error for the wavelength in
vacuum of the transition originating the line. The unit specified in the unit attribute must be 
identical to the one used in the \textbf{vacuum\_wavelength\_original} field. 

The corresponding VAMDC returnable is  {"\textbf{RadTransWavelengthAccuracy"}}.


\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. The NULL value is not authorized.

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|
\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{chemical\_element\_name}

Exactly one field \textbf{MUST} have 
name={"chemical\_element\_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.
The NULL value is not authorized.

\subsubsection{chemical\_element\_mass}

At most one field \textbf{MAY} have name={"chemical\_element\_mass"}, with  datatype={"float"} and ucd=\ucd{"phys.atmol.element"}. 
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 chemical element of this line. For an atom, the corresponding VAMDC returnable is  {"\textbf{{AtomInchiKey}}"} 
and {"\textbf{{MoleculeInchiKey}}"} for a molecular line.
The NULL value is not authorized.

\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
chemical element of this line. The corresponding VAMDC returnable is  {"\textbf{{AtomInchi}}"} 
for an atomic line and  {"\textbf{{MoleculeInchi}}"} for a molecular line.
The NULL value is not authorized.

\subsubsection{ion\_charge}

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

\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.
The NULL value is authorized.

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.
The NULL value is authorized.

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

\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{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{process}

At most one field \textbf{MAY} have name={"process"}, with
datatype={"char"} and arraysize={"*"} 
describing the process for the considered transition. 
Possible values are excitation or deexcitation. 
The corresponding VAMDC returnable is  {"\textbf{RadTransProcess}"}.

\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}"}.

\subsubsection{lower\_level\_energy\_original}

At most one field \textbf{MAY} have name={"lower\_level\_energy\_original"}, with
datatype={"double"} and ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the lower level of the transition which originates this line. 

If present, this field will contain the energy for the lower level of the transition which originates this line, 
expressed in the original unit used in the source database
(if the value was not originally provided in Joules).
The content of the unit attribute specifies the original unit in accordance with 
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.

The corresponding VAMDC returnable is  {"\textbf{StateEnergy}"}.


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

\subsubsection{upper\_level\_energy\_original}

At most one field \textbf{MAY} have name={"upper\_level\_energy\_original"}, with
datatype={"double"} and ucd=\ucd{"phys.energy;phys.atmol.level"},
describing the energy for the upper level of the transition which originates this line. 

If present, this field will contain the energy for the upper level of the transition which originates this line, 
expressed in the original unit used in the source database
(if the value was not originally provided in Joules).
The content of the unit attribute specifies the original unit in accordance with 
the Units in the VO recommendation \citep{2023ivoa.spec.1215G}.

The corresponding VAMDC returnable is  {"\textbf{StateEnergy}"}.

\subsubsection{transition}

At most one field \textbf{MAY} have name={"transition"}, with
datatype={"char"}, arraysize={"*"} and ucd=\ucd{"phys.atmol.transition"}.
If present, this field will contain a human readable description of the transition in terms of electron configurations
and/or quantum states before and after. A syntax suggestion is provided in the following paragraphs. 
As this is a protocol meant to stay simple, the text representation is voluntarily simplified. The user
is encouraged to use the VAMDC infrastructure to get a more detailed and standardized description of the levels.

\paragraph{Atomic configuration}

It is recommended to use a LaTeX-styled \citep{lamport86latex} convention to describe sub-indexes,
super-indexes, greek characters, etc. That means the previous atomic
configuration could be serialized as string in the SLAP response in the
following way:

$$\hbox{3d\textasciicircum6 4s\textasciicircum2}$$

In the case of molecular levels, we usually need to use Greek symbols,
so, e.g.,

$$
\textrm{\textsuperscript{2}}\textrm{\textit{\textsuperscript{S}}}\textrm{\textsuperscript{
+ 1}}\textrm{$\Lambda $}\textrm{\textsubscript{$\Omega
$}}\textrm{ }
$$

would be serialized as

$$\hbox{\^\{2S+1\}{\textbackslash}Lambda \_\{{\textbackslash}Omega \}}$$

See \citep{lamport86latex} for a complete reference.

\paragraph{Molecular level quantum states}

The recommended syntax for the quantum numbers is name:numerator:denominator. Quantum Numbers are separated by the ``;'' character.
To allow for levels needing more than one quantum state to be described, the quantum states would be enclosed by square brackets. 
Example: [J:1:1;F1:0:1;F:1:1]

\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 the chemical elements 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{ELEMENT\_TYPE}

The \textbf{ELEMENT\_TYPE} parameter specifies the type of chemical elements 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{ELEMENT\_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{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{CHEMICAL\_ELEMENT}

The \textbf{CHEMICAL\_ELEMENT} parameter defines an expression using the SQL LIKE syntax to perform
a search in the list of chemical elements provided by the service. The search is case-sensitive.

Returns carbon monoxide and carbon dioxide :
\parexample{CHEMICAL\_ELEMENT=CO\_}

Returns Cobalt atom :
\parexample{CHEMICAL\_ELEMENT=Co}

Returns all the chemical species whose formula ends with "OH" :
\parexample{CHEMICAL\_ELEMENT=\%OH}


\subsubsection{STOICHIOMETRIC\_FORMULA}

The stoichiometric formula is a chemical expression that indicates the quantitative composition of 
atoms that make up the molecule, e.g. CO2, NH3, CH4.

The \textbf{STOICHIOMETRIC\_FORMULA} parameter defines an expression using the SQL LIKE syntax to perform
a search in the list of stoichiometric formula provided by the service.The search is case-sensitive.

Returns all the chemical species whose stoichiometric formula starts with CO :

\parexample{STOICHIOMETRIC\_FORMULA=CO\%}


\subsection{Successful output}
\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{chemical\_element\_name}

Exactly one field \textbf{MUST} have
name={"chemical\_element\_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
chemical element for which at least one spectral line is available in
the service. The NULL value is not authorized.

\subsubsection{ion\_charge}

Exactly one field \textbf{MUST} have name={"ion\_charge"} with datatype={"int"} and ucd=\ucd{"phys.atmol.element;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. The NULL value is not authorized.

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

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

\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 chemical element. The corresponding VAMDC returnable is  {"\textbf{AtomInchi}"} for an atom and {"\textbf{MoleculeInchi}"} for a molecule. The NULL value is not authorized.

\subsubsection{chemical\_element\_stoichiometric\_formula}

Exactly one field \textbf{MUST} have
name={"chemical\_element\_stoichiometric\_formula"}, datatype={"char"},
arraysize={"*"} and
ucd=\ucd{"phys.atmol.element"}, containing the stoichiometric formula of a chemical element 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. The NULL value is authorized.

\subsubsection{chemical\_element\_type}

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

\subsubsection{number\_of\_elements}

At most one field \textbf{SHOULD} have name={"number\_of\_elements"}, 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:

\begin{lstlisting}[language=XML,basicstyle=\small\ttfamily]
<vosi:capabilities
  xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1">
  <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
    <interface xsi:type="vs:ParamHTTP" role="std">
      <accessURL use="full">
        http://example.com/slap2/capabilities
     </accessURL>
    </interface>
  </capability>
  <capability standardID="ivo://ivoa.net/std/VOSI#availability">
    <interface xsi:type="vs:ParamHTTP" role="std">
      <accessURL use="full">
        http://example.com/slap2/availability
      </accessURL>
    </interface>
  </capability>
  <capability standardID="ivo://ivoa.net/std/SLAP#species-2.0">
    <interface xsi:type="vs:ParamHTTP" role="std" version="2.0">
      <accessURL>
        http://example.com/slap2/species
      </accessURL>
    </interface>
  </capability>
  <capability standardID="ivo://ivoa.net/std/SLAP#lines-2.0">
    <interface role="std" version="2.0" xsi:type="vs:ParamHTTP">
      <accessURL use="base">http://example.com/slap2/lines?</accessURL>
      <queryType>GET</queryType>
      <resultType>application/x-votable+xml</resultType>
      <param std="true" use="optional">
        <name>wavelength</name>
        <description>wavelength in the vacuum of the transition originating in the line</description>
        <unit>m</unit>
        <ucd>em.wl</ucd>
        <dataType arraysize="2">real</dataType>
      </param>
      <param std="true" use="optional">
        <name>inchikey</name>
        <description>Inchikey of the searched chemical element</description>
        <ucd>phys.atmol.element</ucd>
        <dataType arraysize="*">char</dataType>        
      </param>
      <param std="true" use="optional">
        <name>chemical_element</name>
        <description>Name of the searched chemical element</description>
        <ucd>phys.atmol.element</ucd>
        <dataType arraysize="*">char</dataType>
      </param>
      <param std="true" use="optional">
        <name>ion_charge</name>
        <description>Minimum and maximum charge of an ion</description>
        <ucd>phys.atmol.element;phys.atmol.ionization</ucd>
        <dataType arraysize="2">integer</dataType>
      </param>
      <!-- custom service parameter -->
      <param std="false" use="optional">
        <name>wavenumber</name>
        <description>Minimum and maximum wavenumber of the line</description>
        <ucd>em.wavenumber</ucd>
        <unit>m**-1</unit>
        <dataType arraysize="2">real</dataType>
      </param>
    </interface>
  </capability>
</vosi:capabilities>
\end{lstlisting}

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

\begin{lstlisting}[language=XML,basicstyle=\small\ttfamily]
<VOTABLE version="1.3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.ivoa.net/xml/VOTable/v1.3"
	xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3 http://www.ivoa.net/xml/VOTable/VOTable-1.3.xsd"
	xmlns:ssldm="http://www.ivoa.net/xml/SimpleSpectralLineDM/v2.0">
	<RESOURCE type="results">
		<INFO name="QUERY_STATUS" value="OK" />
		<INFO name="request_date" value="2025-10-31T14:57:18+01:00" />
		<INFO name="service_ivoid" value="ivo://myvo.org/slap2" />
		<INFO name="service_protocol" value="ivo://ivoa.net/std/SLAP#lines-2.0" />
		<INFO name="publisher" value="myvo.org" />
		<INFO name="last_update_date" value="2025-05-31T10:05:00+01:00" />
		<TABLE>
			<FIELD ucd="em.wl" name="vacuum_wavelength" datatype="double" unit="m" />
      <FIELD ucd="em.wl" name="vacuum_wavelength_error" datatype="double" unit="m" />
			<FIELD ucd="meta.title" name="line_title" datatype="char" arraysize="*" />
			<FIELD ucd="phys.energy;phys.atmol.level" name="lower_level_energy"
				datatype="double" unit="J" />
			<FIELD ucd="phys.energy;phys.atmol.level" name="upper_level_energy" datatype="double" unit="J" />
			<FIELD ucd="meta.title;phys.atmol.level" name="lower_level_description" datatype="char" arraysize="*" />
			<FIELD ucd="meta.title;phys.atmol.level" name="upper_level_description" datatype="char" arraysize="*" />
			<FIELD ucd="phys.atmol.transProb" name="einstein_a" datatype="double" unit="1/s" />
			<FIELD ucd="phys.atmol.element" name="chemical_element_name" datatype="char" arraysize="*" />
			<FIELD ucd="phys.atmol.element;phys.atmol.ionization" name="ion_charge" datatype="int" />
			<FIELD ucd="phys.atmol.element" name="inchikey" datatype="char" arraysize="*" />
			<FIELD ucd="phys.atmol.element" name="inchi" datatype="char" arraysize="*" />
			<FIELD ucd="meta.ref.doi" name="reference_doi" datatype="char" arraysize="*" />
			<DATA>
				<TABLEDATA>
					<TR>
						<TD>9.0001e-08</TD>
            <TD></TD>
						<TD>element : Molecular deuterium, upper energy : 2.3505030918e-18 , lower energy : 1.43849952e-19 </TD>
						<TD>1.43849952e-19</TD>
						<TD>2.3505030918e-18</TD>
						<TD>ElecStateLabel=X  J=12  v=1 </TD>
						<TD>ElecStateLabel=B'  J=13  v=5  elecInv=u  elecRefl=+  Lambda=0  S=0  KronigParity=e </TD>
						<TD>11629800.0</TD>
						<TD>Molecular deuterium</TD>
						<TD>0</TD>
						<TD>UFHFLCQGNIYNRP-VVKOMZTBSA-N</TD>
						<TD>InChI=1S/H2/h1H/i1+1D</TD>
						<TD>10.1088/0953-4075/32/15/313</TD>
					</TR>
					<TR>
						<TD>9.0001e-08</TD>
            <TD></TD>
						<TD>element : Molecular deuterium, upper energy : 2.2695378438e-18 , lower energy : 6.288390960000001e-20 </TD>
						<TD>6.288390960000001e-20</TD>
						<TD>2.2695378438e-18</TD>
						<TD>ElecStateLabel=X  J=2  v=1 </TD>
						<TD>ElecStateLabel=B  J=1  v=35  elecInv=u  elecRefl=+  Lambda=0  S=0  KronigParity=e </TD>
						<TD>14548700.0</TD>
						<TD>Molecular deuterium</TD>
						<TD>0</TD>
						<TD>UFHFLCQGNIYNRP-VVKOMZTBSA-N</TD>
						<TD>InChI=1S/H2/h1H/i1+1D</TD>
						<TD>10.1088/0953-4075/32/15/313</TD>
					</TR>
				</TABLEDATA>
			</DATA>
		</TABLE>
	</RESOURCE>
</VOTABLE>

\end{lstlisting}

\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                  \\
CHEMICAL\_ELEMENT    & AtomSymbol, MoleculeChemicalName    \\
INCHIKEY             & InchiKey                            \\
SPECIES\_MASS        & AtomMass, MoleculeMolecularWeight   \\
ION\_CHARGE          & IonCharge                           \\
LOWER\_LEVEL\_ENERGY & StateEnergy                         \\
UPPER\_LEVEL\_ENERGY & StateEnergy                         \\
TEMPERATURE          & EnvironmentTemperature              \\
EINSTEINA            & RadTransProbabilityA                \\
MAXREC               & N/A                                 \\
\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
\small
\begin{tabularx}{\textwidth}{|p{5.5cm}|>{\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\_original           & RadTransWavelength                                            & MAY     &  YES  \\
vacuum\_wavelength\_error              & RadTransWavelengthAccuracy                                    & MUST    &  YES  \\
vacuum\_wavelength\_error\_original    & RadTransWavelengthAccuracy                                    & MAY     &  YES  \\
line\_title                            & RadTransComment                                               & MUST    &  NO   \\
chemical\_element\_name                & AtomSymbol, MoleculeChemicalName                              & MUST    &  NO   \\
chemical\_element\_mass                & AtomMass, MoleculeMolecularWeight                             & MAY     &  YES  \\
inchikey                               & AtomInchiKey, MoleculeInchiKey                                & MUST    &  NO   \\
inchi                                  & AtomInchi, MoleculeInchi                                      & MUST    &  NO   \\
ion\_charge                            & AtomIonCharge, MoleculeIonCharge                              & MUST    &  NO   \\
lower\_level\_description              & AtomStateDescription, MoleculeStateDescription                & MUST    &  YES  \\
upper\_level\_description              & AtomStateDescription, MoleculeStateDescription                & MUST    &  YES  \\
observed\_wavelength                   & RadTransWavelength + RadTransWavelengthMethod = observed      & MAY     &  YES  \\
einstein\_a                            & RadTransProbabilityA                                          & MAY     &  YES  \\
process                                & RadTransProcess                                               & MAY     &  YES  \\
lower\_level\_energy                   & StateEnergy                                                   & MAY     &  YES  \\
lower\_level\_energy\_original         & StateEnergy                                                   & MAY     &  YES  \\
upper\_level\_energy                   & StateEnergy                                                   & MAY     &  YES  \\
upper\_level\_energy\_original         & StateEnergy                                                   & MAY     &  YES  \\
transition                             & Not available                                                 & 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
ELEMENT\_TYPE                         & Not available                       \\
INCHIKEY                              & InchiKey                            \\
CHEMICAL\_ELEMENT                     & AtomSymbol, MoleculeChemicalName    \\
STOICHIOMETRIC\_FORMULA               & MoleculeStoichiometric\-Formula     \\
NUMBER\_OF\_ELEMENTS                  & 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
\small
\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
chemical\_element\_name                     & AtomSymbol, MoleculeChemicalName & MUST     &  NO   \\
ion\_charge                                 & AtomIonCharge, MoleculeIonCharge & MUST     &  NO   \\
inchikey                                    & AtomInchiKey, MoleculeInchiKey   & MUST     &  NO   \\
inchi                                       & AtomInchi, MoleculeInchi         & MUST     &  NO   \\
chemical\_element\_stoichiometric\_formula  & MoleculeStoichiometricFormula    & MUST     &  YES  \\
chemical\_element\_type                     & Not available                    & SHOULD   &  YES  \\
number\_of\_elements                        & 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.bib}

\end{document}