EPNTAP.tex

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

\usepackage{wasysym}

\iftth
\def\ucd#1{\texttt{#1}}
\else
\makeatletter
\def\ucd{\st@rtucd\re@lucd}
\def\re@lucd#1{\sl#1\@nducd}
\begingroup
% let LaTeX break UCD componds and at dots and semicolons in UCDs
\gdef\bre@kabledot{.\hskip0pt}
\gdef\bre@kablesemicolon{;\hskip0pt}
\catcode`\.=\active\catcode`\;=\active
\gdef\st@rtucd{\begingroup
  \catcode`\.=\active\let.=\bre@kabledot
  \catcode`\;=\active\let;=\bre@kablesemicolon}
\gdef\@nducd{\endgroup}
\endgroup
\makeatother
\fi

\DeclareUnicodeCharacter{00B0}{$^\circ$}
\DeclareUnicodeCharacter{00B5}{$\mu$}
\DeclareUnicodeCharacter{00B1}{$\pm$}

% epn-tap has some wide displays; give it a bit more room (at
% the expense of readability).
\usepackage[lmargin=2cm,rmargin=3cm]{geometry}
\usepackage{pdflscape}
\usepackage{longtable}
\usepackage{rotating}
\usepackage{tabulary}
\usepackage{todonotes}

\lstloadlanguages{SQL,XML}
\lstset{flexiblecolumns=true,numberstyle=\small,showstringspaces=False,
  identifierstyle=\texttt}

\title{EPN-TAP: Publishing Solar System Data to the Virtual Observatory}

% see ivoatexDoc for what group names to use here
\ivoagroup{Data Access Layer}

\author{St\'ephane Erard}
\author{Baptiste Cecconi}
\author{Pierre Le Sidaner}
\author{Markus Demleitner}
\author{Mark Taylor}

\editor{St\'ephane Erard}
\editor{Baptiste Cecconi}

% \previousversion[????URL????]{????Funny Label????}
\previousversion{This is the first public release}


\begin{document}
\begin{abstract}
This document defines the EPN-TAP framework, which is using TAP with
the EPNCore metadata dictionary. The EPNCore metadata dictionary defines
the core components that are necessary to perform data discovery in the
Solar System related science fields. It includes parameters to describe
data products coverage (temporal, spectral, spatial, photometric), origin
(instrument, facility), content (target, physical parameters), access,
references, etc. Its implementation with TAP (Table Access Protocol) is
presented, including service registration guidelines. Topical extension
metadata dictionaries are also presented.
\end{abstract}


\section*{Acknowledgments}

EPNCore has been developed by the VESPA (Virtual European Solar
and Planetary Access) team.  VESPA has been designed in the frame of
Europlanet 2020 Research Infrastructure project and finalized
during the Europlanet 2024 Research Infrastructure project,
based on an assessment phase in the Europlanet Research Infrastructure
 programme, JRA4 work package (IDIS activity).

The Europlanet-RI project was funded by the European Commission under the
7th Framework Program, grant 228319 ``Capacities Specific Programme''.
The Europlanet 2020 Research Infrastructure project has
received funding from the European Union's Horizon 2020 research and
innovation programme under grant agreement No 654208.  The Europlanet-2024
Research Infrastructure project has received funding from
the European Union's Horizon 2020 research and innovation programme under
grant agreement No 871149.  Additional funding was provided in France by
the CNRS / Action Sp\'ecifique Observatoire Virtuel and Programme National
de Plan\'etologie / INSU, as well as CNES, through the participation to
IPDA activities.

\section*{Conformance-related definitions}

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*{List of Acronyms}
\begin{itemize}
\item{ADQL} Astronomical Data Query Language
\item{APIS} Auroral Planetary Imaging and Spectroscopy
\item{CAOM} Common Archive Observation Model
\item{CNRS} Centre National de la Recherche Scientifique
\item{CNES} Centre National d'Etudes Spatiales
\item{EPN} Europlanet (series of EC-funded programmes)
\item{IDIS} Integrated and Distributed Information System
\item{INSU} Institut National des Sciences de l'Univers
\item{IPDA} International Planetary Data Alliance
\item{PDS} Planetary Data System (NASA data archive for planetary missions)
\item{PDS3/4} Successive data formatting standards for space agencies
\item{PSA} Planetary Science Archive (ESA data archive for planetary missions)
\item{SPASE} Space Physics Archive Search and Extract
\item{TAP} Table Access Protocol
\item{UCD} Unified Content Descriptors
\item{VESPA} Virtual European Solar and Planetary Access
\end{itemize}

\section{Introduction}


This document defines the EPN-TAP framework. EPN-TAP is a protocol
used to describe and access data related to the study of the Solar
System in general, including observational, modeled, and experimental
data. It consists of 1) the usual TAP mechanism; 2) the EPNCore metadata
dictionary; 3) a set of rules defining table structure and column
usage. EPN-TAP relies on the TAP (Table Access Protocol) standard with
no modification \citep{2019ivoa.spec.0927D}, so that only items 2 and 3
are described here.
All EPN-TAP services are accessible through standard TAP clients.

Its implementation with TAP is presented, including parameter usage
(sections \ref{sect:dictionary} and \ref{sect:epntable})
and service registration
guidelines (section~\ref{sect:registry}).

The first version of EPN-TAP was developed as an assessment study
during the Europlanet-RI programme (2011), and was limited to test purposes. It
was redesigned to EPN-TAP 2.0 before the start of Europlanet 2020 RI and
completed during the following programme Europlanet 2024 RI based on a large
set of data services and use cases. This later version is described here.


\subsection{EPN-TAP design}

The EPNCore metadata dictionary defines the core components that are
necessary to perform data discovery in science fields related to the
Solar System and related fields. The EPNCore metadata dictionary includes
parameters to describe data products coverage (temporal, spectral, spatial,
illumination conditions), origin (instrument, facility), content (target,
physical parameters), access, references, etc. The notion of \textbf{parameter} is
derived from the ``keywords'' of the PDS
standard used to archive planetary space missions. They are intended
either as search parameters or descriptive ones, although in TAP they
can all be searched by value. In this sense, EPNCore bears similarities
with the ObsCore standard \citep{2017ivoa.spec.0509L} from which it borrows several concepts.

EPN-TAP also uses the notion of \textbf{granule} (inherited from the SPASE standard)
to refer to the data service granularity, which is smallest data unit
provided by a service and described individually in the associated
table. A ``granule'' can correspond to a data file, a set of scalar
values, a call to a web service, a query to a data service in a different
protocol, etc.
Grouping of data into granules is at the discretion of the data
provider. This may be equivalent to ``dataset'' or ``data product''
in other contexts, but these words are avoided here because they have
a different meaning in many Planetary Science archives.

An EPN-TAP service therefore consists of a single table describing a
list of granules with the metadata dictionary: a granule corresponds
to a row of the table, while a parameter corresponds to a column.
Only one data product can be described and linked per row of the table.
Observations, simulations, or experimental data are supported.
Several independent services can reside on a single server.

The global philosophy of EPN-TAP is to describe all tables with a common
set of mandatory parameters which can be used to query all EPN-TAP
services together, which is the scope of the VESPA portal. A unique query
can then be sent to and answered by all data services without generating
errors. This also requires that all parameter values are provided in
a standard form, in particular with standard units. In other words,
mandatory parameters have to be present in an EPN-TAP service and must
provide values in standard form. Although most of them can be left
empty when non-relevant or unknown, care should be taken to fill as many
parameters as possible to provide a better service to the user.

In addition to these mandatory parameters, the EPN-TAP dictionary includes
optional parameters which are grouped in two levels: 1) common, general
purpose parameters provide complementary information; 2) parameters from
thematic extensions have been defined from a set of related data services
and must be used consistently in data services in these fields. The first
group includes file access information and additional description of data
and target. The second group defines additional axes and provides extra
parameters to describe similar observations consistently. The optional
parameters can be used independently of each other
(except the min/max pairs which need to appear together).

Finally, EPN-TAP allows data providers to use entirely new parameters in a
data service to provide specific information, when no existing parameter
applies. This may occur in particular when the data consist in a few
scalar values included in the table itself as individual parameters. Such
parameters are best defined in consistency with existing ones, and may
eventually be included in thematic extensions.
Parameter names are given in lower case, they must not include spaces
or special characters; underscore is used as separator.

Section 2 provides a description of parameters and their usage. All the
currently defined parameters are listed in Section \ref{sect:epntable}
(table) with their
type, unit, and UCD.

EPNCore usage is not limited to data distribution and access through
TAP. It also provides a standard way to describe Planetary Science data,
e.g., to handle local databases and private projects while benefiting
from interfaces with VO tools, in particular with TOPCAT, Aladin, and
CASSIS, which were closely associated to this development.

\subsection{EPN-TAP rules applying to table structure and parameter usage}


\begin{itemize}
\item \textbf{Rules related to data services and table structure include:}

\begin{itemize}
\item A service consists of one database schema containing only one table.
The table must be called <schema>.epn\_core.

\item Only one data product is linked per table row, and parameters
in that row describe that product. In case the same data product is
distributed with several formats, there can be either one row per format,
or a single row providing access to the preferred format,
while other formats are distributed through an associated datalink.


\item Related files providing documentation of the data product can
however be associated through thumbnail\_{url} (quick-look image),
datalink\_url (various documents and links), and external\_link (web
page providing more discussion of this granule).

\item Data services are declared in the IVOA registry of services
according to TAP guidelines (section~\ref{sect:registry}).

\item The service metadata must include the usual elements to allow
discovery in the registry. Subject elements should be taken from the IVOA
flavored Unified Astronomy Thesaurus (UAT) when available. At least one of
these top-level keywords of the UAT must be provided: exoplanet-astronomy,
solar-physics, solar-system-astronomy, planetary-science.

\item Data service output VOTables should include TIMESYS and COOSYS
elements when constant. This is not always true, see time\_scale  and
space\_origin parameters for details.

\item Data service output must pass validation;
an EPN-TAP service validator is included in
STILTS/taplint\footnote{\url{http://www.starlink.ac.uk/stilts/sun256/taplint.html}}.
\end{itemize}


\item \textbf{Rules related to parameters include:}

\begin{itemize}
\item Parameters defining a range along an axis most often appear as a
pair with *\_min and *\_max variations.  Both values must be provided
to support ranges correctly. If only one value is available, it must
appear in both parameters.

\item Parameters accept values in lower case, except when a global
standard or vocabulary applies. This is the case in particular with
Solar System object names, which follow the IAU naming convention.

\item Empty parameters can be void or can contain the NULL value.

\item Most floating-point parameters only require single precision,
with the exception of time\_min and time\_max which must be stored and
returned in double precision to preserve the required accuracy.

\item Some string parameters can be multivalued. Lists of values must be provided
as hash-separated lists (values separated by internal \# character).

\item Although each row contains at most one linked data product, special
conventions exist:
Thumbnails may be provided on the same granule row,
as far as they are intended for quick-look in the VESPA portal or
similar user interfaces; inclusion of thumbnails is recommended.
In contrast, large previews should be handled as separated data products.
Associated documents, or in some cases alternative formats, can be
attached via the datalink\_url parameter. Related web services or SODA
data services are also linked via this parameter.

\item Some parameters only accept values from a predefined list. Such
lists are provided or discussed in section \ref{sect:dictionary} and are maintained
on an external web page with a Permanent ID: \url{https://hdl.handle.net/21.15110/epn_tap_extensions}.
Whenever possible, this refers to IVOA vocabularies maintained independently.

\item Internal spaces are supported in string parameters values, but
leading or trailing spaces are not.

\item Special characters, quotes, and hash are not allowed in string parameter values,
and may be changed to \_ (underscore, which is the single-character
wildcard in ADQL LIKE conditions).

\item Although additional, service-specific parameters can be used,
care must be taken to avoid duplications or variations on existing parameters,
including those from thematic extensions.

\item Such free parameters, when very specific to a service,
may use a prefix related to this service to prevent conflicts
(e.g., myservice\_myparameter).
Associated UCDs must be extracted from the
current version of the standard (UCD1+).

\item When free parameters contain a numerical value, associated errors
should use the syntax: parameter\_error, or parameter\_error\_min
and parameter\_error\_max when asymmetrical (all non-negative). The
associated UCDs must start with ``stat.error;'', ``stat.error;stat.min;'',
or ``stat.error;stat.max;'', respectively.
\end{itemize}

Upper and lower limits can be introduced with the same 3 parameters
used to provide asymmetrical errors, say: val, val\_error\_min and
val\_error\_max. The following scheme is suggested:

\begin{itemize}
\item An upper limit can be provided with val = 0, val\_error\_min = Inf,
val\_error\_max = upper\_limit.

\item A lower limit can be provided with val = lower\_limit,
val\_error\_min = 0, val\_error\_max = Inf.
\end{itemize}

This scheme minimizes interpretation errors, simplifies graphical
representations, and preserves transforms such as value $\to$ -value.

\end{itemize}



\subsection{Role within the VO Architecture}

\begin{figure}[thb]
\centering

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

Figure~\ref{fig:archdiag} shows how EPN-TAP fits into Virtual
Observatory architecture.  EPN-TAP's main connections to other VO
standards are:

\begin{bigdescription}
\item[ADQL \citep{2008ivoa.spec.1030O}] ADQL is the preferred language to
query EPN-TAP in.  The common language is a prerequisite for global
discovery within all EPN-TAP services.
\item[TAP \citep{2019ivoa.spec.0927D}] TAP is used to transport queries,
table metadata, and the results of queries.  The re-use of TAP gives
EPN-TAP a wide range of client and server implementations.
\item[VODataService \citep{2021ivoa.spec.1102D}] VODataService tableSets
are used to discover EPN-TAP services in VO Registries.
\item[UCDs \citep{2021ivoa.spec.0616C}] UCDs associated to EPNCore
parameters provide context when manipulating EPN-TAP tables and result
VOTables. They also describe the physical quantities distributed in
services via the measurement\_type parameter, making searches by physical
quantity possible.
\item[DALI \citep{2017ivoa.spec.0517D}] DALI lays out several basic
conventions, including the serialization of data types like timestamps
and geometries.
\end{bigdescription}

\section{The EPNCore metadata parameter dictionary}
\label{sect:dictionary}

% GENERATED: python3 parse_source.py columndescription
% To ignore the following section,
% add 'Mandatory parameters' to IGNORED_SECTIONS

In EPN-TAP services, EPNCore parameters appear as table columns and describe the granules.
Mandatory parameters must be present in all EPN-TAP services, while optional
parameters can be included as needed, with specified units and UCD.

\subsection{Mandatory parameters}

\subsubsection{Granule references}

These 3 parameters must always be provided and contain a value. If granule grouping is not
relevant, use a single value for granule\_gid (and obs\_id can be
identical to granule\_uid).

\paragraph{granule\_uid}

Identifier for this row. This parameter is a primary key in epn\_core
tables, i.e., no two different rows may share the same granule\_uid.

There can be only one data file associated to a granule (plus possibly a
thumbnail for quick-look purpose in a search interface).\\
Basic ascii characters are allowed, including internal spaces, except for the \# character.


\paragraph{obs\_id}

Associates granules derived from the same data (e.g., various
representations or processing levels). May be the ID of the original
observation.

\paragraph{granule\_gid}

Associates granules of same type (e.g., same map projection, or geometry
data products) --- think of it as a simple and convenient way to group or
differentiate types of data.

When several files relate to the same data, this parameter helps
distinguishing them: this will allow the user to select the type of data
of interest.  For instance, a service may provide links to calibrated images,
plus raw data and ancillary information for every observation; these
will share the same obs\_id, but will have different granule\_gid.

\subsubsection{Data Description}

\paragraph{dataproduct\_type}

The dataproduct\_type parameter describes the high level scientific
organization of the data product linked by the access\_url parameter,
or directly included in the table (in which case the value is `ci'
for catalogue\_item). EPNCore currently defines several types listed
below. Data providers must select the type most adapted to their
data. In complex situations (e.g., when a file contains several data
products), several types can be used to describe the same granule by
using a hash-separated-list — although using several granules to
describe the file content may be a better solution.

In EPN-TAP these types are identified by a 2-characters ID, so that
multivalued queries are unambiguous. Possible IDs are listed below with
their meaning:

\begin{itemize}

\item \textbf{im }(= image): scalar field with two spatial axes, or
association of several such fields, e.g., images with multiple color
planes, from multichannel or filter cameras. Preview images (e.g., map
with axis and caption) also belong here. Conversely, vectorial 2D fields
are described as spatial\_vector (see below).

\item \textbf{ma }(= map): scalar field / rasters with two spatial axes
covering a large area and projected either on the sky or on a planetary
body, associated to spatial\_coordinate\_description and map\_projection
parameters (with a short enumerated list of possible values); each pixel
is associated to 2D coordinates (e.g., fits with WCS). This is mostly
intended to identify radiometrically calibrated and orthorectified
images with complete coverage that can be used as reference basemaps,
but this also includes HiPS.

\item \textbf{sp }(= spectrum): measurements organized primarily along a
spectral axis, e.g., radiance spectra. This includes spectral aggregates
(series of related spectral segments with non-connected spectral ranges,
e.g., from several channels of the same instrument, various orders from
an échelle spectrometer, composite spectra, SED, etc).

\item \textbf{ds }(= dynamic\_spectrum): consecutive spectral measurements
through time, organized primarily as a time series. This typically
implies successive spectra of the same target / field of view.

\item \textbf{sc }(= spectral\_cube): sets of consecutive
spectral measurements with 1 or 2D spatial coverage, e.g., imaging
spectroscopy. The choice between image and spectral\_cube is dictated by
the characteristics of the instrument (which dimension is most resolved
and which dimensions are acquired simultaneously). The choice between
dynamic\_spectrum and spectral\_cube is related to the uniformity of
the field of view and by practices in the science field.

\item \textbf{pr }(= profile): scalar or vectorial measurements along
1 spatial dimension, e.g., atmospheric profiles, atmospheric paths,
sub-surface profiles, traverses…

\item \textbf{pf }(= photometric\_function): scalar or vectorial
measurements along 1 angular dimension, e.g., phase or polarization
curves, phase functions, emission-phase function sequences… Does not
handle variations along several angular axes. This is typically associated
to variations in illumination angle parameters.

\item \textbf{vo }(= volume): measurements with 3 spatial dimensions,
e.g., internal or atmospheric structures, including shells/shape models
(3D surfaces).

\item \textbf{mo }(= movie): sets of chronological 2D spatial measurements
(consecutive images)

\item \textbf{cu }(= cube): multidimensional data with 3 or more axes,
e.g., all that is not described by other 3D data types such as spectral
cube, volume, or movie. This is intended to accommodate unusual data with multiple
dimensions. This can be used for 3D ancillary data associated to spectral
cubes, e.g., providing the coordinates and illumination angles for
each spectrum.

\item \textbf{ts }(= time\_series): measurements organized primarily
as a function of time (with exception of dynamical spectra and movies,
i.e., usually a scalar quantity). Typical examples of time series include
space-borne dust detector measurements, daily or seasonal curves measured
at a given location (e.g., a lander), and light curves.

\item \textbf{ca }(= catalogue): applies to a granule providing a
catalogue of object parameters, a list of features, a table of granules
in another TAP service, a list of events, a list of spectral lines\dots The
result metadata table of a service query can also be considered as a
catalogue. Catalogues can be provided as VOTable (possibly containing
multiple tables, although this is not supported by SAMP). It is good
practice to describe the type of data included in the catalogue using
a hash-separated-list (e.g., a table of spectra should be described by
ca\#sp, so that it will respond to a query for spectra).

\item \textbf{ci }(= catalogue\_item): applies when the service itself
provides a catalogue with entries described as individual granules, in
particular when there is no associated file (e.g., a list of asteroid
properties or spectral lines). Catalogue\_item can be limited to scalar
quantities (including strings), and possibly to a single element. This
organization allows the user to search inside the catalogue from
the TAP query interface. In practice, Spice kernels are identified as
catalogue\_items because they are usually associated to a set of scalar
parameters.

\item \textbf{sv} (= spatial\_vector): vector information associated
to localization, such as a spatial footprints, a GIS-related element,
etc —  e.g., a kml or geojson file (STC-S strings are provided though
the s\_region parameter, though). This includes maps of vectors, e.g.,
wind maps.

\item \textbf{ev} (= event): introduces individual VOevents
formatted according to IVOA standard (or possibly events with other
formatting). Characteristics are provided via the event\_* parameters.

\end{itemize}

\textbf{\\}
\emph{Example TAP queries}:

\begin{verbatim}
SELECT TOP 1000 * FROM iks.epn_core
 WHERE dataproduct_type LIKE '%sp%'
\end{verbatim}

or

\begin{verbatim}
SELECT TOP 1000 * FROM iks.epn_core
 WHERE ivo_hashlist_has(dataproduct_type, 'sp') = 1
\end{verbatim}

will return only image data (both syntaxes handle lists of values).

\paragraph{measurement\_type}

The measurement\_type parameter defines the physical quantities
contained in the data, using UCDs \citep{2021ivoa.spec.0616C}. It relates to the reported quantity,
not to the type of experiment. Therefore, only UCDs related to physical
quantities can be used; e.g., phys.absorption;em.opt.I is eligible,
while pos.lunar.occult (occultation by lunar limb) is not. This is used in particular to provide
indications to visualization/processing tools.

Whenever several quantities are comprised in the data, the
measurement\_type parameter must describe all these quantities, using
multiple UCDs in a hash-separated-list.

\textbf{\\}
\emph{Example}:

\begin{itemize}
\item For images in general (i.e., actual measurements with a camera),
the relevant UCD is phot.radiance;obs.image (or phot.radiance;obs.image;stat.uncalib if not
calibrated).

\item For spectra: phot.radiance describes radiance, phys.reflectance
stands for reflectance factor (= I/F), and phot.flux.density for a
\emph{flux} vector (irradiance). The associated spectral vector is
described by UCDs em.wl, em.freq or em.energy, and the related error
has the form stat.error;phys.reflectance (for I/F).

\item Quantities derived from modeling or simulations are described by the
regular UCD with ``;meta.modelled'' appended.
\end{itemize}

\paragraph{processing\_level}

The processing\_level parameter is intended to provide the user with
a quick evaluation of data readiness level. EPN-TAP uses
a simplified scheme as described below.

Several classifications are in use in different contexts, as summarized
in Table~\ref{table:proclev}.  EPNCore uses the CODMAC / PDS3 levels but removes
the intermediate calibration levels; this is equivalent to using the
simplified PDS4 levels and maintaining a separate level for ancillary
data. ``Partially calibrated'' data collections are in general considered as not
calibrated, but this evaluation is up to the data provider, depending on
context. ``Ancillary'' data include all extra information documenting
the measurements, in particular coordinates or geometry files. Several
processing levels can be included in the same service (in particular
calibrated and ancillary data, but also raw data). When mixed in the
same file, the choice is left to the data provider.

Note that the optional processing\_level\_desc parameter
is available to provide, e.g., a specific encoding of processing
levels related to a data collection, or more details about partial calibrations.

Most EPN-TAP data services are expected to include Calibrated or
Derived data.

\begingroup\small\begin{inlinetable}
\begin{tabular}{lllllp{2cm}lp{0.35\textwidth}}
\sptablerule
\vbox{\vskip 2pt\hbox{EPN-}\vskip 3pt\hbox{TAP2}}
&CODMAC&PSA&NASA&PDS3&PDS4&ObsTAP&Description\\
\sptablerule

1 &1 (raw)&(0?)&&UDR&Telemetry&0
  &Unprocessed Data Record (low-level encoding,
   e.g., telemetry from a spacecraft instrument.
   Normally available only to the original team)\\
2 &2 (edited)&1&0&EDR&Raw&1
  &Experiment Data Record (often referred to as ``raw data'':
   decommutated, but still affected by instrumental effects)\\
2 or 3&\_&&&\_&Partially calibrated&
  &Processed beyond the raw stage,
   but have not yet reached calibrated status (PDS4)\\
3 &3 (calibrated)&2&1A&RDR&Calibrated&2
  &Reduced Data Record (``calibrated'' in physical units, no resampling)\\
5 (yes, 5)&4 (resampled)&&1B&REFDR&Derived&3
  &Reformatted Data Record
   (mosaics or composite of several observing sessions,
   involving some level of data fusion)\\
5 &5 (derived)&3&2-5&DDR&Derived&4
  &Derived Data Record
   (result of data analysis, directly usable by other communities
   with no further processing)\\
6&6 (ancillary)&&&ANCDR&Derived&
  &Ancillary Data Record
   (extra data specifically supporting a data set,
   such as coordinates, geometry… but also dark currents, flat fields…) \\
\end{tabular}
\label{table:proclev}
\end{inlinetable}\endgroup

Notes:

\begin{itemize}
\item This table is a compilation of information from
      PSA, PDS4, and ObsCore documents
\item The PDS3 column corresponds to the PDS3/PSA PRODUCT\_TYPE keyword
\item Descriptions are extracted from PSA and PDS4 documentations,
      with comments.
\end{itemize}

\subsubsection{Target description}

\paragraph{target\_name}

The target\_name parameter identifies a target by name or ID. The
target may be any Solar System body, exoplanet, planetary sample, or
meteorite, plus in some cases astronomical objects or spacecraft. Any
other feature (craters, regions, atmospheric layers\dots) must be named
using the optional feature\_name parameter (see \ref{par:feature_name}). This parameter
can be multivalued only to describe several targets related to a granule
(e.g., with events). Alternative names of the same target must not be
listed here, but may be provided through the optional alt\_target\_name
parameter. In some rare cases no target name can be defined, so this
parameter can remain empty.

The best practice is to use the official designation of the target as
defined by IAU. This parameter is case sensitive (mixing lower/upper
cases) and all values must use the standard spelling and case; unusual
characters (such as intermediate spaces) are allowed, except quotes
and hashes (preferably changed to \_).
Data providers must be aware that services which do not expose the IAU
designations will not return answers to queries using them.
Conversely, users must be aware that some
data of interest might not be visible if they do not use the recommended
IAU nomenclature for planetary bodies. The quaero name
resolver\footnote{\url{https://ssp.imcce.fr/webservices/ssodnet/api/quaero/}}
from IMCCE may help data providers (as well as users) to handle multiple
denominations; it is available from the VESPA portal to support queries.

Concerning celestial objects (at fixed position, i.e., stars,
galaxies…) the name should be identifiable through
Simbad\footnote{\url{http://simbad.u-strasbg.fr/simbad/}}.

Other best practices are listed below:

\begin{itemize}
\item The Exoplanet Encyclopedia provides a nearly
complete list of currently known extrasolar planets:
\url{http://exoplanet.eu/index.php}
(also available as an EPN-TAP service)

\item Meteorite catalogues can be found here:\\
\url{http://www.nhm.ac.uk/research-curation/research/projects/metcat/search/indexsing.dsml}
\\and
\url{http://www.lpi.usra.edu/meteor/index.php}.

\item The catalog of lunar samples is available here:
\url{http://www.lpi.usra.edu/lunar/samples/}

\item Other planetary samples are listed in topical web sites,
e.g., samples from the Stardust mission are described here:\\
\url{http://curator.jsc.nasa.gov/stardust/catalog/}

\item Consortia such as the IGSN\footnote{\url{https://www.igsn.org}}
issue IDs for samples

\item Asteroids: Usage is to use preferably the name (if it exists) or
principal designation (the number is not used here, it can be included
in alt\_target\_name)

\item Comets: Usage is to use preferably the code and principal designation, e.g.,
P/2022 C2 or 1P for periodic comets, C/2022 E3 for non-periodic ones 
(discoverer names are ambiguous and can be included
in alt\_target\_name)

\item Meteors: the IAU Meteor Data Center assigns IDs to meteors and
meteor showers

\item Calibration targets: values can relate to existing names in a
given archive (e.g., the PSA contains values such as bias, checkout,
dark, flatfield, internal source…)
\end{itemize}

\textbf{\\}
\emph{Example TAP queries}:


\begin{verbatim}
SELECT TOP 1000 * FROM spectro_asteroids.epn_core
 WHERE (target_name LIKE '%Ceres%' OR target_name LIKE '%Vesta%')
 AND (ivo_hashlist_has(target_class, 'dwarf_planet') = 1 OR
     ivo_hashlist_has(target_class, 'asteroid') = 1)
\end{verbatim}

Will return data only from 1 Ceres or 4 Vesta.

The LIKE operator is used in this example to handle cases when 1) the name includes a
number, either `1 Ceres' or `(1) Ceres', which (although not recommended)
may occur in some services, 2) the special case of dwarf planets, which
may be tagged as asteroids, or as `dwarf\_planet\#asteroid' (recommended,
see below).

The usage of LIKE cannot be generalized to all target\_class values,
because of  `planet' which also responds to `dwarf\_planet' and `exoplanet'.
The ivo\_hashlist\_has function smoothly handles all values
of target\_class. Also beware that using LIKE on target\_name may generate false positives.

\textbf{\\}
\emph{Example}:

1P is the official IAU designation for comet Halley

\paragraph{target\_class}

The target\_class parameter identifies the type of the target. Solar
System bodies are defined without ambiguity by the couple target\_class
and target\_name. In other cases, targets may have no proper name
(i.e., samples), but the target\_class parameter must contain a value in
all cases. The possible values for target\_class are:

\begin{itemize}
\item asteroid
\item dwarf\_planet
\item planet
\item satellite
\item comet
\item exoplanet
\item interplanetary\_medium
\item sample
\item sky
\item spacecraft
\item spacejunk
\item star
\item calibration
\end{itemize}

Usage:

\begin{itemize}

\item Most Solar System bodies are expected to belong to a single target class,
and the pair of values is required to resolve homographies (such as Io).
However, classifications may evolve with time.

\item It is therefore good practice to use a hash-separated-list to
handle any ambiguity or evolution in target classes, such as dwarf
planets (dwarf\_planet\#asteroid) or transitional objects (comet\#asteroid).
This will help support queries by target\_class in particular.

\item If several target\_name values are provided for a granule,
several target\_class may be present as hash-separated values.

\item ``interplanetary\_medium'' refers in particular to interplanetary
dust observed in context (not to samples), or to simulations
(e.g., of the primordial nebula).
Details can be provided through target\_region.

\item ``sample'' refers to lunar or planetary samples, to meteorites,
but also to terrestrial samples, e.g., in laboratory studies.

\item ``satellite'' stands for natural satellites only --- artificial
satellites are handled though spacecraft or spacejunk.

\item ``star'' is used typically for calibration targets, and for the Sun.

\item ``sky'' should be used for all other celestial bodies,
usually referred to by their sky coordinates.
It also includes the Interstellar Medium.

\item ``calibration'' is used for observations only related to instrument
or signal calibration, including dark current, flat field, reference
sample (in lab), etc (use of ``calibration'' with planetary bodies is
left to data providers).

\item planetary rings are not considered a target class, but appear as
target\_region = ``ring'' with their planet indicated in target\_name.

\end{itemize}

\emph{Comment}:

All ``Types'' of objects used by the quaero resolver are included
in the EPNCore list: ``asteroid'', ``spacecraft'', ``comet'',
``exoplanet'', ``spacejunk'', ``satellite'', ``planet'', ``dwarf planet'',
``star''.\\
Additional EPNCore classes are: ``interplanetary\_medium'',
``sample'', ``sky'', ``calibration''.


\subsubsection{Axes}

EPNCore describes the data coverage along 8 main axes:
time, spectral, spatial (3 coordinates), and viewing geometry (3 angles).

Coverages along the time/space/spectral axes are described with a range
and a resolution and/or sampling step.

Each quantity is a set of 2 parameters providing min and max values. They
must both be present with the same value when min = max. Additional single
parameters provide extra information: spatial\_frame\_type, s\_region,
and the optional coverage parameter.

\paragraph{time (min/max)}

The time\_min and time\_max parameters provide the date and time of
acquisition in the observer frame.

The time parameters are always provided in UTC and formatted in Julian
Days (expressed in double precision). EPNCore uses standard JD to avoid
ambiguity with time origin (as opposed to ObsCore which uses Modified
JD). The use of double precision floats ensures an accuracy on the order
of 1 ms, which is considered sufficient for search purposes (the initial
accuracy is preserved in the data itself). A client front-end may expose
times formatted in a more convenient way for human users.

\textbf{\\}
\emph{Example TAP queries}:

\begin{description}
\item[Search data contained in a time range:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM spectro_asteroids.epn_core
 WHERE time_min > 2455197.5 AND time_max < 2455927.5
\end{verbatim}

\item[Search data described by a start time parameter:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM spectro_asteroids.epn_core
 WHERE time_min BETWEEN 2455197.5 AND 2455927.5
\end{verbatim}
\end{description}

Time range is, by default, provided in the observer frame (i.e., at the
observer location at that moment), which is almost always the native time
in the data. For instance, space-borne observations are usually documented
with spacecraft on-board time, which is expected here (provided as JD,
not as on-board clock timing). For other cases, the location where time
is measured must be provided through the time\_refposition parameter.

To support space-borne vs ground-based campaigns, multiple spacecraft
observations, or survey of periodic events, measurement times need to be
corrected for light path. Whenever comparisons are potentially involved,
the use of the target\_time\_min and target\_time\_max parameters is
recommended in addition to time\_min and time\_max to make this kind of
comparison simpler.

Non-compulsory parameters may be used to accommodate additional,
specially formatted time scales such as native on-board time for space
borne observations. The information of the time\_min and time\_max
parameters is however highly recommended for all observations,
as it is used by default to search data collections.

\paragraph{time\_sampling\_step (min/max)}

These parameters provide the sampling step in seconds for measurements
of dynamical phenomena, and for computations. This is the time between
2 successive measurements or data, which is mostly relevant when the
measurements are regularly spaced. This may also reflect an input
parameter, e.g., for simulations or ephemeris computations. This
parameter is intended to allow the user to search for time-resolved
observations of dynamic phenomena, but can also accommodate the
``repetition time'' for several types of instruments.

\paragraph{time\_exp (min/max)}

These parameters correspond to the integration time (or exposure
time) of measurements in seconds. They provide an estimate of the time
resolution for dynamical phenomena, as well as an indication of relative
S/N ratio inside a given data collection. This time is usually shorter than
the time\_sampling\_step if both are present. It provides the overall
integration time, i.e., individual exposure time $\times$ number of summed
frames when relevant.

\paragraph{spectral\_range (min/max)}

The spectral\_range parameters define the upper and lower bounds of the
spectral domain of the data. This quantity is conventionally expressed
on a frequency scale in Hertz, although the client front-end may propose
conversions to other units/scales. The spectral range and associated
parameters only apply to electromagnetic waves. See the optional
parameters from the particle spectroscopy extension for particle energy or mass detection.

Since this is the standard parameter to identify a spectral range, it
is recommended to fill it even for images obtained through a filter
(for instance, by giving the central wavelength $\pm$ FWHM/2,
or even just the central wavelength as both minimum and maximum,
which may already be enough to make the granule findable).
The SVO Filter Profile
Service\footnote{\url{http://svo2.cab.inta-csic.es/theory/fps3/}}
provides responses for many instrument filters; 
the corresponding link can be provided via datalink and
bandwidths can be retrieved easily with a python library:
\url{https://github.com/hover2pi/svo_filters}.

Care must be taken when computing spectral ranges from metadata given as
wavelength.  For instance, when the spectral range $\lambda_\mu$ is
given in micrometers, with the constants from sect.~\ref{sect:convs} one
would compute (notice the change of roles!)

\begin{eqnarray*}
\hbox{\texttt{spectral\_range\_min}} &=&
  2.99792458\cdot 10^{14}/\lambda_{\mu,\textrm{max}}\\
\hbox{\texttt{spectral\_range\_max}} &=&
  2.99792458\cdot 10^{14}/\lambda_{\mu,\textrm{min}}\\
\end{eqnarray*}

\paragraph{spectral\_sampling\_step (min/max)}

The spectral\_sampling\_step parameters provide the spectral separation
between the centers of two adjacent filters or channels. Similar to the
spectral\_range quantities, they are expressed on a frequency scale in Hz.

These parameters are most relevant for radio observations
(long wavelengths / low frequencies) with regular sampling.
They can also help distinguish between Nyqvist and sub-Nyqvist
sampling rates (together with resolution).

Again, care must be taken when converting sampling steps from
non-frequency metadata.  For example, when the spectral sampling step is
given in micrometers of wavelength,
$\Delta\lambda_\mu$, with the constants from
sect.~\ref{sect:convs} one would compute
$$\hbox{\texttt{spectral\_sampling\_step\_*}}
= 2.99792458\cdot10^{14}\Delta\lambda_\mu/\lambda_\mu^2.$$
For wavelengths in nanometers, $\lambda_{\textrm{nm}}$, this becomes
$$\hbox{\texttt{spectral\_sampling\_step\_*}}
= 2.99792458\cdot10^{11}\Delta\lambda_{\textrm{nm}}/
\lambda_{\textrm{nm}}^2.$$
Finally, for a wave number $u$ in $\textrm{cm}^{-1}$, the conversion is
$$\hbox{\texttt{spectral\_sampling\_step\_*}}  =
2.99792458\cdot10^{6}\Delta u$$

\paragraph{spectral\_resolution (min/max)}

The spectral\_resolution parameters provide the (dimensionless)
resolving power $\lambda/\Delta\lambda = \nu/\Delta\nu$.

These parameters are mostly intended to provide an order of magnitude,
e.g., to distinguish between Fourier spectrometers, grating spectrometers
or filter cameras, or between observations related to surfaces or
atmospheres. This is often most relevant for optical/infrared observations
(short wavelengths / high frequencies).

Note that when computing the spectral resolution using wavelengths,
minimum and maximum change roles, as in
\begin{eqnarray*}
\hbox{\texttt{spectral\_resolution\_min}}
&=& \lambda_\textrm{min} / \textrm{max}(\Delta\lambda)\\
\hbox{\texttt{spectral\_resolution\_max}}
&=& \lambda_\textrm{max} / \textrm{min}(\Delta\lambda)
\end{eqnarray*}

\paragraph{c1 (min/max)}

\paragraph{c2 (min/max)}
\vspace{-15pt}
\paragraph{c3 (min/max)}
\vspace{-15pt}
These parameters provide up to three spatial coordinates of the measured
target (note that these parameter names contain no underscore before min/max, in contrast with the other ones).
The coordinates depend on the spatial\_frame\_type parameter
defined below. All services must handle three spatial coordinates,
even if the third one is always set to NULL. Some coordinates are
measured along a circle and must handle 0-meridian crossing, therefore
min/max values are actually start/stop values defining the footprint. In
body-fixed coordinates, c1 is longitude and is always counted eastward;
c1min is therefore the westernmost longitude and c1max the easternmost
one; the opposite applies to Right Ascension on the sky. Note that the
c3 parameter is related to the observed area, relative to a reference
surface in most cases; the target distance (e.g., geocentric distance
for ground based observations, or spacecraft distance) is introduced by
the optional parameters  ``earth\_distance'' or ``target\_distance''.

\textbf{\\}
\emph{Example TAP queries}:

Requests on C1/C2 coordinates often involve comparisons between two
bounding boxes. Below are typical examples in body-fixed coordinates,
when poles are not included in the bounding box (note that this type of query
is more compact and more accurate if parameters s\_region or coverage are provided).
\begin{description}
\item[Increasing longitudes: data range intersects {[100, 200]}:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM vvex.epn_core
 WHERE ((c1min <= c1max AND c1min <= 200.0 AND c1max >= 100.0) OR
        (c1min > c1max AND (c1min <= 200.0 OR c1max >= 100.0)))
   AND c2max >= -20.0 AND c2min <= 20.0 AND spatial_frame_type = 'body'
\end{verbatim}

\item[0-crossing longitude range: data range intersects {[300, 20]}:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM vvex.epn_core
 WHERE (c1min <= 20.0 OR c1max >= 300.0 OR c1min > c1max)
   AND c2max >= -20.0 AND c2min <= 20.0 AND spatial_frame_type = 'body'
\end{verbatim}

\item[Increasing longitudes: data range is included in {[100, 200]}:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM vvex.epn_core
 WHERE c1min >= 100.0 AND c1max <= 200.0 AND c1min <= c1max
   AND c2max <= 20.0 AND c2min >= -20.0 AND spatial_frame_type = 'body'
\end{verbatim}

\item[0-crossing longitude range: data range is included in {[300, 20]}:]\mbox{}
\begin{verbatim}
SELECT TOP 100 * FROM vvex.epn_core
 WHERE ((c1min >= 300.0 AND c1max <= 20.0) OR
        (c1min >= 300.0 AND c1max >= 300.0) OR
        (c1min <= 20.0 AND c1max <= 20.0))
   AND c2max <= 20.0 AND c2min >= -20.0 AND spatial_frame_type = 'body'
\end{verbatim}
\end{description}

In order to make uniform requests possible, spatial coordinates provided
in the EPNCore table must be standardized. However, they can be provided
in several systems types, as defined by the spatial\_frame\_type
parameter. The native coordinate system used in the EPNCore table can
be described by parameters spatial\_coordinate\_description and
spatial\_origin. This is intended to provide this information
prior to loading the data, especially when several coordinate
systems are available in the same service. Descriptions for EPN-TAP
are provided in a separate document (see extension and vocabulary
page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under Planetary Coordinate
Systems).
Secondary coordinates can be introduced using additional parameters,
e.g., c1 and c2 ranges identify the visible region of a planetary
disk, while extra RA / Dec parameters provide location on the
sky at this moment, and subobserver\_longitude\_min/max and
subobserver\_latitude\_min/max provide the coordinates of the disk center.

A special case arises for images of complete planetary disks, i.e., most telescopic images.  
Providing a 180° wide bounding box is 
irrelevant and would add noise to most requests based on spatial coordinates. 
It is more efficient in this case to provide the coordinates of the disk center through 
parameters subobserver\_longitude\_min/max and subobserver\_latitude\_min/max 
(with the same value in the min/max terms) plus the orientation in the image plane through 
north\_pole\_position. A MOC coverage can be added to allow for quick searches (rather than 
a s\_region which hardly covers a complete hemisphere).

\paragraph{c1\_resol (min/max)}

\paragraph{c2\_resol (min/max)}
\vspace{-15pt}
\paragraph{c3\_resol (min/max)}
\vspace{-15pt}
These parameters provide a simple estimate of the resolution in the same
frame/units as c1/c2/c3. For instance, if spatial\_frame\_type =
`celestial', it can accommodate the FWHM of the PSF on the sky (in
degrees). The client front-end may propose more appropriate units to the
user, depending on context (e.g., angular resolution in mas, distance
in m\dots).

\paragraph{spatial\_frame\_type}

Provides the ``flavor'' of the coordinate system, which defines the nature
of the spatial coordinates (c1,c2,c3) in the EPNCore table and queries,
and the way they are defined. A value is always required (use ``none''
if not applicable). This may be different from the coordinate system associated to /
included in the data themselves. The reference frame itself is defined by
the spatial\_coordinate\_description parameter, and the frame center can
be specified using the spatial\_origin parameter in case of ambiguity.
The possible types are described below:

\begin{itemize}
\item \textbf{celestial}: 2D angles on the sky, i.e., right ascension
c1 and declination c2 plus possibly the heliocentric distance in c3 (in AU);
although this is a special case of a spherical frame, the order and
conventions are different. Right ascension is provided in degrees. ICRS
coordinates are assumed by default, but other frames may exist, e.g., HPC
(Helio-Projective Cartesian) is centered on the Sun; such frames are
identified from the spatial\_coordinate\_description parameter.
For ground-based observations, Earth distance may be provided in the
earth\_distance parameter (not in c3).

\item \textbf{body}: 2D angles in body-fixed frame: longitude c1 and
latitude c2 plus possibly altitude as c3. \\A planetocentric system with
eastward longitudes in the range (0,360)° is required for service
interoperability. IAU 2009 planetocentric convention
applies, in particular eastward longitudes and a north pole located on
the north side of the invariant plane of the Solar System for planets
and satellites.
Unless otherwise specified in spatial\_coordinate\_description,
this will be interpreted as the current IAU frame at the moment of access,
in particular for definition of the prime meridian \citep{2018CeMDA.130...22A}.
\\Parameter c3 is measured above the reference
ellipsoid, and can be <0 for interiors. Two other parameters are
available to provide other vertical scales if needed (radial\_distance
and altitude\_fromshape). \\Planetocentric rotating frames are defined
as spherical (rather than body).

\item \textbf{cartesian:} (x,y,z) as (c1,c2,c3).
This provides spatial coordinates  in km.

\item \textbf{spherical:} (r, theta, phi) as (c1,c2,c3), as
defined in ISO standard 80000-2:2009; r = radius; theta = zenith
angle/colatitude/inclination; phi = azimuth (E longitude). Angles are
provided in degrees. When related to the sky or tied to a solid body,
``celestial'' (with RA/Dec) or ``body'' (with E longitude/latitude)
frames must be used instead.

\item \textbf{cylindrical:} (r, theta, z) as (c1,c2,c3); r = radius in
km; theta = azimuth; z = height in km. The angle is provided in degrees.

\item \textbf{none:} to be used when no spatial frame is defined for
the data. This value is intended to prevent useless searches when space
coordinates are not defined.

\end{itemize}

This parameter, although related to the specific coordinate system in use,
is mostly intended to identify the nature of the coordinates provided in
the service table (e.g., angles versus distances). This parameter is
provided as a column of the EPNCore table to ensure it can be queried
through the basic TAP mechanism. Although it will in general remain
constant along the table for simple services, this parameter can vary from
granule to granule and a value must therefore be provided in any query
that includes spatial coordinates. Whenever additional coordinates are
provided, they must be stored in extra columns of the table. If several
different frames are mixed to provide the main coordinates, the use of
different granule\_gid may help clarify the situation. At any rate, easy
access to the data must be considered during the design of the service.

\paragraph{incidence (min/max)}

The incidence parameters define the upper and lower bounds of the
incidence angle range in the data (also known as Solar Zenith Angle).
This is always indicated in decimal degrees, and usually ranges from 0 to
90° (with 0° indicating the normal to the surface). Incidence and
emergence angles may be counted relative to the normal of the ellipsoid
model, or to the local normal (e.g., using a 3D shape model). In case
the two systems are included in the data, these parameters introduce the
values relative to the ellipsoid (local values may be provided through
non-compulsory parameters).

\paragraph{emergence (min/max)}

The emergence parameters define the upper and lower bounds of the
emergence, emission, or viewing angle range in the data. This is always
indicated in decimal degrees, and usually ranges from 0 to 90° (with
0° indicating the normal to the surface). Incidence and emergence angles
may be counted relative to the normal of the ellipsoid model, or to the
local normal (e.g., using a 3D shape model). In case the two systems
are included in the data, these parameters introduce the values relative
to the ellipsoid (local values may be provided through non-compulsory
parameters).

\paragraph{phase (min/max)}

The phase parameters define the upper and lower bounds of the phase
angle range in the data (i.e., $\textrm{scattering angle} - 180^\circ$, or
$\textrm{light source}-\textrm{target-observer angle}$.
It is always indicated in decimal degrees,
and may range from -180 to 180° (with 0° corresponding to opposition,
i.e., light source in the back of the observer). Negative values may
refer, e.g., to geometry before opposition, depending on context.
Phase ($\phi$), incidence $i$ and emergence $e$ are partly related:
\begin{displaymath}
  |i - e| < |\phi| < i + e
\end{displaymath}

If the azimuth angle $a$ is available instead of the phase angle,
the latter can be derived from knowledge of the three angles:
\begin{displaymath}
  \cos(\phi) = \cos(i) \cos(e) + \cos(a) \sin(i) \sin(e)
\end{displaymath}

\paragraph{s\_region}

This parameter introduces a footprint as a contour. The s\_region
parameter should be given for geolocalized data products in 2D, most
notably on the sky (using RA, Dec) or on planetary surfaces (using E
longitude, latitude) to communicate the geometry of a feature or an
observation footprint. This is a single parameter with no min/max
declinations. Coordinates are provided in the same reference system as
c1/c2 parameters, clients must therefore inspect spatial\_frame\_type
before interpreting such contours. Any type of contour that works with
ADQL's geometry operators (CONTAINS, INTERSECTS...) is legal here.

The coverage parameter introduces another type of footprint, with potential
extension to time coverage. When both are present, care must be taken
that they are consistent.

In the VOTable serialization the s\_region parameter is represented
as either an STC-S string value with xtype='adql:REGION' or a DALI
1.1-compliant numeric array value with xtype='point', 'circle' or
'polygon'.

\textbf{\\}
\emph{Implementation notes:}

Two syntaxes are possible:

1) The original ObsCore s\_region one (currently limited to polygons)
— a string with syntax: `\{(lon1,lat1), (lon2,lat2), … \}' (with
no quotes) where (lon1,lat1) = (10.d, 5d), character d included (it
stands for degrees). Pairs (lon1,lat1) must sample the contour in a
sequence provided in direct (counter-clockwise) sense as viewed from
the observer. Notice that the result of a TAP query is an STC-S string,
which has different format (as in ObsCore).

2) Modern DALI 1.1 geometries — a numeric array providing either a point
(`lon lat', with no quotes), a circle (`lon lat radius', with no quotes),
or a polygon (sequence of at least 3 `lon lat' pairs, with no quotes). For
polygons, pairs (lon lat) must sample the contour in a sequence provided
in direct (counter-clockwise) sense as viewed from the origin (when on
the sky) or from the observer (when on planets).

\subsubsection{Data origin}

\paragraph{instrument\_host\_name}

This parameter provides the name of the observatory, spacecraft, or
facility that performed the measurements. A hash-separated-list of host
names must be provided for integrated data sets. In the EPNCore table, usual
acronyms are preferred to full names to avoid long strings and related
errors (however, both values can be provided in the list). As a rule of thumb, 
instrument\_host\_name implies a location, and several levels can be 
provided together when relevant, e.g., space\_mission\#spacecraft or observatory\#telescope. 
The second value is recommended as it is more specific.
For lab measurements, this is typically the name of the facility. 
Simulations of observations from a spacecraft
may be identified by e.g., "simulation\#Cassini" so that the user looking for 
observations is informed that simulations also exist.


\textbf{\\}
An IVOA Note has been issued about  Observatory Facility Vocabulary
\footnote{\url{https://ivoa.net/documents/Notes/ObsFacilityWikidata/20231115/NOTE-ObsFacilityWikidata-1.0-20231115.pdf}}
and will eventually be used as a reference.
Reference lists that can be used in the meantime include:

\begin{itemize}
\item for ground-based observations, the list of IAU observatory
codes:\\
\url{http://www.minorplanetcenter.net/iau/lists/ObsCodesF.html}
\\However, this list is not intended to include all ground-based
observatories, and a complement still needs to be identified (including
e.g., radio telescopes).

\item a reasonably complete list of radio telescopes is available here:\\
\url{http://en.wikipedia.org/wiki/List_of_radio_telescopes}

\item the WiseRep list also
provides a  database of telescopes and instruments:\\
\url{https://wiserep.weizmann.ac.il/aux/telescopes}\\
\url{https://wiserep.weizmann.ac.il/aux/instruments}

\item Concerning space-borne data, the most complete list of
international planetary missions and orbital observatories is
found here (included in a complete list of space missions with ID):
\url{http://nssdc.gsfc.nasa.gov/nmc/}\\
Planetary missions are also listed here:
\url{http://nssdc.gsfc.nasa.gov/planetary/chronology.html}.

\item Alternatively, the PDS dictionary defines values
for many mission names:\\
\url{http://pds.nasa.gov/tools/dictionary.shtml}\\
Other mission and ground station names are supported by the SPICE system,
but only as ID codes:\\
\url{https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/naif_ids.html}
\end{itemize}

\paragraph{instrument\_name}

Identifies the instrument(s) that acquired the data.
A hash-separated-list of instruments must be provided
for integrated data products.
Service providers should include multiple values
for instrument name, e.g., complete name and usual acronym.
This will allow queries on either
``Visible Infrared Thermal Imaging Spectrometer'' or ``VIRTIS''
to produce the same reply.  
As a rule of thumb, instrument\_name implies one or more coverages 
(spatial, spectral, etc): for ground-based observations and lab measurements, 
this is typically the name of the instrument in use (not
the telescope or facility). Non-compulsory parameters are available to
provide more information about sensors, channels, instrument modes, etc.
Simulations of observations from a space experiment
may be identified by e.g., "express\_v3\#VIMS" (where the first is the name of the code)
so that the user looking for observations is informed that simulations also exist, in particular 
when a specific instrumental response is included.

\textbf{\\}
\emph{Example}:

\begin{verbatim}
Visible Infrared Thermal Imaging Spectrometer#VIRTIS
\end{verbatim}

An Observatory and Facility
Database\footnote{\url{https://voparis-wiki.obspm.fr/display/VES/Observatory+Facility+Database}}
is under study at IVOA, and will eventually be used as a reference.


The most complete ready-to-use list of international
planetary missions and orbital observatories is found here:
\url{http://nssdc.gsfc.nasa.gov/nmc/}

Instruments on board planetary missions in particular are listed here:\\
\url{http://nssdc.gsfc.nasa.gov/nmc/experimentSearch.do}

\subsubsection{Granule call-back info}

These parameters provide ancillary information for routine processing
after a query. These 4 parameters must always contain a value.
Dates are provided in ISO 8601 format.

\paragraph{service\_title}

The schema name of the service: it provides a unique acronym for the service/table, constant
throughout the service. It is intended to identify the source of the data in later stages, e.g., when
handling multiservice results. When
designing the service, care must therefore be taken to use a title not
already ascribed to another EPN-TAP service. Special/unusual characters
must be avoided (including \#, ?, etc). Other identifiers (ivoid…) may be used in a future version.

Existing EPNCore services can be listed from the registry:
\begin{verbatim}
select distinct(schema_name), table_utype
from rr.res_schema natural
join rr.res_table
where table_utype LIKE '%epn%'
\end{verbatim}


\paragraph{creation\_date}

Provides the date when the granule was introduced in the service.

\paragraph{modification\_date}

Provides the date when the granule was last updated.
This is intended to speed up mirroring between sites and to flag recalibrations.
When unknown or not relevant, the creation date is replicated here.

\paragraph{release\_date}

Provides the date when the granule becomes public.  This is
intended to support a proprietary period.
When unknown or not relevant, the creation date is replicated here.

% To ignore the following section, add 'Optional parameters' to IGNORED_SECTIONS
\subsection{Optional parameters}
\label{sect:optional}

Optional parameters are predefined parameters (with unit and UCD) which are available to
provide further information if needed.
This section describes optional parameters of general use,
while section \ref{sect:extensions} describes
parameters related to specific science fields.

\subsubsection{Data Access Reference}

If the data are not included in the table
(i.e., provided in separate files),
these 3 parameters must be present and contain a value. If alternative
formats are also provided, they must be described in other granules
with the same obs\_id and possibly different group ID, or via datalink.
Whenever the
data consists of a few scalar fields, these parameters are best replaced
by parameters providing the data itself in the table.  This makes them
usable in query constraints (e.g., mass, in a table providing the masses of
Solar System bodies).

\paragraph{access\_url}

The data of interest are often stored in a file, not in the table itself.
In this very usual case, the access\_url parameter provides
a complete path to the data products on the network, so that they are
accessible for download by plotting or processing tools.
This parameter links to a file, a web service (e.g., PlanetServer\_CRISM
service) or a script (e.g., Titan\_profiles service); in such cases,
the link must include the adequate arguments so that data is downloaded.
This parameter must link to the actual data, not to a file of
metadata nor a document (the datalink\_url parameter can be
used for this purpose).

\paragraph{access\_format}

Access\_format provides the format of the data file linked through
the access\_url parameter. \\The data may be stored under native
format, and no format conversion is required to set up an EPN-TAP
service; this field can therefore include reference to unusual
formats. However, VO-ready formats are required to take advantage
of visualization and processing in VO tools. Consistently with
ObsCore, possible values are MIME-types written in lower case;
the most common ones are listed on the extension and vocabulary
page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under Data Formats and MIME Types.

\paragraph{access\_estsize}

The access\_estsize field provides an order of magnitude of the size (in
kilobytes) of the file available via the corresponding URL. It is intended
to provide an indication that can help to tune download functionalities
in an application, depending on data volume and transfer bit rate.


\subsubsection{Miscellaneous file metadata}


\paragraph{thumbnail\_url}

The thumbnail\_url parameter contains the URL of a reduced version
of the data product used for quick-look purpose (e.g., a small jpeg
image, typically 200x200 pixels). This may be handy in the case of big
data files or unusual data formats, to facilitate data selection by the
user. EPN-TAP clients such as the VESPA portal use this thumbnail for
an on-line quick-look.  It therefore contributes significantly to a
service's accessibility.
Recommended formats include jpeg and png, which are handled easily
in a web browser. Larger or more elaborate previews must be provided as
independent granules and identified via a granule\_gid different from
the data.

\paragraph{file\_name}

The file\_name parameter introduces the name of the \emph{data}
file, with extension but no path information. In many data services,
the file name encodes the most relevant metadata and may be a
very handy access mechanism for specialists. In services providing
sets of files in a complicated directory tree (e.g., related to
a spacecraft operation plan), the file\_name parameter is a handy
key to perform automatic operations such as mirroring, pipeline
processing, etc.  A web service is available to retrieve a file from
the file\_name parameter in any EPN-TAP service (File grabbing interface
(fgi)\footnote{\url{https://voparis-wiki.obspm.fr/pages/viewpage.action?pageId=17236008}}).
Its use is therefore always recommended when data are provided in separate
files, i.e., not included in the table.\\
All file\_name values in the
EPNCore table are case sensitive and must reflect the filename of the
product provided through access\_url; for instance, if access\_url is
a link to a script converting an ascii file to VOTable, file\_name must
refer to the outcome of this script, in this case the VOTable.

\paragraph{access\_md5}

This parameter introduces a MD5 Hash for the file when available, to be used as a checksum.

\paragraph{accref}

Although not an EPNCore parameter, this name is reserved for internal
use and must not be used explicitly.

\paragraph{datalink\_url}

This parameter is used to provide extra accesses through a
datalink/SODA interface.
This interface can provide access, for instance, to previews,
documentation (filter characteristics, chemical analyses of samples, etc), 
related data products (such as progenitors,
calibration files, etc) and to cut-out or processing services on the data.

\textbf{\\}
\emph{Implementation note:}

Datalinks can be parameterized with input values
retrieved from the current granule at the time of ingestion.
When multiple EPN-TAP parameters are required to build a datalink,
they can be first concatenated in an extra parameter in the table
(often called \textbf{ds\_id}).

\subsubsection{Supplementary description}

\paragraph{bib\_reference}

The bib\_reference parameter introduces an individual bibliographic
reference at granule level. This provides the origin of the
data, e.g., if the resource is a compilation of data from various
origins. References are best provided as
bibcode\footnote{\url{http://adsabs.github.io/help/actions/bibcode}},
DOI, or arXiv identifier\footnote{\url{https://arxiv.org/help/arxiv_identifier}},
although other forms are acceptable.

\paragraph{publisher}

This parameter refers to the publisher of the \emph{data service}, who is not
necessarily at the origin of the data. Provided as a free format string.

\paragraph{processing\_level\_desc}

This parameter provides further details about processing\_level if needed, e.g.,
a specific encoding related to a data collection, or more details about partial
calibrations. Provided as a free format string.

\paragraph{internal\_reference}

The internal\_reference parameter can be used to identify granules
(or sets of granules) intimately related to the current one. e.g.,
in a service containing both observations and results of analysis of
observation sets, internal\_reference can be used to provide the set of
observations used to compute a result. This contains a hash-separated-list
of granule\_uid in the same service (which implies that those never
contain the \# character).\\This is specifically intended to provide
internal references in services which would otherwise need to be split
in several tables, and it must only be used as a last resort (clever
use of obs\_id and granule\_gid is usually more efficient).

\paragraph{external\_link}

The external\_link parameter can be used to provide extra information
that does not fit easily in the table, and is intended for human reading
only. This parameter must contain a single URL. This is typically an
extended discussion of a granule on a web site, which may include images,
tables, or other documents. For instance, the individual planet pages of
the Encyclopedia of exoplanets are linked with this parameter, as they
contain many links and sometimes web applets. Alternatively, the parameter
can provide a link to a web service related to this granule; for instance,
in the HRSC/MEx service (hrsc3nd) it displays a detailed view of the
image with zooming functions for quick examination at full resolution.

\paragraph{species}

The species parameter introduces the chemical species of interest in
simple data services. The formatting is very basic and simply uses the
standard formula in ascii, e.g., H2O for water, CO2 for carbon dioxide
or Fe for iron. This is one of the few query parameters provided in
case sensitive form, using the standard chemical notation. This format
can only accommodate atoms and simple molecular species, and does not
support isotopic variations.

An example application is related to atmospheric composition:
a table providing vertical profiles of gaseous species with altitude.
All columns are abundances and are described by the same measurement\_type
parameter. The use of the ``species'' parameter allows identifying the
various species and accessing the requested information. This of course
is restrained to simple cases.

If more elaborated compositional information must be included, the use of
parameter species\_inchikey is recommended. InChiKeys identify molecule,
including isotopes, but not the physical state or phase.

\paragraph{messenger}

This parameter is a generalization of waveband from VODataService
(used e.g., in ConeSearch and SSA). It provides a rough indication
of the spectral domain, e.g., when variable in a large archive. In
addition, values for messenger can describe particles other than
photons. Possible values are from the IVOA vocabulary (and case matters)
\url{http://www.ivoa.net/rdf/messenger}.

\paragraph{filter}

This parameter introduces the standard name of a filter used during
measurements. It is reserved for filters in imaging mode (no
grating/grism \#, etc). There is no predefined list, because of the large
variety of possible denominations, but the best practice is to use a short
and accurate ID. This VO service provides an extended list of references:
\url{http://svo2.cab.inta-csic.es/svo/theory/fps3/}

This parameter is intended to document the results of a search, rather than
a search parameter. Therefore, it is recommended to also provide the bandwidth 
via the spectral\_range\_min/max parameters --- this
is the only way to make filter imaging easily searchable.

\paragraph{alt\_target\_name}

This parameter introduces alternative names of the target, especially
when they are more commonly used than the official IAU one (e.g., Halley vs 1P).

A frequent usage is to store a hash-separated-list of all alternative
names for small bodies to avoid ambiguities (e.g., for asteroids: name,
number, principal and provisional designations). Although this situation
never occurs for small bodies, care must be taken to replace possible \#
characters by \_ in target names (e.g., for samples).

\paragraph{feature\_name}
\label{par:feature_name}

Introduces a supplementary name to provide more details
about the observed target. It is intended to
accommodate a local name (crater, surface feature, region…)
whereas target\_name is reserved to identify the whole body
(Mars, Moon, Ceres…). Use of official features names defined by IAU
(\url{http://planetarynames.wr.usgs.gov/})
is recommended when relevant.

\paragraph{target\_region}

Specifies a \emph{type} of region on the target. This parameter
only introduces generic regions (e.g., atmospheric layer, internal
structure…), not specific local names which must be handled using the
feature\_name parameter.

Values should be selected from the IVOA
rendition of the Unified Astronomy Thesaurus:
\url{http://www.ivoa.net/rdf/uat}

The UAT can be completed with new values if required. 
Older sources (some of them may be integrated in the UAT) include:

\begin{itemize}
\item IVOA thesaurus:
      \url{http://www.ivoa.net/rdf/Vocabularies/vocabularies-20091007/IVOAT/}
\item IAU thesaurus:
      \url{http://www.vocabularyserver.com/trex/en/}
\item Spase dictionary \url{http://www.spase-group.org/}
\end{itemize}

\textbf{\\}
\emph{Example}:

\emph{``atmosphere'', ``surface'', ``ionosphere'', ``ring'', ``solar-wind''}\\
The same values can be given in the subject keywords of the service's registry record.

\paragraph{coverage}

This parameter introduces a footprint as a MOC (healpix-based).
It is intended to support space/time coverages, most notably on the sky
(assuming RA, Dec coordinates) or on planetary surfaces (assuming
E longitude, latitude). This is a single parameter with no associated min/max
parameters. It must contain a MOC 2.0 ascii string (MOC or STMOC).
The result of the query must have xtype = ``moc'' (or possibly ``stmoc'' or equivalent in future standards)
for proper handling in TAP.

The coverage parameter may appear together with s\_region, which introduces
a simpler type of footprint (2D contour). Coverage has precedence over
s\_region. When both are present, care must be taken that they are
consistent.

\subsubsection{Description of coordinate frame}

\paragraph{spatial\_coordinate\_description}

\paragraph{spatial\_origin}
\vspace{-15pt}
These two parameters provide a description of the spatial frame in use,
depending on the spatial\_frame\_type parameter. Both parameters relate
to the coordinates provided in the EPNCore table, not necessarily to
those included in the data products.

Spatial\_coordinate\_description provides an acronym of the
Coordinate Reference System as discussed in the extension and vocabulary
page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under Planetary Coordinate Systems.
For body-fixed frames, IAU/SPICE/WMS strings such as IAU2020:49900 are
eligible --- in this case, the final 00 which stands for planetocentric
E-handed is the only valid option (refers to EPN-TAP standard on c1/c2
coordinates). A detailed description of body-fixed system is available here: \url{http://voparis-vespa-crs.obspm.fr:8080}
 If absent the current IAU coordinate system is assumed,
depending on context.

Spatial\_origin may be used to identify frame center
in specific situations, using either target\_name
(referring to target center) or the IVOA vocabulary
(\url{http://www.ivoa.net/rdf/refposition}).
Other values may be used, e.g., to introduce specific geometries for
simulations.

\textbf{\\}
\emph{Examples}:

\begin{verbatim}
spatial_coordinate_description: ICRS, IAU_MARS, IAU2000:49900
spatial_origin: Geocenter, Mars, (spacecraft)
\end{verbatim}


Spatial\_coordinate\_description and an epoch derived from time\_min/max
can be used to feed the COOSYS element of VOTable 1.4 when its value
is constant throughout the table (notice that most EPN-TAP coordinate
frames are not standard values in this vocabulary at the time of writing):

\begin{verbatim}
<COOSYS ID="system" epoch="<epoch>" system="<spatial_coordinate_description>"/>
\end{verbatim}

\paragraph{time\_refposition}

Indicates where the time is measured, which can be a planet or a
spacecraft — this does not handle time zones on Earth. This knowledge
is required to cross-correlate event-based observations, in particular
to indicate light-path differences. It applies to the time\_min and
time\_max parameters (while target\_time\_min/max always refer to the
target in the FoV). If this parameter provides no value, time is expected
to be provided in the observer frame (related to instrument\_host\_name),
which is not necessarily fixed in the Solar System.

Values for time\_refposition may specify a target name (referring
to target center) or spacecraft name, or use the IVOA vocabulary
(\url{http://www.ivoa.net/rdf/refposition})
including future versions of the hierarchy proposed at
\url{https://wiki.ivoa.net/internal/IVOA/InterOpMay2019TDIG/topocenter.pdf}.

\textbf{\\}
\emph{Example}:

\begin{verbatim}
Geocenter, (solar system bodies), (spacecraft)
\end{verbatim}

\paragraph{time\_scale}

Provides the time scale applying to time\_min and time\_max parameters.
UTC is assumed when no value is provided, since this
is the expected value in most observational data services.
Services using different time scales must declare them in this column
using identifiers from the IVOA timescale
vocabulary\footnote{\url{http://www.ivoa.net/rdf/timescale}}, amending
that if necessary. The typical time scale for predicted events is TDB.

Both time\_scale and time\_refposition can be used to feed the TIMESYS
element of VOTable 1.4 when their values are constant throughout the
table (this is best avoided otherwise, e.g., when grouping coordinated
observations from various locations in the Solar System):

\begin{verbatim}
<TIMESYS ID="time_frame" refposition="<time_refposition>"
         timeorigin="JD-origin" timescale="<time_scale>"/>
\end{verbatim}

\subsubsection{Target configuration and observing geometry}

The next pairs of parameters provide additional location in time and
space, and require min/max values. They are independent and can appear
separately:

\paragraph{solar\_longitude (min/max)}

Solar longitude (a.k.a. heliocentric longitude, or ecliptic longitude of
the Sun, traditionally noted Ls) is the Sun-Planet vector angle counted
from the planet position at northern hemisphere spring equinox. It provides a
measurement of season.

Ls = 90° corresponds to the northern summer solstice, Ls = 180°
to the northern autumn equinox, and Ls = -90° to the northern winter
solstice. Although it is most usually applied to Mars and Titan (using
Saturn's Ls), this notion can be enlarged to any planetary body without
ambiguity.

This should not be confused with the true anomaly of the body (which
is the same angle counted from the perihelion position), nor with the
longitude of the subsolar point (see below).

\paragraph{local\_time (min/max)}

Provide the local time at the observed area. These parameters are
provided in unit of target rotation divided by 24 and are measured from
local midnight, i.e., in decimal (local) hours (range from 0 to 24,
must increase with time at a given location).

\paragraph{target\_distance (min/max)}

The target\_distance parameters introduce the distance of the observer
to the observed area (in km) along the line of sight. This is mostly
intended for space borne data, where it provides the spacecraft-target
distance in km. For ground-based observations the earth\_distance\_min/max
parameters should be used instead (in AU).

\paragraph{target\_time (min/max)}

The target\_time parameters introduce the time measured in UTC scale
at the target. This is intended to directly correlate simultaneous
observations such as ground-based support and space-borne observations,
or multi-spacecraft campaigns. Values are given as TIMESTAMP.

\paragraph{earth\_distance (min/max)}

\paragraph{sun\_distance (min/max)}
\vspace{-15pt}
These two parameters provide the corresponding distance of Earth or Sun
to the target at the time of observation (in AU). When the target is the
Sun or Earth, use the target\_distance\_min/max parameters to provide
the distance to the observer.

\paragraph{subobserver\_longitude (min/max)}

\paragraph{subobserver\_latitude (min/max)}
\vspace{-15pt}
Provide coordinates of sub-observer point, in particular sub-Earth
point (disk center) or central meridian for ground-based observations
(this is different from the FoV location which is provided in c1/c2
parameters). The min/max pair is required to support long exposures
related to time series, especially on giant planets to test target
attitude.

\paragraph{subsolar\_longitude (min/max)}

\paragraph{subsolar\_latitude (min/max)}
\vspace{-15pt}
Provide coordinates of sub-solar point, especially for disk images.
The min/max pair is required to support long exposures
related to time series.

\paragraph{ra, dec}

Sky coordinates of the target can be provided in addition to standard
coordinates, in which case they must be stored in these parameters.
This may for instance document the location of a planet
in a celestial image,
while the main coordinates c1/c2 are used to provide the observed area as
longitude and latitude. ICRS coordinate system is assumed; right ascension
is provided in degrees (similar to ObsCore). RA and DEC parameters are
interpreted correctly by most VO tools, therefore no min/max variations
are allowed to maintain compatibility with existing software.

\subsubsection{Vertical scales on planets}

In body-fixed frame, parameters c3min/max, if present, introduce a
vertical range counted from a reference surface, typically the reference
ellipsoid for the current target. \\

Two other parameter pairs can be used provide different vertical
scales, and must be considered for atmosphere-related services when
available/relevant:

\paragraph{radial\_distance (min/max)}

Distance of observed area (at c1/c2) from body center, measured in km.
Not to be confused with target\_distance
(which provides the distance from observer to observed area).

\paragraph{altitude\_fromshape (min/max)}

Altitude of observed area (at c1/c2) above local surface, measured in km.
The local surface is provided by a DTM or a shape model.
This parameter typically provides the height in the atmosphere.

Parameter c3 can be used to select services/data in a given altitude
range above the ellipsoid, while radial\_distance and altitude\_fromshape
provide other convenient vertical scales to compare observations from
various origins. This use of c3min/max also applies to planetary interiors
(c3 is then <0) and measurements at high altitude/distance.

% To ignore the following section, add 'Extensions' to IGNORED_SECTIONS
\subsection{Extensions}
\label{sect:extensions}

EPN-TAP extensions are living projects intended to support data services in new fields as they become available. As such, they are supported outside of this document and can be completed with additional parameters in the future, following agreement between data providers and the editors of this document.

Extensions are maintained on an external web page with a Permanent ID:
\url{https://hdl.handle.net/21.15110/epn_tap_extensions} (PID provided by EUDAT/B2HANDLE).

The parameters listed in this section have however been agreed upon, and
can be considered as part of the EPN-TAP standard. Parameters given here have
fixed names, units, and UCDs.  Extension pages cannot override
them.  Extension pages can, however, change the recommended
descriptions (which are non-normative anyway), and they can
deprecate parameters given here.  Hence, data providers intending
to use parameters discussed in this section should inspect the
corresponding extension pages before adopting any of these
parameters.
Parameters from extensions can be used independently, like the generic optional parameters
described in section \ref{sect:optional}.


\subsubsection{Particle spectroscopy extension}

These parameters are related to the spectral distribution of particles
only -- for electro-magnetic waves, the spectral\_* parameters apply.

When used, these parameters define an extra axis and must all be present.
This set defines an additional axis for particle energy,
all with min/max values.

\paragraph{particle\_spectral\_type}

The particle\_spectral\_type parameter specifies the type of axis in use:
either `energy' (provided in eV), `mass' (in amu), or `mass/charge'
(in amu/qe).

\paragraph{particle\_spectral\_range (min/max)}

The particle\_spectral\_range parameters define the upper and
lower bounds of the spectral domain for particles. Depending on the
particle\_spectral\_type parameter, this quantity is expressed on an
energy, mass, or mass/charge scale, with respective units eV, amu,
or amu/qe.

\paragraph{particle\_spectral\_sampling\_step (min/max)}

The particle\_spectral\_sampling\_step parameters provide the
spectral separation between measurements, in the same scale and unit as
particle\_spectral\_range.\\
This parameter is mostly intended to provide an order of magnitude.

\paragraph{particle\_spectral\_resolution (min/max)}

The particle\_spectral\_resolution parameters correspond to the actual
resolution of the measurements, and are provided in the same scale and
unit as particle\_spectral\_range. \\
This parameter is mostly intended to provide an order of magnitude.

\subsubsection{Solar System Objects extension}

Most services providing descriptions of solar system objects contain
no observation files (only inferred properties).
Dedicated parameters are defined for the most common quantities.

\paragraph{mean\_radius, equatorial\_radius, polar\_radius}

These parameters are used to provide solar system object sizes (in km)

\paragraph{diameter}

Target diameter, or equivalent diameter for binary objects (in km)

\paragraph{mass}

Solar system object mass (in kg)

\paragraph{sidereal\_rotation\_period}

Solar system sidereal rotation period (in hour)

\paragraph{semi\_major\_axis, inclination, eccentricity, long\_asc, arg\_perihel, mean\_anomaly}

Provide the standard orbital parameters (distance in AU, angles in degrees)

\paragraph{epoch}

Provides a date of interest in JD

\paragraph{magnitude, flux, albedo}
Provide values of respective quantities (flux in mJy).


\textbf{\\}When target\_class = asteroid, dwarf\_planet or comet,
the following parameters can be used:

\paragraph{dynamical\_class}

introduces the class of small body, from an enumerated list.
The draft list includes: TNO, MBA, NEO, OCC (Oort Cloud comet),
JFC (Jupiter family comet), Centaur

See the extension and vocabulary page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under Small bodies sub-types.

\paragraph{dynamical\_type}

introduces a subdivision of the above, from an enumerated list.
It currently includes:

\begin{itemize}
\item NEO: Atira, Aten, Apollo, Amor (complete)

\item TNO (complete, but values may be adjusted):
res 2:5 , res 1:2,
Plutino, Hot classical, Cold classical, Scattered disk object,
Detached object, Inner Oort object
\end{itemize}

See the extension and vocabulary page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under Small bodies sub-types.

\paragraph{taxonomy\_code}
provides taxonomy codes for small bodies, typically related to spectral properties.

\subsubsection{Maps}

It is important to specify dataproduct\_type = ``ma'' to introduce planetary maps (rather than ``im''). 
The reason is that global maps respond to all queries on spatial coordinates and therefore 
add noise to the answers of such queries. Specifying also a dataproduct\_type will 
help clarify such answers.

\paragraph{map\_projection}

Provides map projection description (preferably as FITS name or code)
or parameters as a free string — for instance, several services use
this to store WKT or PROJ parameters as listed here:  \url{http://voparis-vespa-crs.obspm.fr:8080}. 
This refers to the data, not necessarily
to the spatial coordinates in the table (which have to be east-handed).

\paragraph{map\_height, map\_width}

These parameters give the number of pixels along the two axes of a raster map.
This specification does not constrain the orientation of such maps,
and hence 'width' and 'height' do not correspond to physical directions.

\paragraph{pixelscale (min/max)}

Pixel size at the target (usually at surface), in km/pixel.

\paragraph{map\_scale}
A string providing scale as a ratio (e.g., ``1:50000'').

\subsubsection{Contributive works}

These parameters are intended to specify the data origin in services
compiling amateur data, detection networks, experimental facilities,
or any service distributing data provided by multiple sources.

\paragraph{observer\_name, observer\_id, observer\_code}

Provide the name, ID and possibly internal code of the observer.
Name is provided as free text.

\paragraph{observer\_institute, observer\_country}

Provide the affiliation and country of residence of the observer. Use of ISO 3166 country codes is recommended. This is mostly intended for amateur or pro-am contributions.

\paragraph{observer\_location, observer\_lon, observer\_lat}

Give broad location and geographic position of the observer or telescope.
observer\_location can be used when the exact location cannot be released
(e.g., for small telescopes).

\paragraph{original\_publisher}
Services compiling data from many sources
can use this parameter to refer to the source of the data


\paragraph{Parameters from other extensions}

Parameters from other extensions may be helpful in this context:

The\textbf{ \textbf{data\_calibration\_desc}} parameter from
the spectroscopy extension can be used to provide information on
post-processing (this is preferred over a parameter named ``comment'')

\textbf{producer\_name, }\textbf{producer\_institute }provide reference
to who produced the data, especially for experimental data services

\subsubsection{Experimental spectroscopy}

Specific \textbf{*\_desc} parameters describe the sample and the
experimental setup. Although optional, they are important to provide the
context. They introduce free descriptive strings which are not intended
as search parameters.

\paragraph{producer\_name, producer\_institute}

Provide reference to who measured the sample, as free text.

\paragraph{sample\_id}

Additional identifier of the sample, e.g., a specific fraction of a meteorite
(in addition to target\_name).
Intended to refer to a pre-existing catalogue of a collection,
will therefore contain a name/ID mainly for local use.

\paragraph{sample\_classification}

Provides composition as group, class, sub-class, etc, of sample,
concatenated in a hash-separated-list with no particular order. It should include the specification ``meteorite''
plus the meteorite type when applicable, as well as description of main mixtures ingredients.
Meteorite types can be provided as in \citep{Krot:2005mz} or equivalent. Dana \citep{dana:1997}
or Struntz \citep{strunz2001} classification tags can be used for minerals. To reduce the likelihood
of false positives, minor and trace components must not be included in sample\_classification.

Examples below are taken from the PDS\_speclib service:
\begin{bigdescription}
\item[Terrestrial mineral:]
 natural\#solid\#earth\#mineral\#unclassified\#nesosilicate\#unclassified\#olivine
\item[Lunar sample:]
 natural\#solid\#moon\#rock\#unclassified\#igneous\#unclassified\#pyroxene
\item[Martian meteorite:]
 natural\#solid\#mars\#rock\#unclassified\#unclassified\#unclassified\#unclassified\#meteorite\#snc
\end{bigdescription}

\paragraph{\textbf{species\_inchikey} }

Provides an accurate machine-oriented description of species involved,
as per IUPAC standard \citep{heller2015}. InChiKeys are fixed-length strings
which do not include \#, and are therefore consistent with the
hash-separated-list syntax.

\paragraph{grain\_size (min/max)}

Provide the particle size range in µm. A very large value (eg, >1000
µm) can be used locally in a service to identify bulk material.
This is really \emph{grain}\_size, since \emph{particle}
is reserved for elementary particle spectroscopy.

\paragraph{azimuth (min/max)}

Provides the azimuth angle in degrees --- see if negative values of angles
can have a special meaning (also for phase angle)

\paragraph{pressure, temperature}

Provide experimental conditions, in bar and K. Although it is not recommended
by the IAU, the unit bar is accepted for pressure in this context, as it refers
to terrestrial laboratory conditions.

\paragraph{sample\_desc}

Free string describing the sample, its origin,
and possibly its preparation

\paragraph{setup\_desc}

Free string describing the experimental setup if
needed --- this may include the aperture (size of sample measured).

\paragraph{data\_calibration\_desc}

Free string describing data post-processing / calibration.

\paragraph{geometry\_type}

Describes the geometry for spectral measurements, from an enumerated list.
Possible values are maintained on the extension and vocabulary page
(\url{https://hdl.handle.net/21.15110/epn_tap_extensions})  under Lab spectroscopy extension.
Possible values currently include:

\begin{itemize}
\item direct (therefore in emission)
\item specular
\item bidirectional
\item directional-conical
\item conical-directional
\item biconical
\item directional-hemispherical
\item conical-hemispherical
\item hemispherical-directional
\item hemispherical-conical
\item bihemispherical
\item directional
\item conical
\item hemispherical
\item other geometry
\item unknown
\end{itemize}

\paragraph{spectrum\_type}

Explicitly provides the type of spectral measurement, from an enumerated
list --- this is where `radiance factor', `reflectance', `reflectance
factor', etc, are defined. The purpose is to give a precise description
of complex measurements independently from UCDs, which are not expected
to reach this level of description.

Possible values and corresponding UCDs are maintained on the extension and
vocabulary page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions})
under Lab spectroscopy extension. UCDs appear both under
measurement\_type and in the data files.


\paragraph{measurement\_atmosphere}

Provides description of experimental conditions as a free string.
Measurements under vacuum are indicated here with the word `vacuum'.

\paragraph{Use of general parameters}

When used with the lab spectroscopy extension, some general parameters
need special interpretation:

\textbf{thumbnail\_url} Provides a link to a small spectral plot.
Caution should be taken to maintain minimal readability in the small format
used in the VESPA portal. Larger plots can be included as separate granules
(previews).

\textbf{datalink\_url} External documents are often available to provide
extra information in this context, e.g., chemical analysis or a descriptive
image of the sample. Such documents can be considered an extension of the
table for the current granule, as opposed to other data products which
\emph{must} be defined as different granules/rows. The best solution
identified consists of providing such links via Datalink.

\textbf{target\_class} = `sample', constant.

\textbf{target\_name} provides the name or ID of the sample.  A value
is mandatory in this case. It introduces the name of a meteorite or
lunar sample when applicable. Various parts of the same sample can be
indicated and described in sample\_desc (such as ``Location A'', etc)
or in sample\_id.

\textbf{measurement\_type} provides the type of measurement/scale as a UCD
(e.g., REFF, I\_over\_F, etc…), and is completed by \textbf{spectrum\_type}
which is expected to be more accurate in general.

\textbf{original\_publisher} (from the Contributive work extension) may be used to identify a source database
in a collective service such as SSHADE.


\subsubsection{APIS extension}

A specific extension has been designed for compatibility with the
APIS service, so that all services in the field of planetary aurorae
can be queried together and consistently.
This extension contains a set of nearly 25 specific parameters
providing ephemeris and configuration quantities, which are listed on the
extension and vocabulary page (\url{https://hdl.handle.net/21.15110/epn_tap_extensions}) under APIS extension.

Some of the parameters defined for APIS are of more general interest and are intended to describe
datasets acquired as part of calls for proposals on large observatories or facilities.  
This list has been completed with parameters from other such situations, and is adapted to services  
distributing data from observational campaigns. 

\textbf{obs\_mode, detector\_name, opt\_elem, instrument\_type} --- relate to instrument characteristics

\textbf{proposal\_id, proposal\_pi, proposal\_title, campaign} --- relate to the original proposal

\textbf{proposal\_target\_name, target\_description } --- information about the target in the original proposal or catalogue (especially from the CAOM model used e.g., by HST archives)

\textbf{north\_pole\_position, target\_primary\_hemisphere,
target\_secondary\_hemisphere} --- describe target geometric configuration

\textbf{target\_apparent\_radius, orientation, platesc} --- describe size, image orientation, and scale on the sky

\textbf{acquisition\_ID, measurement\_unit} --- provides sequencing and data unit


\subsubsection{Events}


VOEvents \citep{2006ivoa.spec.1101S} can be archived in EPN-TAP tables.
The following extra parameters are available to complete their metadata:

\paragraph{event\_type}

Provides a type of event from a pre-defined list.
Possible values include:

\begin{itemize}
\item meteor\_shower
\item fireball
\item lunar\_flash
\item comet\_tail\_crossing
\end{itemize}

A more complete list of values will be maintained separately.

\paragraph{event\_status}

Following the VOevent standard, this can be:

\begin{itemize}
\item prediction
\item observation
\item utility (e.g., local event related to an instrument,
      like a change of detector)
\end{itemize}

\paragraph{event\_cite}

Following the VOevent standard, this can be:

\begin{itemize}
\item followup
\item supersedes
\item retraction (an alternative is to update the event lists)
\end{itemize}


\paragraph{Use of general parameters}

\textbf{access\_url} is expected to link to a VOevent file with
\textbf{dataproduct\_type} = ev

\textbf{access\_format} = text/xml (for broad identification) or =
application/x-voevent+xml

\textbf{instrument\_host\_name}, \textbf{instrument\_name} For
VOEvents that are actually predictions, use instrument\_host\_name = ``simulation''
and instrument\_name = reference of code used, including version number.

\textbf{target\_name} groups all targets in a hash-separated-list
(e.g., Sun\#Earth)

\textbf{obs\_id} is identical for related events

\subsubsection{Other extensions}

Other extensions will be defined by topical working groups.
They will be maintained separately to complement the present document, and linked on the extension web page, with Permanent ID: \url{https://hdl.handle.net/21.15110/epn_tap_extensions} (PID provided by EUDAT/B2HANDLE).

Extensions can be derived from independent Data Models,
e.g., for exoplanets.



% /GENERATED

\clearpage
\begin{landscape}
\section{EPNCore Table}
\label{sect:epntable}

% GENERATED: python3 parse_source.py columntable
\begingroup\scriptsize\begin{longtable}{p{4cm}p{1.6cm}p{1cm}p{8.2cm}p{3.5cm}}
\sptablerule
\textbf{Parameter name}&\textbf{Type}&\textbf{Unit}&\textbf{Description}&\textbf{UCD}\\\sptablerule\endfirsthead
\sptablerule
\textbf{Name}&\textbf{Type}&\textbf{Unit}&\textbf{Description}&\textbf{UCD}\\\sptablerule\endhead
\multicolumn{5}{c}{\vrule width 0pt height 20pt depth 12pt \textbf{\textbf{EPNCore mandatory parameters} (Must be present, possibly empty)\textbf{ (bold face: a value is required)}}}\\
\textbf{granule\_uid}&Text&&Unique ID in data service.&\ucd{meta.id}\\
\textbf{granule\_gid}&Text&&Common to granules of same type&\ucd{meta.id}\\
\textbf{obs\_id}&Text&&Associates granules derived from the same data&\ucd{meta.id;obs}\\
\textbf{dataproduct\_type}&Text&&Organization of the data product, from enumerated list&\ucd{meta.code.class}\\
measurement\_type&Text&&UCD(s) defining the data&\ucd{meta.ucd}\\
processing\_level&Integer&&Dataset-related encoding, or simplified CODMAC calibration level&\ucd{meta.calibLevel}\\
target\_name&Text&&Standard IAU name of target (must match target\_class), case sensitive.&\ucd{meta.id;src}\\
\textbf{target\_class}&Text&&Type of target, from enumerated list&\ucd{src.class}\\
time\_min&Double&d&Start time (in JD). UTC measured at time\_refposition location (default is observer's frame)&\ucd{time.start;obs}\\
time\_max&Double&d&Stop time (in JD). UTC measured at time\_refposition location (default is observer's frame)&\ucd{time.end;obs}\\
time\_sampling\_step\_min&Float&s&Min time sampling step&\ucd{time.resolution;stat.min}\\
time\_sampling\_step\_max&Float&s&Max time sampling step&\ucd{time.resolution;stat.max}\\
time\_exp\_min&Float&s&Min integration time&\ucd{time.duration;obs.exposure;stat.min}\\
time\_exp\_max&Float&s&Max integration time&\ucd{time.duration;obs.exposure;stat.max}\\
spectral\_range\_min&Float&Hz&Min spectral range (as frequency)&\ucd{em.freq;stat.min}\\
spectral\_range\_max&Float&Hz&Max spectral range (as frequency)&\ucd{em.freq;stat.max}\\
spectral\_sampling\_step\_min&Float&Hz&Min spectral sampling step&\ucd{em.freq;spect.binSize;stat.min}\\
spectral\_sampling\_step\_max&Float&Hz&Max spectral sampling step&\ucd{em.freq;spect.binSize;stat.max}\\
spectral\_resolution\_min&Float&&Min spectral resolution (resolving power)&\ucd{spect.resolution;stat.min}\\
spectral\_resolution\_max&Float&&Max spectral resolution (resolving power)&\ucd{spect.resolution;stat.max}\\
c1min&Float&Note~\ref{atn-1}&Min of first coordinate, depends on the frame.&see table below\\
c1max&Float&Note~\ref{atn-1}&Max of first coordinate, depends on the frame&\\
c2min&Float&Note~\ref{atn-1}&Min of second coordinate, depends on the frame.&\\
c2max&Float&Note~\ref{atn-1}&Max of second coordinate, depends on the frame&\\
c3min&Float&Note~\ref{atn-1}&Min of third coordinate&\\
c3max&Float&Note~\ref{atn-1}&Max of third coordinate&\\
s\_region&Text&Note~\ref{atn-3}&ObsCore-like footprint in 2D (if spatial\_frame\_type = celestial or body)&\ucd{pos.outline;obs.field}\\
c1\_resol\_min&Float&Note~\ref{atn-2}&Min resolution in first coordinate&Note~\ref{atn-2}\\
c1\_resol\_max&Float&Note~\ref{atn-2}&Max resolution in first coordinate&Note~\ref{atn-2}\\
c2\_resol\_min&Float&Note~\ref{atn-2}&Min resolution in second coordinate&Note~\ref{atn-2}\\
c2\_resol\_max&Float&Note~\ref{atn-2}&Max resolution in second coordinate&Note~\ref{atn-2}\\
c3\_resol\_min&Float&Note~\ref{atn-2}&Min resolution in third coordinate&Note~\ref{atn-2}\\
c3\_resol\_max&Float&Note~\ref{atn-2}&Max resolution in third coordinate&Note~\ref{atn-2}\\
\textbf{spatial\_frame\_type}&Text&Note~\ref{atn-1}&Flavor of coordinate system, defines the nature of coordinates. From enumerated list. Use ``none'' if undefined.&\ucd{meta.code.class;pos.frame}\\
incidence\_min&Float&deg&Min incidence angle (solar zenithal angle)&\ucd{pos.incidenceAng;stat.min}\\
incidence\_max&Float&deg&Max incidence angle (solar zenithal angle)&\ucd{pos.incidenceAng;stat.max}\\
emergence\_min&Float&deg&Min emergence angle&\ucd{pos.emergenceAng;stat.min}\\
emergence\_max&Float&deg&Max emergence angle&\ucd{pos.emergenceAng;stat.max}\\
phase\_min&Float&deg&Min phase angle&\ucd{pos.phaseAng;stat.min}\\
phase\_max&Float&deg&Max phase angle&\ucd{pos.phaseAng;stat.max}\\
instrument\_host\_name&Text&&Standard name of the observatory or spacecraft&\ucd{meta.id;instr.obsty}\\
instrument\_name&Text&&Standard name of instrument&\ucd{meta.id;instr}\\
\textbf{service\_title}&Text&&Title of resource = schema name&\ucd{meta.title}\\
\textbf{creation\_date}&Timestamp&Note~\ref{atn-4}&Date of first entry of this granule&\ucd{time.creation}\\
\textbf{modification\_date}&Timestamp&Note~\ref{atn-4}&Date of last modification&\ucd{time.processing}\\
\textbf{release\_date}&Timestamp&Note~\ref{atn-4}&Start of public access period (set to creation\_date if no proprietary period)&\ucd{time.release}\\
\multicolumn{5}{c}{\vrule width 0pt height 20pt depth 12pt \textbf{\textbf{Common optional parameters}}}\\
access\_url&Text&&URL of the data file, case sensitive (additional files may be linked through datalink\_url). Can point to a script. If present, next 2 parameters must also be present.&\ucd{meta.ref.url;meta.file}\\
access\_format&Text&&RFC 2045 media type (mime), required to be all-lower case&\ucd{meta.code.mime}\\
access\_estsize&Integer&kbyte&Estimate file size in kbyte (with this spelling)&\ucd{phys.size;meta.file}\\
access\_md5&Text&&MD5 Hash for the file when available (real file, not script)&\ucd{meta.checksum;meta.file}\\
thumbnail\_url&Text&&URL of a thumbnail image with predefined size (png ~200 pix, for use in a client only)&\ucd{meta.ref.url;meta.preview}\\
file\_name&Text&&Name of the data file only, case sensitive&\ucd{meta.id;meta.file}\\
datalink\_url&Text&&Provides links to files or services on the server&\ucd{meta.ref.url}\\
bib\_reference&Text&&Bibcode or doi recommended; can be a URL or anything else. Refers to the \emph{granule}&\ucd{meta.bib}\\
publisher&Text&&Resource publisher&\ucd{meta.curation}\\
processing\_level\_desc&Text&&Describes specificities of the processing level&\ucd{meta.note}\\
internal\_reference&Text&&Related granule\_uid(s) in the current service&\ucd{meta.id.cross}\\
external\_link&Text&&Web page providing more details on the \emph{granule}.&\ucd{meta.ref.url}\\
species&Text&&Identifies a chemical species, \emph{case sensitive}&\ucd{meta.id;phys.atmol}\\
messenger&Text&&Electro-magnetic band, from enumerated list&\ucd{instr.bandpass}\\
filter&Text&&Identifies filter in use, typically for images&\ucd{meta.id;instr.filter}\\
alt\_target\_name&Text&&Provides alternative target name(s). Can be a hash list&\ucd{meta.id;src}\\
target\_region&Text&&Type of region or feature of interest&\ucd{meta.id;src;obs.field}\\
feature\_name&Text&&Secondary name (e.g., standard name of a region of interest)&\ucd{meta.id;src;obs.field}\\
coverage&Text&&Introduces an ascii (ST)MOC (2D footprint, possibly including time or frequency, if spatial\_frame\_type = celestial or body)&\ucd{pos.outline;obs.field}\\
spatial\_coordinate\_description&Text&&ID of specific coordinate system and version / properties&\ucd{meta.code.class;pos.frame}\\
spatial\_origin&Text&&Defines the frame origin&\ucd{meta.ref;pos.frame}\\
time\_refposition&Text&&Defines \emph{where} the time is measured (e.g., ground vs spacecraft). Default is observer's frame.&\ucd{meta.ref;time.scale}\\
time\_scale&Text&&Always UTC in \emph{data} services --- from enumerated list&\ucd{time.scale}\\
solar\_longitude\_min&Float&deg&Min Solar longitude Ls (location on orbit / season)&\ucd{pos.ecliptic.lon;pos.heliocentric;stat.min}\\
solar\_longitude\_max&Float&deg&Max Solar longitude Ls (location on orbit / season)&\ucd{pos.ecliptic.lon;pos.heliocentric;stat.max}\\
local\_time\_min&Float&h&Min local time at observed region&\ucd{time.phase;time.period.rotation;stat.min}\\
local\_time\_max&Float&h&Max local time at observed region&\ucd{time.phase;time.period.rotation;stat.max}\\
target\_distance\_min&Float&km&Min observer-target distance&\ucd{pos.distance;stat.min}\\
target\_distance\_max&Float&km&Max observer-target distance&\ucd{pos.distance;stat.max}\\
target\_time\_min&Timestamp&Note~\ref{atn-4}&Min observing time in target frame&\ucd{time.start;src}\\
target\_time\_max&Timestamp&Note~\ref{atn-4}&Max observing time in target frame&\ucd{time.end;src}\\
earth\_distance\_min&Float&AU&Min Earth-target distance&\ucd{pos.distance;stat.min}\\
earth\_distance\_max&Float&AU&Max Earth-target distance&\ucd{pos.distance;stat.max}\\
sun\_distance\_min&Float&AU&Min Sun-target distance&\ucd{pos.distance;stat.min}\\
sun\_distance\_max&Float&AU&Max Sun-target distance&\ucd{pos.distance;stat.max}\\
subobserver\_longitude\_min&Float&deg&Minimum sub-observer point longitude (sub-Earth for ground based observations)&\ucd{pos.bodyrc.lon;stat.min}\\
subobserver\_longitude\_max&Float&deg&Maximum sub-observer point longitude (sub-Earth for ground based observations)&\ucd{pos.bodyrc.lon;stat.max}\\
subobserver\_latitude\_min&Float&deg&Minimum sub-observer point latitude (sub-Earth for ground based observations)&\ucd{pos.bodyrc.lat;stat.min}\\
subobserver\_latitude\_max&Float&deg&Maximum sub-observer point latitude (sub-Earth for ground based observations)&\ucd{pos.bodyrc.lat;stat.max}\\
subsolar\_longitude\_min&Float&deg&Minimum sub-solar point longitude&\ucd{pos.bodyrc.lon;stat.min}\\
subsolar\_longitude\_max&Float&deg&Maximum sub-solar point longitude&\ucd{pos.bodyrc.lon;stat.max}\\
subsolar\_latitude\_min&Float&deg&Minimum sub-solar point latitude&\ucd{pos.bodyrc.lat;stat.min}\\
subsolar\_latitude\_max&Float&deg&Maximum sub-solar point latitude&\ucd{pos.bodyrc.lat;stat.max}\\
ra&Float&deg&Right ascension&\ucd{pos.eq.ra;meta.main}\\
dec&Float&deg&Declination&\ucd{pos.eq.dec;meta.main}\\
radial\_distance\_min&Float&km&Min distance from observed area to body center&\ucd{pos.distance;pos.bodyrc;stat.min}\\
radial\_distance\_max&Float&km&Max distance from observed area to body center&\ucd{pos.distance;pos.bodyrc;stat.max}\\
altitude\_fromshape\_min&Float&km&Min altitude of observed area above shape model / DTM&\ucd{pos.bodyrc.alt;stat.min}\\
altitude\_fromshape\_max&Float&km&Max altitude of observed area above shape model / DTM&\ucd{pos.bodyrc.alt;stat.max}\\
\multicolumn{5}{c}{\vrule width 0pt height 20pt depth 12pt \textbf{\textbf{Parameters from extensions}}}\\
obs\_mode&Text&&Observing mode&\ucd{meta.code;instr.setup}\\
detector\_name&Text&&Detector name&\ucd{meta.id;instr.det}\\
opt\_elem&Text&&Optical element name&\ucd{meta.id;instr.param}\\
instrument\_type&Text&&type of instrument&\ucd{meta.id;instr}\\
acquisition\_id&Text&&ID of the data file/acquisition in the original archive&\ucd{meta.id}\\
proposal\_id&Text&&Proposal identifier&\ucd{meta.id;obs.proposal}\\
proposal\_pi&Text&&Proposal principal investigator&\ucd{meta.id.PI;obs.proposal}\\
proposal\_title&Text&&Proposal title&\ucd{meta.title;obs.proposal}\\
campaign&Text&&Name of the observational campaign&\ucd{meta.id;obs.proposal}\\
target\_description&Text&&List of keywords&\ucd{meta.note;src}\\
proposal\_target\_name&Text&&target name as in proposal title&\ucd{meta.note;obs.proposal}\\
target\_apparent\_radius&Float&arcsec&Apparent radius of the target&\ucd{phys.angSize;src}\\
north\_pole\_position&Float&deg&North pole (of target) position angle with respect to celestial north pole&\ucd{pos.posAng}\\
target\_primary\_hemisphere&Text&&Primary observed hemisphere&\ucd{meta.id;obs.field}\\
target\_secondary\_hemisphere&Text&&Secondary observed hemisphere&\ucd{meta.id;obs.field}\\
platesc&Float&arcsec/pix&pixel angular size or platescale (on sky only)&\ucd{instr.scale}\\
orientation&Float&deg&Position angle of image y axis (on sky only)&\ucd{pos.posAng}\\
measurement\_unit&Text&&Physical unit, same as Bunit in fits&\ucd{meta.unit}\\
observer\_name&Text&&Observer name&\ucd{meta.id.PI;obs.observer}\\
observer\_id&Integer&&Observer's numeric identifier&\ucd{meta.id.PI}\\
observer\_code&Text&&Observer's service username&\ucd{meta.id.PI}\\
observer\_institute&Text&&Observer institute&\ucd{meta.note}\\
observer\_country&Text&&Observer's country of residence&\ucd{meta.note;obs.observer}\\
observer\_location&Text&&Broad location of the observer or telescope&\ucd{pos;obs.observer}\\
observer\_lon&Float&deg&Observer's approximate longitude&\ucd{obs.observer;pos.earth.lon}\\
observer\_lat&Float&deg&Observer's approximate latitude&\ucd{obs.observer;pos.earth.lat}\\
original\_publisher&Text&&Refers to the source of the data, e.g.,  in compilations of experimental data&\ucd{meta.note}\\
mean\_radius&Float&km&&\ucd{phys.size.radius}\\
equatorial\_radius&Float&km&&\ucd{phys.size.radius}\\
polar\_radius&Float&km&&\ucd{phys.size.radius}\\
diameter&Float&km&Target diameter, or equivalent diameter for binary objects&\ucd{phys.size.diameter}\\
mass&Float&kg&Mass of object&\ucd{phys.mass}\\
sidereal\_rotation\_period&Float&h&Object rotation rate&\ucd{time.period.rotation}\\
semi\_major\_axis&Float&AU&&\ucd{phys.size.smajAxis}\\
inclination&Float&deg&Orbit inclination&\ucd{src.orbital.inclination}\\
eccentricity&Float&&Orbit eccentricity&\ucd{src.orbital.eccentricity}\\
long\_asc&Float&deg&Longitude of ascending node, J2000.0&\ucd{src.orbital.node}\\
arg\_perihel&Float&deg&Argument of Perihelion, J2000.0&\ucd{src.orbital.periastron}\\
mean\_anomaly&Float&deg&Mean anomaly at the epoch&\ucd{src.orbital.meanAnomaly}\\
epoch&Double&d&Epoch of interest in JD&\ucd{time.epoch}\\
magnitude&Float&mag&Absolute magnitude. For small bodies, from HG magnitude system&\ucd{phys.magAbs}\\
flux&Float&mJy&Target flux&\ucd{phot.flux.density}\\
albedo&Float&&Target albedo&\ucd{phys.albedo}\\
dynamical\_class&Text&&Class of small body, from enumerated list&\ucd{meta.code.class;src}\\
dynamical\_type&Text&&Subdivision of the class, from enumerated list&\ucd{meta.code.class;src}\\
taxonomy\_code&Text&&Code for target taxonomy&\ucd{src.class.color}\\
map\_projection&Text&&ID from enumerated list, or string with parameters (referring to a standard)&\emph{pos.projection}\\
map\_height&Float&pix&Map size in px&\ucd{phys.size}\\
map\_width&Float&pix&Map size in px&\ucd{phys.size}\\
map\_scale&Text&&Preferably as a ratio (e.g., "1:50000")&\ucd{pos.wcs.scale}\\
pixelscale\_min&Float&km/pix&Min pixel size on a surface&\ucd{instr.scale;stat.min}\\
pixelscale\_max&Float&km/pix&Max pixel size on a surface&\ucd{instr.scale;stat.max}\\
particle\_spectral\_type&Text&&From enumerated list&\ucd{meta.id;phys.particle}\\
particle\_spectral\_range\_min&Float&&&\ucd{phys.energy;phys.particle;stat.minphys.mass;phys.particle;stat.min}\\
particle\_spectral\_range\_max&Float&&&\ucd{phys.energy;phys.particle;stat.maxphys.mass;phys.particle;stat.max}\\
particle\_spectral\_sampling\_step\_min&Float&&&\ucd{spect.resolution;phys.particle;stat.min}\\
particle\_spectral\_sampling\_step\_max&Float&&&\ucd{spect.resolution;phys.particle;stat.max}\\
particle\_spectral\_resolution\_min&Float&&&\ucd{spect.resolution;phys.particle;stat.min}\\
particle\_spectral\_resolution\_max&Float&&&\ucd{spect.resolution;phys.particle;stat.max}\\
producer\_name&Text&&Data producer name, especially in compilations of experimental data&\ucd{meta.note}\\
producer\_institute&Text&&Data producer institute, e.g., in compilations of experimental data&\ucd{meta.note}\\
sample\_id&Text&&Provides a local ID in an existing catalogue&\ucd{meta.id;src}\\
sample\_classification&Text&&Information related to class, sub-class, species… as hash list&\ucd{meta.note;phys.composition}\\
sample\_desc&Text&&Describes the sample, its origin, and possible preparation. Can be a hash list&\ucd{meta.note}\\
species\_inchikey&Text&&Fixed length string identifying the species. Can be a hash list&\ucd{meta.id;phys.atmol}\\
grain\_size\_min&Float&um&Min sample particle size&\ucd{phys.size;stat.min}\\
grain\_size\_max&Float&um&Max sample particle size&\ucd{phys.size;stat.max}\\
azimuth\_min&Float&deg&Min azimuth angle for illumination&\ucd{pos.azimuth;stat.min}\\
azimuth\_max&Float&deg&Max azimuth angle for illumination&\ucd{pos.azimuth;stat.max}\\
pressure&Float&bar&Ambient pressure&\ucd{phys.pressure}\\
measurement\_atmosphere&Text&&Describes experimental conditions. ``vacuum'' for measurements under vacuum.&\ucd{meta.note;phys.pressure}\\
temperature&Float&K&Ambient temperature&\ucd{phys.temperature}\\
setup\_desc&Text&&Describes the experimental setup. Can be a hash list&\ucd{meta.note}\\
data\_calibration\_desc&Text&&Provides information on post-processing. Can be a hash list&\ucd{meta.note}\\
geometry\_type&Text&&Type of observation, from enumerated list. Can be a hash list&\ucd{meta.note;instr.setup}\\
spectrum\_type&Text&&Type of spectral observation, from enumerated list TBD. Can be a hash list&\ucd{meta.note;instr.setup}\\
event\_type&Text&&Type of event from enumerated list&\ucd{meta.code.class}\\
event\_status&Text&&From enumerated list&\ucd{meta.code.status}\\
event\_cite&Text&&From enumerated list&\ucd{meta.code.status}\\
\sptablerule
\end{longtable}
\endgroup

% /GENERATED

\end{landscape}

\subsection{Table Notes}

The entries in the Type column which are not otherwise annotated
have the following meanings:
\begin{itemize}
\item[] {\bf Text}:
      a string value represented in VOTable
      with a {\tt datatype} of {\tt char} and a suitable {\tt arraysize}
\item[] {\bf Float}:
      a floating point value represented in VOTable
      with a {\tt datatype} of {\tt float} or {\tt double}
\item[] {\bf Integer}:
      an integer value represented in VOTable
      with a {\tt datatype} of {\tt int} or {\tt long}
\item[] {\bf Double}:
      a double precision floating point value represented in VOTable
      with a {\tt datatype} of {\tt double}
\end{itemize}

The following notes are referenced by number in the table:
\begin{enumerate}
\item\label{atn-1} Depending on context (as given by
\verb|spatial_frame_type|), see table~\ref{table:spatialucds}.  Longitude
and RA range from $0\cdots 360$; Latitude and Dec range from
$-90\cdots+90$.\\
When \verb|spatial_frame_type = "none"|,
UCDs here are empty, and no unit is provided.

\item\label{atn-2} Spatial resolution parameters have the same unit as spatial
coordinate parameters. The associated UCDs combine either
\ucd{pos.resolution} (if linear) or \ucd{pos.angResolution} (if angular)
with secondary \ucd{stat.min} or \ucd{stat.max}. \ucd{c1}: only body and
celestial are angular; \ucd{c2}: only cartesian is linear; \ucd{c3}:
only spherical is angular.

\item\label{atn-3} Any contour type that works with ADQL's geometry operators
(CONTAINS, INTERSECTS...) is legal here.

\item\label{atn-4} Timestamps are provided as ISO-8601 strings as
specified by DALI \citep{2017ivoa.spec.0530P}.  On VOTable output,
\verb|xtype="timestamp"| is required.

\end{enumerate}

\begin{sidewaystable}
\begin{tabular}{p{0.1\textwidth}p{0.1\textwidth}p{0.25\textwidth}p{0.16\textwidth}p{0.13\textwidth}p{0.13\textwidth}p{0.1\textwidth}}
\sptablerule
&{\bf celestial}&{\bf body}&{\bf cartesian}
  &{\bf spherical}&{\bf cylindrical}\\
\sptablerule
{\bf c1min}
  &\ucd{pos.eq.ra;stat.min}
  &\ucd{pos.bodyrc.lon;stat.min}
  &\ucd{pos.cartesian.x;stat.min} (in km)
  &\ucd{pos.spherical.r;stat.min} (in m)
  &\ucd{pos.cylindrical.r;stat.min} (in km)\\

{\bf c1max}
  &\ucd{pos.eq.ra;stat.max}
  &\ucd{pos.bodyrc.lon;stat.max}
  &\ucd{pos.cartesian.x;stat.max} (in km)
  &\ucd{pos.spherical.r;stat.max} (in m)
  &\ucd{pos.cylindrical.r;stat.max} (in km)\\

{\bf c2min}
  &\ucd{pos.eq.dec;stat.min}
  &\ucd{pos.bodyrc.lat;stat.min}
  &\ucd{pos.cartesian.y;stat.min} (in km)
  &\ucd{pos.spherical.colat;stat.min}
  &\ucd{pos.cylindrical.azi;stat.min} \\

{\bf c2max}
  &\ucd{pos.eq.dec;stat.max}
  &\ucd{pos.bodyrc.lat;stat.max}
  &\ucd{pos.cartesian.y;stat.max} (in km)
  &\ucd{pos.spherical.colat;stat.max}
  &\ucd{pos.cylindrical.azi;stat.max} \\

{\bf c3min}
  &\ucd{pos.distance;stat.min} (in AU)
  &\ucd{pos.bodyrc.alt;stat.min} (from surface only, implicitly
    from reference level, in km)
  &\ucd{pos.cartesian.z;stat.min} (in km)
  &\ucd{pos.spherical.azi;stat.min}
  &\ucd{pos.cylindrical.z;stat.min} (height, in km) \\

{\bf c3max}
  &\ucd{pos.distance;stat.max} (in AU)
  &\ucd{pos.bodyrc.alt;stat.max} (from surface only, implicitly
    from reference level, in km)
  &\ucd{pos.cartesian.z;stat.max} (in km)
  &\ucd{pos.spherical.azi;stat.max}
  &\ucd{pos.cylindrical.z;stat.max} (height, in km) \\
\sptablerule
\end{tabular}
\caption{UCDs of the spatial columns depending on the value of
\texttt{spatial\_frame\_type}.}
\label{table:spatialucds}
\end{sidewaystable}

\subsection{Unit Conversions}
\label{sect:convs}

In order to avoid significant changes when round-tripping between units
customary in the various sub-disciplines and the ones given in the
EPN-Core table (e.g., going from wavelength to frequency during
ingestion and then back to wavelength for display purposes), services
and clients MUST use the following constants when converting values.

The concrete values given here may change with minor versions of this
standard.  Clients should hence be prepared to take the protocol
version (discoverable through the table utype) into account when doing
unit conversion as new versions of EPN-TAP are issued.

\begin{itemize}
\def\.#1{\textrm{#1}}
\item Speed of light in vacuum $c=299792458\,\.m/\.s$
\item Planck constant $h=6.62607015\cdot 10^{-34}\,\.J\.s$
\item The electronvolt $1\,\.{eV}=1.602176634\cdot 10^{-19}\,\.J$ (and
the elementary electric charge this implies)
\item Astronomical unit $1\,\.{AU}=1.495978707\cdot10^{11}\,\.m$
\item Earth equatorial radius $a_{\earth}=6.3781\cdot 10^6\,\.m$
\item Solar radius $R_{\astrosun}=6.95700\cdot10^8\,\.m$
\item Earth mass $M_{\earth}=5.9722\cdot 10^{24}\,\.{kg}$
\item Jupiter mass $M_{\jupiter}=1.8982\cdot 10^{27}\,\.{kg}$
\end{itemize}


\section{EPN-TAP and the VO Registry}
\label{sect:registry}

\subsection{Registering EPN Data Collections and Services}

EPNCore data collections are registered using VODataService
\citep{2021ivoa.spec.1102D} tablesets, where the table utype is set to
$$\hbox{\verb|ivo://ivoa.net/std/epntap#table-2.0|}.$$

This registration of the EPNCore table will work even if the table is
exposed through protocols different from TAP.  Normally, however, the
tableset will be contained in a VODataService \xmlel{CatalogService}
record with a TAP capability, and this capability will be an auxiliary
capability as per DDC \citep{2019ivoa.spec.0520D}.  For one-table
services, a full TAPRegExt \citep{2012ivoa.spec.0827D} capability is also
allowed.

Further capabilities, for instance for associated Datalink services,
may be given in the same record.

An example for a registration record in VOResource, for the case of
using an auxiliary capability referencing a main TAP service comes with
this document\footnote{\auxiliaryurl{example-record.xml}}.

The noteworthy points in the record are:

\begin{itemize}
\item A \xmlel{relationship} element referencing the main TAP service
through which the service is queriable as per DDC:
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
<relationship>
  <relationshipType>served-by</relationshipType>
  <relatedResource ivo-id="ivo://org.gavo.dc/tap"
    >GAVO Data Center TAP service</relatedResource>
</relationship>
\end{lstlisting}

\item The declaration for the auxiliary capability, including the access
URL so clients do not need to follow the relationship just declared in
simple applications:
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
<capability standardID="ivo://ivoa.net/std/TAP#aux">
   <interface role="std" version="1.1" xsi:type="vs:ParamHTTP">
     <accessURL use="base">http://dc.zah.uni-heidelberg.de/tap</accessURL>
     <mirrorURL>https://dc.zah.uni-heidelberg.de/tap</mirrorURL>
   </interface>
</capability>
\end{lstlisting}

\item Most importantly, the declaration of the table utype that lets
clients discover that this particular table contains EPNCore data:
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
<table>
  <name>mpc.epn_core</name>
  <title> EPN-TAP table for MPC Asteroid Orbital Data</title>
  <description> The EPN-TAP 2.0 version of...</description>
  <utype>ivo://ivoa.net/std/epntap#table-2.0</utype>
  ...
</table>
\end{lstlisting}
\end{itemize}

That in the example record, the resource description is identical to the
description of the schema, which again is identical to the description
of the table is an artefact of EPN-TAP registrations being single-table
and is thus to be expected in most registrations of this type.


\subsection{Discovering EPN-TAP services}

Consumers in general are interested in TAP endpoints and table names for
EPN-TAP services.  By our registration pattern, this translates into
resources with TAP capabilities that have a standard key for version 2
EPN-TAP in a table utype.  During a transition period, clients are
advised to also look for tables with the utype
\verb|ivo://vopdc.obspm/std/epncore#schema-2.0|.

Translated into RegTAP \citep{2019ivoa.spec.1011D}, the following query
would return TAP access URLs and the table names, using ADQL 2.1 CTEs
for readability:

\begin{lstlisting}[language=SQL]
WITH epntables AS (
  SELECT ivoid, table_name
  FROM rr.res_table
  WHERE
    table_utype='ivo://vopdc.obspm/std/epncore#schema-2.0'
    OR table_utype LIKE 'ivo://ivoa.net/std/epntap#table-2.%')

SELECT DISTINCT table_name, access_url
FROM epntables
  NATURAL JOIN rr.capability
  NATURAL JOIN rr.interface
WHERE
  standard_id LIKE 'ivo://ivoa.net/std/tap%'
  AND intf_role='std'
\end{lstlisting}

The \texttt{DISTINCT} in the main query is a rough filter that removes
entries duplicated because their tables are registered both in the main
TAP record and in an auxiliary capability.

\appendix
\section{Changes from Previous Versions}

This is the first public release.

EPN-TAP v1 was developed as an assessment study
during the Europlanet-RI programme (2011), and was limited to test purposes.

% these would be subsections "Changes from v. WD-..."
% Use itemize environments.


\bibliography{ivoatex/ivoabib,ivoatex/docrepo,localrefs}


\end{document}