\documentclass[10pt,notitlepage,onecolumn]{ivoa}
\parskip=1ex		% More space between paragraphs
%%% Suppress the ridicously large top separation of item lists
\makeatletter
\toks@\expandafter{\@listI}
\edef\@listI{\the\toks@\setlength{\topsep}{1pt}}
\makeatother
\topsep=0pt
\usepackage{color}		% Accept Colors
\usepackage{verbatim}		% Accept inputverbatim
\usepackage[text={14.5cm,22.5cm},a4paper]{geometry}
\usepackage[singlelinecheck=false,sl]{caption}
\usepackage[plain]{algorithm}
\usepackage{algorithmicx}
\usepackage{algpseudocode}
\algrenewcommand{\algorithmiccomment}[1]{\hskip3em$\rightarrow$ #1}
\usepackage{multirow}

% Enable hyphenation of teletype words (we've got lots of long ones
% here...)
\newcommand{\origttfamily}{}
\let\origttfamily=\ttfamily
\renewcommand{\ttfamily}{\origttfamily \hyphenchar\font=`\-}

\ifx\pdftexversion\undefined
  \usepackage[dvips]{graphicx}
  \DeclareGraphicsExtensions{.eps,.ps}
  \usepackage[ps2pdf,bookmarks=true,bookmarksnumbered=true,%
    hypertexnames=false,breaklinks=true,colorlinks,citecolor=blue,%
    linkcolor=blue,urlcolor=blue]{hyperref}
\else
  \usepackage[pdftex]{graphicx} %% graphics for pdftex (supports .pdf .jpg .png)
  \usepackage{epstopdf}         %% requires epstopdf
  \makeatletter
  \g@addto@macro\Gin@extensions{,.ps}
  \@namedef{Gin@rule@.ps}#1{{pdf}{.pdf}{`ps2pdf #1}}
  \makeatother
  \usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,%
    hypertexnames=false,breaklinks=true,colorlinks,citecolor=blue,%
    linkcolor=blue,urlcolor=blue]{hyperref}
  \pdfadjustspacing=1
\fi

\let\fg=\color			% fg = foreground color
\raggedbottom
\oddsidemargin=0cm
\parindent=0pt
\arrayrulewidth=0.75pt\renewcommand{\arraystretch}{1.2}
\definecolor{DarkRed}{rgb}{0.5,0,0}
\definecolor{DarkBlue}{rgb}{0,0,0.5}
\def\filex{pdf}	% File extension
\def\attr#1{{\tt{\fg{DarkRed}#1}}}
\def\elem#1{{\tt{\fg{DarkRed}#1}}}
\def\STCElement#1{{\tt{\fg{DarkBlue}#1}}}
\def\allowhyphens{\penalty0\hskip0pt}
\def\attrval#1#2{{\texttt{#1="\allowhyphens #2"}}}
\def\utype#1{\attrval{utype}{#1}}
\def\valuelit#1{\texttt{#1}}
\def\twikiname#1#2{\makebox[10em][l]{{#2}}}

\newcommand{\dmURI}{http:/\slash www.ivoa.net\slash xml\slash STC\slash stc-v1.30.xsd}

\makeatletter
\newenvironment{utypelist}%
  {\renewcommand\item[1][undefined]{\par\hskip-\leftmargin
    \makebox[\textwidth][l]{\texttt{##1}}\\
      \global\@newlistfalse}
  \begin{list}\global\@newlistfalse}%
  {\end{list}}
\makeatother

\begin{document}

\title{Referencing STC in VOTable}
\date{2010-06-18}

\ivoatype{IVOA Note}

\version{2.0}

\editor{Markus {Demleitner}}
\urlthisversion{%\par\noindent {\bf This version:}\\
  \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20100618.\filex}}
\urllastversion{
  \url{http://www.ivoa.net/Documents/latest/VOTableSTC.\filex}
}
\previousversion{
  \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20090612.\filex}
  V1.1\\
\hspace*{0.8cm}\url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20081030.\filex}
  V1.02\\
\hspace*{0.8cm}\url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20081018.\filex}
  V1.01\\
\hspace*{0.8cm}\url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20080910.\filex}
  V1.00\\
   
  }
% Give author list: separate different authors with \\
% You can add email addresses with links \url{mailto:yourname@ivoa.net}
\author{
\normalsize \twikiname{MarkusDemleitner}{Markus {\bf Demleitner}}
   \quad{\em Zentrum f\"ur Astronomie Heidelberg, Germany} \\
\normalsize \twikiname{FrancoisOchsenbein}{Fran\c cois {\bf Ochsenbein}}
	\quad{\em Observatoire Astronomique de Strasbourg, France} \\
\normalsize \twikiname{JonathanMcDowell}{Jonathan {\bf McDowell}}
   \quad{\em Harvard-Smithsonian Center for Astrophysics, USA} \\
\normalsize \twikiname{ArnoldRots}{Arnold {\bf Rots}}
   \quad{\em Harvard-Smithsonian Center for Astrophysics, USA} \\
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\begin{document}



\maketitle % print header in standard form

\section*{Abstract}
This note specifies how to define the roles individual
VOTable~\cite{votrec} fields have within the STC data model~\cite{stc}
and the coordinate systems they are expressed in using VOTable GROUP,
PARAM, and FIELDref elements.

It is hoped that the basic mechanisms proposed here can be applied to
data models other than STC as well.

\section*{Status of this document}

This is an IVOA note expressing suggestions from and opinions of the
authors.  It is intended to share best practices, possible approaches,
or other perspectives on interoperability with the Virtual Observatory.

While this note was made in agreement between the {\em VOTable} and the
{\em Data Models} Working Groups, it should not be referenced or
otherwise interpreted as a standard specification.

Comments to this note are welcome, either to Markus Demleitner or the
VOTable mailing list.

\tableofcontents

\section{Introduction}

Astronomical tables like source catalogues, observation logs or even
simulation data usually contain columns giving spatio-temporal data:
Positions, velocities or proper motions, times, redshifts, frequencies.
To be interpretable, such columns need a precise description of the
system their values are expressed in (reference system, reference
position, and the like).  Also the ``roles''within a set of space-time
coordinates (e.g., x is the error of y, which in turn is a time
derivative of z) need to be explicit within the transport format to
allow automated analysis and later interpretation.

In the context of the Virtual Observatory (VO), tabular data is typically
exchanged employing VOTables.  In the early days of the VO, a dedicated
\elem{COOSYS} element was introduced in the original version (1.0) of
the VOTable specification~\cite{vot10}.  It allowed some minimal level
of details about coordinate systems, merely supporting an enumeration of
the most commonly used coordinate frames (ICRS, historical equatorial
frames, galactic, ecliptic, etc) associated to a couple of parameters
(equinox and epoch).  Experience has shown that the \elem{COOSYS}
element is not expressive enough. It was therefore deprecated in
VOTable version 1.2.

The description of coordinate systems should now proceed on the basis of
the IVOA data model for space-time coordinates~\cite{stc}.  To link
elements of a VOTable with those of a data model, version 1.1 of the
VOTable specification introduced the \attr{utype} attribute, which is
allowed on most VOTable elements, among others on \elem{GROUP},
\elem{FIELD}, \elem{PARAM}, and, since 1.2, \elem{FIELDref} and
\elem{PARAMref}.  The value of a \attr{utype} attribute is a pointer
into a data model in an application-specific sense.\footnote{The Data
Models working group is preparing a document that will contain further
guidelines on the relation between utypes and data models.}

This note suggests a mechanism for combining utypes, the STC data
model, and VOTables into a system to transfer and store STC information
within VOTable without requiring all clients to support the entire (or
even a significant part) of the STC data model.

\def\multi2par#1{\multirow{2}{*}{\parbox{0.65\textwidth}{#1}}}
\def\subheadstrut{\vrule width 0pt height 12pt depth 4pt}



\section{Informal Guide to Embedding STC in VOTable}
\label{sec:howto}

This section informally explains how to embed STC information and is
hoped to cover simple use cases.

All STC-related information is contained in \elem{GROUP}s with
\utype{stc:CatalogEntryLocation}.  Any metadata -- i.e., data not
contained in table columns -- is defined using \elem{PARAM} elements
with certain utypes, whereas the table \elem{FIELD}s are furnished with
utypes using \elem{FIELDref} elements.  The \elem{GROUP} element(s)
defining the system(s) are direct children of the \elem{TABLE}
containing the \elem{FIELD}s.


Consider a simple example:

%%!make ex1
\begin{verbatim}
<TABLE name="withref">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="href" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.href"
      value="ivo://STClib/CoordSys#TT-ICRS-TOPO"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="ra" utype="stc:AstroCoords.Position2D.Value2.C1"/>
    <FIELDref ref="de" utype="stc:AstroCoords.Position2D.Value2.C2"/>
    <FIELDref ref="dateObs" utype="stc:AstroCoords.Time.TimeInstant"/>
  </GROUP>
  <FIELD ID="dateObs" name="dateObs" datatype="char" arraysize="*"/>
  <FIELD ID="ra" name="ra" datatype="float"/>
  <FIELD ID="de" name="de" datatype="float"/>
</TABLE>
\end{verbatim}

\begin{table}[tb]
\begin{flushright}
\caption{\label{tab:STClib}
{Some systems defined in the STC library; to obtain valid values for the
utype
\valuelit{stc:AstroCoordSystem.href}, prepend {\tt ivo://STClib/CoordSys\#}}.
Other coordinate systems defined
in \cite{stc}, Appendix C.1 include systems like {\small
TT-FK5-TOPO}, {\small UTC-ICRS-TOPO}, {\small UTC-ICRS-GEO}, 
{\small TDB-FK5-BARY}, {\small TDB-ECLIPTIC-BARY}, 
or {\small TT-ICRS-RADIO-LSR-TOPO}.}

\begin{tabular}{|p{0.23\textwidth}|p{0.70\textwidth}|}\hline
{\tt TT-ICRS-TOPO} & Terrestrial time reported at local place,
        ICRS orientation of axes with origin at local place\\
{\tt UTC-FK5-TOPO} & As UTC-ICRS-TOPO but in FK5 system at Equinox J2000.0 \\
{\tt TT-ICRS-GEO} & Terrestrial time reported at center of Earth,
        ICRS orientation of axes with origin at center of Earth \\
{\tt TDB-ICRS-BARY} & Barycentric Dynamical Time  reported at Solar System Barycenter,
        ICRS orientation of axes with origin at Solar System Barycenter \\
\hline\end{tabular}
\end{flushright}
\end{table}

In this example, the coordinate system is defined via a reference to the
STC library as specified in Appendix C.1 of \cite{stc}.  Table
\ref{tab:STClib} lists some common values taken from there.  The
\elem{PARAM} with \attrval{utype}{stc:DataModel.URI} is essentially
constant.  It is intended to tell clients where to learn more about the
particular data model employed by the writing application.

We proceed to assign the roles the indiviual fields fill.  For this
purpose, \elem{FIELDref}s tie together a utype (designating the field's
role) and the \elem{FIELD} itself via a reference to the
\elem{FIELD}'s ID.

Due to the complexity of the STC data model, the list of possible STC utypes
is very long.  In the formal definition of the utypes, we therefore give
an algorithm that constructs utypes from the STC-X XML schema
\cite{stcx}.  However, we give a list of common STC utypes in
appendix~\ref{app:utypelist}. It is intended to cover the common use
cases. You are welcome to contact the authors to have more utypes
included.

All \elem{PARAM}s containing STC utype/value-pairs
have the VOTable \attrval{datatype}{char} with \attrval{arraysize}{*}.
This is because the serialization of the values is defined in terms of
the STC-X schema, which means all values going into \elem{PARAM}s are
XML character data.  A welcome consequence of this is that clients
in a ``pipeline'' need only store key/value pairs for the STC
information, interpret as much as they need and can still correctly
serialize the original information without having to understand all
utypes involved.

\elem{PARAM} elements must have \attr{name} attributes.  While you are
free to choose them as convenient, it is recommended to use whatever
is behind the last dot in the utype.

This mechanism of transmitting utype/value pairs using \elem{PARAM}s
extends to all parts of STC, allowing the definition of coordinate
systems not available in the STC library as well as constant values.

Let us give a second, more complex, example to illustrate the use of
\elem{PARAM}s and the definition of two sets of coordinates in one table:

%%!make ex2
\begin{verbatim}
<TABLE name="twosystems">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="CoordFlavor" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordFlavor"
      value="SPHERICAL"/>
    <PARAM name="CoordRefFrame" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordRefFrame"
      value="ICRS"/>
    <PARAM name="ReferencePosition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.TimeFrame.ReferencePosition"
      value="BARYCENTER"/>
    <PARAM name="TimeScale" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.TimeFrame.TimeScale" value="TT"/>
    <PARAM name="Epoch" datatype="char" arraysize="*"
      utype="stc:AstroCoords.Position2D.Epoch" value="2010.2"/>
    <PARAM name="yearDef" datatype="char" arraysize="*"
      utype="stc:AstroCoords.Position2D.Epoch.yearDef" value="J"/>
    <PARAM name="TimeInstant" datatype="char" arraysize="*"
      utype="stc:AstroCoords.Time.TimeInstant"
      value="2002-01-28T09:30:00"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="raErr"
      utype="stc:AstroCoords.Position2D.Error2.C1"/>
    <FIELDref ref="deErr"
      utype="stc:AstroCoords.Position2D.Error2.C2"/>
    <FIELDref ref="ra" utype="stc:AstroCoords.Position2D.Value2.C1"/>
    <FIELDref ref="de" utype="stc:AstroCoords.Position2D.Value2.C2"/>
    <FIELDref ref="pmra"
      utype="stc:AstroCoords.Velocity2D.Value2.C1"/>
    <FIELDref ref="pmde"
      utype="stc:AstroCoords.Velocity2D.Value2.C2"/>
  </GROUP>
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="CoordFlavor" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordFlavor"
      value="SPHERICAL"/>
    <PARAM name="CoordRefFrame" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordRefFrame"
      value="GALACTIC_II"/>
    <PARAM name="ReferencePosition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.ReferencePosition"
      value="BARYCENTER"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="glon"
      utype="stc:AstroCoords.Position2D.Value2.C1"/>
    <FIELDref ref="glat"
      utype="stc:AstroCoords.Position2D.Value2.C2"/>
  </GROUP>
  <FIELD ID="glon" name="glon" datatype="float"/>
  <FIELD ID="glat" name="glat" datatype="float"/>
  <FIELD ID="ra" name="ra" datatype="float"/>
  <FIELD ID="de" name="de" datatype="float"/>
  <FIELD ID="raErr" name="raErr" datatype="float"/>
  <FIELD ID="deErr" name="deErr" datatype="float"/>
  <FIELD ID="pmra" name="pmra" datatype="float"/>
  <FIELD ID="pmde" name="pmde" datatype="float"/>
</TABLE>
\end{verbatim}

Note that the two coordinate sets present are translated into two
groups with \attrval{utype}{stc:Ca\-talog\-En\-try\-Location}.

The first group contains proper motions and errors, and specifies the
time of the observation together with the time scale needed to make
sense of the number.  The positions have been brought to a
specific epoch (that is not a property of the coordinate system but
rather of the positions themselves) using the proper motions.  The
second group only contains a minimal definition of the galactic
coordinates.

The remainder of this document gives a more formal specification of 
the embedding of STC in VOTable -- which the reader may skip unless
she needs to represent more advanced concepts -- and some additional examples.

\section{Specification}

\subsection{Location of Definitions}

Each instance of STC, i.e., each coordinate system, is defined in
exactly one \elem{GROUP} element.  All such groups have a utype with a
data model identifier (i.e., the part in front of the colon) of
\valuelit{stc}.  The role identifier (i.e., the part behind the colon)
of this utype
could in principle be any name of an STC-X element of stcMetadataType or
its descendants.  However, for ease of implemenation we only allow two
types:

\begin{enumerate}
\item\valuelit{stc:CatalogEntryLocation} for groups describing coordinates
of astronomical objects or observations.  Whether what is contained in
the VOTable actually are entries of a ``catalog'' in some sense is
irrelevant.  The idea is that user programs only need to locate
\elem{GROUP}s with this utype to obtain the STC information.
\item\valuelit{stc:ObservatoryLocation} for groups describing the
coordinates of the artefact that performed an observation.  Except as
part of Characterization, such groups
should only be present if required to, e.g., define a
the topocenter.
\end{enumerate}

Each group \emph{should} declare the URI of the data model used by
including a utype\slash value pair of \valuelit{stc:DataModel.URI} and 
\valuelit{\dmURI} (or possibly later versions).

Such groups \emph{must} be direct children of the \elem{TABLE} element
containing the \elem{FIELD} elements being described.  This
specification does not propose any mechanism to describe coordinate sets
with components in several tables.  If such functionality should ever be
desired, the \elem{GROUP}s would probably be children of the enclosing
\elem{RESOURCE}, while coordinate systems spanning different resources
would be forbidden.

\begin{algorithm}
\caption{Generation of utypes from STC-X trees}
\label{alg:treetoutype}
\begin{algorithmic}
\Procedure{emitUtypesNode}{$n$, $u$}

\Comment{$n$ is a node within an STC-X Tree}

\Comment{$u$ is a string containing the parent's \attr{utype}}

\If{$n$'s type inherits from one of the types in
table~\ref{tab:subsgroups}} 

  \State {$u\gets u+\verb|'.'|+n$'s substitution group's utype fragment}

\ElsIf{$n$'s type inherits from AbsoluteTime}
  \State emit a pair of $u+\verb|'.xtype'|$, ${\rm name}(n)$
\Else
  \State{$u\gets u+\verb|'.'|+{\rm name}(n)$}
\EndIf
\If {$n$ has non-empty text content}
  \State emit a pair of $u$ and $n$'s text content
\EndIf
\State call {\sc emitAttrUtypes}($n$, $u$)
\For{all child nodes nodes $n'$ of $n$}
  \State call {\sc emitUtypesNode($n'$, $u$)}
\EndFor
\EndProcedure
\end{algorithmic}
\end{algorithm}


\begin{table}[htb]
\caption{\label{tab:subsgroups}
{Substitution group/utype mapping (for
algorithm \ref{alg:treetoutype})}}
\begin{tabular}{|ll|}\hline
 Substitution group head&utype fragment \\
 \hline
 spaceRefFrameType&\verb|SpaceRefFrame|\\
 referencePositionType&\verb|ReferencePosition|\\
 coordFlavorType&\verb|CoordFlavor|\\
\hline\end{tabular}
\end{table}

\subsection{Values and Utypes}
\label{subsec:valuty}
The point of using utypes to serialize data model instances is that a
potentially complex structure is mapped to one or more sequence(s) of
pairs of utype and value.

This process is defined here in terms of the STC-X
serialization~\cite{stcx} since its schema currently provides the most
rigorous representation of STC metadata.  Any equivalent way of creating
the key-value pairs is, of course, equally valid.

To generate the utype-value pairs for a given STC structure,
first generate a DOM tree of STC-X, e.g., according to the rules of the
W3C DOM \cite{dom}.  Only STC-X documents rooted in either
\STCElement{CatalogEntryLocation} or \STCElement{ObservatoryLocation}
are admitted.

Values in the STC-X schema are restricted to floating point or similar
value literals.  For the current purposes, this is not enough, since
roles in the STC data model might be filled by value references (i.e.,
references to \elem{FIELD} elements) rather than (immediate) values.  To
avoid excessive formalism, we refrain from specifying a mechanism by
which \elem{FIELD} references could be injected into STC-X and just
stipulate that any text content or attribute value in the STC-X DOM tree
can be replaced by such a reference.


On the DOM tree obtained in this way, execute the procedure {\sc
emitUtypesNode} (algorithm \ref{alg:treetoutype}), passing the root node
for $n$ and a string containing \valuelit{stc:} for $u$.  
For the determination of node names,
namespaces are disregarded, i.e., a node with QName
{\{http://www.ivoa.net\slash xml\slash STC\slash stc-v1.30.xsd\}C1}
just is C1 for the purposes of this algoritm.

Due to a typo in the STC-X schema in version 1.30, some elements there
are called \STCElement{Timescale}.  For utype generation, assume these
are called \STCElement{TimeScale}.

\begin{algorithm}
\caption{Generation of utypes from STC-X attributes}
\label{alg:attrtoutype}
\begin{algorithmic}

\Procedure{emitAttrUtypes}{$n$, $u_0$}

\Comment $n$ is a node within an STC-X-Tree

\Comment $u_0$ is a string containing the $n$'s utype

\For{all key-value pairs $k$, $v$ formed from the $n$'s attributes}

  \Comment $k$ is an attribute name without any namespace notation
  \If{$k$ is not in the set of banned attributes}
   
    \Comment{The banned attributes are given in
    table~\ref{tab:bannedattrs}.}

    \State $u\leftarrow u_0+\verb|'.'|+k$

    \State Emit a pair $u$, $v$.
  \EndIf
\EndFor
\EndProcedure
\end{algorithmic}
\end{algorithm}

\begin{table}[htb]
\caption{\label{tab:bannedattrs}
{Banned attributes for utype generation (for algorithm
\ref{alg:attrtoutype}).}}
\begin{tabular}{|ll|}\hline
\attr{idref}&\multirow{4}{*}{\parbox{0.6\textwidth}{Not necessary in the
scheme described here.}}\\
\attr{id}&\\
\attr{frame\_id}&\\
\attr{coord\_system\_id}&\\
\hline
\attr{ucd}&\multirow{8}{*}{\parbox{0.6\textwidth}{Allowing these would create conflicts with
VOTable's mechanisms of specifying them.}}\\
\attr{unit}&\\
\attr{pos\_angle\_unit}&\\
\attr{pos\_unit}&\\
\attr{spectral\_unit}&\\
\attr{time\_unit}&\\
\attr{vel\_time\_unit}&\\
\attr{gen\_unit}&\\
\hline
\attr{xlink:type}&
\parbox{0.6\textwidth}{Fixed equal to simple here.}\\
\hline
\end{tabular}
\end{table}

If this procedure yields two values for a single utype, the
result is undefined, but a utype generating program {\em should}
raise an error.  This means the STC-X instance documents containing,
e.g., multiple generic coordinate systems or multiple area
specifications cannot be serialized to utypes using this
algorithm.  
Also, the STC-X root element must not have more than
one child of each \STCElement{AstroCoordSystem},
\STCElement{AstroCoords}, and \STCElement{AstroCoordArea}.

We believe this is acceptable for the purpose addressed in
this note; generic coordinates are not supported by the mechanism
defined here anyway and should be represented in VOTables by some other
means.  Multiple coordinate systems should be defined in multiple STC-X
documents leading to multiple \elem{GROUP}s as shown above.

At \url{http://vo.ari.uni-heidelberg.de/docs/utypes.xsl} we give an XSLT
program that generates utype-value sequences from STC-X documents.


\subsection{Pair serialization}
\label{subsec:pairser}

The procedure outlined above yields a sequence of pairs of utypes and
string-typed values.  Generators will have to maintain some way of telling
whether such a string represents a \elem{FIELD} reference or an immediate value.

In VOTables, \elem{FIELD} references are encoded as
\elem{FIELDref} elements with the \attr{utype} and \attr{ref} attributes
representing the utype and the value of the pair, respectively.

Immediate values are serialized to \elem{PARAM} elements.  The \attr{utype}
and \attr{value} attributes reflect utype and value of the pair,
respectively.  Since by construction all values are strings,
\attrval{datatype}{char} and \attrval{arraysize}{*} must be given on all
\elem{PARAM}s.  The application is free to set the (required)
\attr{name} attribute on \elem{PARAM}s as it sees fit; absent
other considerations, it is recommended to split the utype at the dots 
and use the last part of the resulting sequence as \attr{name}.

In addition to the recipe given in section~\ref{subsec:valuty}, an
application \emph{should} copy a \attr{ucd} attribute from STC-X
elements to VOTable \elem{PARAM} elements if generating utypes from
STC-X.  Since clear rules on how to construct suitable unit strings
from STC-X documents are beyond the scope of this document, we only
note that applications \emph{may} try to infer units for
\elem{PARAM}s; when serializing directly from some internal
representation, the \elem{PARAM}'s \attr{unit} attribute \emph{should}
be given.

Applications \emph{may} drop any utype/value pair during serialization.
On deserialization, the rules on handling unknown
properties stated in \cite{stc} apply.  In particular, utypes ending with
\valuelit{xtype} \emph{should} be dropped in VOTables since VOTable
\elem{FIELD}s have a (possibly conflicting) \attr{xtype} attribute.  In
case of conflicts, the attribute of \elem{FIELD} \emph{must} always
take precedence.

The epoch is not part of the STC data model in version 1.30.  It will be
present in future versions.  Until these versions are adopted by the
IVOA, for epochs on positions use
\utype{AstroCoords.PositionX.Epoch}, where X is one of 1D, 2D, or 3D.
Literals for this utype in \elem{PARAM}s are floating point literals
understood to be Julian years.  If you must give the epoch in Besselian
years -- which is discouraged --, add a \utype{AstroCoords.PositionX.Epoch.yearDef} with the fixed
value \texttt{B}.

\section{Further Examples}
\label{sec:examples}

Both as an illustration and to help understand the application of the
STC data model's concepts to describing coordinates in VOTables, we
give some further examples here; for two basic examples, see
section~\ref{sec:howto}.  In all examples, we only show the relevant
\elem{TABLE} element.

\subsection{Referring to Regions}

In this example, we show how to describe a column that contains a
region specification (as might be necessary in, e.g., TAP results).

%%!make ex3
\begin{verbatim}
<TABLE name="withreg">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="href" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.href"
      value="ivo://STClib/CoordSys#TT-ICRS-TOPO"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="region" utype="stc:AstroCoordArea.Circle"/>
  </GROUP>
  <FIELD ID="region" name="region" datatype="char" xtype="adql:REGION"
    arraysize="*"/>
</TABLE>
\end{verbatim}



\subsection{Ephemeris of a Comet}

In solar system applications, it is usually necessary to specify the
planetary ephemeris used.  The following example illustrates how to do
this, and in addition employs a coordinate system including distances.

%%!make ex4
% You'll need to manually break the insane PlanetaryEphem thing below
\begin{verbatim}
<TABLE name="epcomet">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="CoordFlavor" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordFlavor"
      value="SPHERICAL"/>
    <PARAM name="coord_naxes" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordFlavor.coord_naxes"
      value="3"/>
    <PARAM name="CoordRefFrame" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordRefFrame"
      value="ICRS"/>
    <PARAM name="ReferencePosition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.ReferencePosition"
      value="GEOCENTER"/>
    <PARAM name="PlanetaryEphem" datatype="char" arraysize="*" utype=
      "stc:AstroCoordSystem.SpaceFrame.ReferencePosition.PlanetaryEphem" 
      value="JPL-DE405"/>
    <PARAM name="ReferencePosition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.TimeFrame.ReferencePosition"
      value="GEOCENTER"/>
    <PARAM name="TimeScale" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.TimeFrame.TimeScale" value="UTC"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="RA" utype="stc:AstroCoords.Position3D.Value3.C1"/>
    <FIELDref ref="DE" utype="stc:AstroCoords.Position3D.Value3.C2"/>
    <FIELDref ref="Dist"
      utype="stc:AstroCoords.Position3D.Value3.C3"/>
    <FIELDref ref="DateObs" utype="stc:AstroCoords.Time.TimeInstant"/>
  </GROUP>
  <FIELD ID="DateObs" name="DateObs" datatype="char"
    xtype="adql:TIMESTAMP" arraysize="*"/>
  <FIELD ID="RA" name="RA" datatype="float"/>
  <FIELD ID="DE" name="DE" datatype="float"/>
  <FIELD ID="Dist" name="Dist" datatype="float"/>
</TABLE>
\end{verbatim}


\subsection{Constant Values}

If certain parts of your space-time coordinates are constant, you can
use \elem{PARAM}s to transmit them, as in the following example that
might be produced by an experiment monitoring the variability of a
single source:

%%!make ex5
\begin{verbatim}
<TABLE name="constpos">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="CoordFlavor" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordFlavor"
      value="SPHERICAL"/>
    <PARAM name="CoordRefFrame" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpaceFrame.CoordRefFrame"
      value="GALACTIC_II"/>
    <PARAM name="TimeScale" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.TimeFrame.TimeScale" value="TT"/>
    <PARAM name="C1" datatype="char" arraysize="*"
      utype="stc:AstroCoords.Position2D.Value2.C1" value="289.9509"/>
    <PARAM name="C2" datatype="char" arraysize="*"
      utype="stc:AstroCoords.Position2D.Value2.C2" value="64.36"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="dateObs" utype="stc:AstroCoords.Time.TimeInstant"/>
  </GROUP>
  <FIELD ID="dateObs" name="dateObs" datatype="float"/>
  <FIELD ID="flux" name="flux" datatype="float"/>
</TABLE>
\end{verbatim}

\subsection{Redshift and Spectral}

For completeness, here is a table definition with frequency and
redshift columns.

%%!make ex6
\begin{verbatim}
<TABLE name="specshift">
  <GROUP utype="stc:CatalogEntryLocation">
    <PARAM name="DopplerDefinition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.RedshiftFrame.DopplerDefinition"
      value="OPTICAL"/>
    <PARAM name="value_type" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.RedshiftFrame.value_type"
      value="REDSHIFT"/>
    <PARAM name="value_type" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.RedshiftFrame.value_type"
      value="REDSHIFT"/>
    <PARAM name="ReferencePosition" datatype="char" arraysize="*"
      utype="stc:AstroCoordSystem.SpectralFrame.ReferencePosition"
      value="TOPOCENTER"/>
    <PARAM name="URI" datatype="char" arraysize="*"
      utype="stc:DataModel.URI"
      value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/>
    <FIELDref ref="z" utype="stc:AstroCoords.Redshift.Value"/>
    <FIELDref ref="freq" utype="stc:AstroCoords.Spectral.Value"/>
  </GROUP>
  <FIELD ID="freq" name="freq" datatype="float"/>
  <FIELD ID="z" name="z" datatype="float"/>
</TABLE>
\end{verbatim}

\begin{appendix}

\section{Common utypes}
\label{app:utypelist}
Due to the sheer size of the STC data model, it is impractical to
enumerate all utypes that can be generated from it by the recipe given
here.  Thus, we simply give commonly useful utypes here.  The
explanations given here are only intended to suggest possible uses.
Since utypes really are pointers into data models, the STC data model 
is authoritative for the interpretation of the utypes.

For concepts expressible in STC-S, you can generate utypes using a GAVO web
service \cite{gavoutypes}.

\begin{utypelist}
% the following stuff is machine generated.  To regenerate, replace
% everything up to \end{utypelist} with the output of
% grep -v "^\#" utypelist.txt | sort | sed -e 's/[^\t]*/\\item[&]/'
\item[stc:AstroCoordArea.Position2VecInterval.HiLimit2Vec.C1]	largest value of the first component in a 2D spatial interval (a ``box'')
\item[stc:AstroCoordArea.Position2VecInterval.HiLimit2Vec.C2]	largest value of the second component in a 2D spatial interval (a ``box'')
\item[stc:AstroCoordArea.Position2VecInterval.LoLimit2Vec.C1]	smallest value of the first component in a 2D spatial interval (a ``box'')
\item[stc:AstroCoordArea.Position2VecInterval.LoLimit2Vec.C2]	smallest value of the second component in a 2D spatial interval (a ``box'')
\item[stc:AstroCoordArea.SpectralInterval.HiLimit]	the upper limit of a range of frequencies
\item[stc:AstroCoordArea.SpectralInterval.LoLimit]	the lower limit of a range of frequencies
\item[stc:AstroCoordArea.TimeInterval.StartTime]	date and time of the beginning of an observation or event
\item[stc:AstroCoordArea.TimeInterval.StartTime.Error]	associated Error
\item[stc:AstroCoordArea.TimeInterval.StopTime]	date and time of the end of an observation or event
\item[stc:AstroCoordArea.TimeInterval.StopTime.Error]	associated Error
\item[stc:AstroCoords.Position2D.Epoch]	point in time the positions are reduced to using given proper motions\footnote{Not part of the STC data model yet.	See section~\ref{subsec:pairser}}
\item[stc:AstroCoords.Position2D.Epoch.yearDef]	(see Epoch utype)
\item[stc:AstroCoords.Position2D.Error2.C1]	error in the first component of a 2D position
\item[stc:AstroCoords.Position2D.Error2.C2]	error in the second component of a 2D position
\item[stc:AstroCoords.Position2D.Error2Radius]	error radius of a 2D position
\item[stc:AstroCoords.Position2D.Resolution2.C1]	the resolution of the first component of a 2D spatial position
\item[stc:AstroCoords.Position2D.Resolution2.C2]	the resolution of the second component of a 2D spatial position
\item[stc:AstroCoords.Position2D.Resolution2Radius]	resolution of a 2D spatial position specification
\item[stc:AstroCoords.Position2D.Value2.C1]	first component (e.g., right ascension or longitude on a sphere) of a 2D position
\item[stc:AstroCoords.Position2D.Value2.C2]	second component (e.g., declination or latitude on a sphere) of a 2D position
\item[stc:AstroCoords.Redshift.Value]	a redshift (or radial velocity when position is 2D)
\item[stc:AstroCoords.Spectral.Value]	a frequency or wavelength
\item[stc:AstroCoords.Time.Resolution]	The resolution of a time axis
\item[stc:AstroCoords.Time.TimeInstant]	date and time of an observation or event
\item[stc:AstroCoords.Time.TimeInstant.Error]	associated error
\item[stc:AstroCoords.Velocity2D.Error2.C1]	error in the first component of 2D proper motion
\item[stc:AstroCoords.Velocity2D.Error2.C2]	error in the second component of 2D proper motion
\item[stc:AstroCoords.Velocity2D.Error2Radius]	error radius for a 2D proper motion
\item[stc:AstroCoords.Velocity2D.Value2.C1]	first component of 2D proper motion
\item[stc:AstroCoords.Velocity2D.Value2.C2]	second component of 2D proper motion
\item[stc:AstroCoordSystem.RedshiftFrame.DopplerDefinition]	OPTICAL, RADIO, or RELATIVISTIC
\item[stc:AstroCoordSystem.RedshiftFrame.ReferencePosition]	see stc:AstroCoordSystem.SpectralFrame.ReferencePosition
\item[stc:AstroCoordSystem.RedshiftFrame.value\_type]	REDSHIFT or VELOCITY
\item[stc:AstroCoordSystem.SpaceFrame.CoordFlavor.naxis]	number of axes in the coordinate system
\item[stc:AstroCoordSystem.SpaceFrame.CoordFlavor]	takes values like SPHERICAL, CARTESIAN, POLAR; 2D-spherical implied for common reference frames if omitted
\item[stc:AstroCoordSystem.SpaceFrame.CoordRefFrame]	takes values like ICRS, FK5, FK4, ECLIPTIC, GALACTIC, SUPER\_GALACTIC, J2000, B1950
\item[stc:AstroCoordSystem.SpaceFrame.ReferencePosition]	see stc:AstroCoordSystem.TimeFrame.ReferencePosition
\item[stc:AstroCoordSystem.SpectralFrame.ReferencePosition]	see stc:AstroCoordSystem.TimeFrame.ReferencePosition; additionally, values like LSR, LSRK, LSRD are admitted.
\item[stc:AstroCoordSystem.TimeFrame.ReferencePosition]	takes values like TOPOCENTER, BARYCENTER, HELIOCENTER, GEOCENTER, GALACTIC\_CENTER, RELOCATABLE, UNKNOWNRefPos, or planet names
\item[stc:AstroCoordSystem.TimeFrame.TimeScale]	takes values like TT, TAI, UTC, TDB, LST, or LOCAL 
\end{utypelist}

For positional utypes, only the two-dimensional variants are given.  The
one- and three-dimensional utypes can be obtained by applying
fairly obvious changes.


\section{History and Modifications}
\begin{itemize}
\item	Version 1.0 (2008-09-10) to 1.01 (2008-10-18):
	\begin{itemize}
	\item	the reference to STC-Lib definitions in the form
		\attrval{ref}{ivo://STC\-lib/CoordSys\#UTC-ICRS-TOPO}
		was removed (not conforming to the {\em ID/IDref}
		XML definitions). The \elem{PARAM} with the 
		\utype{AstroCoordSystem.coord\_system\_id}
		is used instead.
	\item	the \elem{PARAM} element
		with \utype{AstroCoordSystem.coord\_sys\-tem\_id}
		is reserved for {STC-Lib} standard values;
		these parameters were removed from examples.
	\item	specification of coordinate components was partly rewritten.
	\end{itemize}
\item	Version 1.01 (2008-10-18) to 1.02 (2008-10-30):
	cosmetics
\item	Version 1.02 (2008-10-30) to 1.1 (2009-06-12):
	\begin{itemize}
	\item	explicitation of how to specify the epoch of coordinates.
	\item	recommendation to write the coordinate definitions
		{\em before} referencing them.
	\item	usage of \attrval{xtype}{iso8601}.
	\end{itemize}
\item Version 2.0 (2010-06-18)
  \begin{itemize}
  \item Basically a re-write; new document structure with an
    introductory section for the benefit of the 80/20 rule.
  \item Define utypes and values in terms of the STC-X serialization.
  \item Scrap two-group principle; one system is now contained in
    one group.
  \item Remove second-level groups within AstroCoordSystem (there can
    be only one of each anyway).
  \item Move stclib references into AstroCoordSystem.href.
  \item Change examples (to machine-generated ones).
  \end{itemize}

\end{itemize}

\end{appendix}


\begin{thebibliography}{99}
\bibitem{vot10} Ochsenbein, F., et, al, 2003:
  \textit{VOTable: A Proposed XML Format for Astronomical Tables},
  Version 1.0,
  \url{http://www.ivoa.net/Documents/VOTable/20031017/PR-VOTable-1.0-20031017.html}

\bibitem{votrec} Ochsenbein, F., et al., 2009:
  \textit{VOTable Format Definition},
  Version 1.2,
  \url{http://www.ivoa.net/Documents/VOTable/20091130/REC-VOTable-1.2.html}

\bibitem{stc} Rots, A., 2007:
  \textit{Space-Time Coordinate Metadata for the Virtual Observatory},
  Version 1.33,
  \url{http://www.ivoa.net/Documents/REC/DM/STC-20071030.html}

\bibitem{stcx} Rots, A, 2005: 
  \textit{STC-X: Space-Time Coordinate (STC) Metadata
  XML Implementation}, Version 1.0,
  \url{http://www.ivoa.net/Documents/Notes/STC-X/STC-X-20050315.html}


\bibitem{dom} Le Hors, A., et al, 2000:
  \textit{Document Object Model (DOM) Level 2 Core Specification},
  \url{http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/}

\bibitem{gavoutypes} The GAVO Data Center Team, 2010: 
  \textit{STC utype generator}, 
  \url{http://vo.uni-hd.de/stctrans/q/utypes/form}

\end{thebibliography}
\end{document}
