Skip to content

Appendix A.1 removed, LINK section revamped #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lmichel wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Appendix A.1 removed, LINK section revamped #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
197932a
ignore .project (eclipse)
lmichel Jun 24, 2026
0624072
Appendix A.1 (VOTable LINK substitutions) has been removed
lmichel Jun 24, 2026
7a6c2c6
Mentions of the possible use of the MIVOT datamodel mapping for
lmichel Jun 24, 2026
0bb5fc9
remove appendix A2 (VOTable Query Extension) and updateLINK section
lmichel Jul 16, 2026
4e8afe4
remove appendix A2 (VOTable Query Extension) and updateLINK section
lmichel Jul 16, 2026
947e8d4
Merge branch 'wd1.6/link' of git@github.com:lmichel/VOTable.git into …
lmichel Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ VOTable.html
*.fdb_latexmk
*.fls
*.swp
.project
203 changes: 54 additions & 149 deletions VOTable.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -931,17 +931,20 @@ \subsection{\elem{LINK} Element}
\label{elem:LINK}

The role of the {\elem{LINK}} element is to provide pointers
to external resources
through a URI. In VOTable, the {\elem{LINK}}
element may be part of a {\elem{RESOURCE}},
{\elem{TABLE}}, \elem{GROUP}, {\elem{FIELD}} or \elem{PARAM} element.
to resources outside of the VOTable
through a URI. {\elem{LINK}}
element may be child of {\elem{RESOURCE}},
{\elem{TABLE}}, \elem{GROUP}, {\elem{FIELD}} or \elem{PARAM}.

The linked URI is given by the \attr{href} attribute,
and the nature of the link is indicated by the \attr{content-role} attribute.
% @@@@@ how is contet role populated

\subsubsection{\elem{LINK} \attr{content-role} attribute}

The role and the nature of the link is indicated by the \attr{content-role} attribute.
The URI should ideally be dereferenceable,
but this is not an absolute requirement,
and appropriate use of the URI depends on the content-role.
This document defines two values for the \attr{content-role} attribute:
and appropriate use of the URI depends on the \attr{content-role}.
This document defines the following values for the \attr{content-role} attribute:

\begin{itemize}
\item \attrval{content-role}{doc} indicates documentation.
Expand All @@ -961,6 +964,7 @@ \subsection{\elem{LINK} Element}
\begin{verbatim}
<LINK content-role="type" href="https://www.ivoa.net/rdf/uat#parallax"/>
\end{verbatim}

\end{itemize}

A \attr{content-role} should be provided for all \elem{LINK} elements,
Expand All @@ -970,19 +974,49 @@ \subsection{\elem{LINK} Element}
for instance by the Semantics Working Group or as part of other
standards that make use of VOTable.

\subsubsection{\elem{LINK} \attr{content-type} attribute}

In addition the \elem{LINK} element
may announce the RFC 2046 media type of the data it references
with a \attr{content-type} attribute (e.g.\ \attrval{content-type}{image/fits}).
Although this might be overridden by metadata received during the
retrieval operation (e.g.\ the HTTP Content-Type header)
it can serve as a hint to the application about what to expect.

In the Astrores format, from which VOTable is derived,
there are additional semantics for the {\elem{LINK}}
element; the \elem{href} attribute is used as a template for creating
URLs. This behavior is explained in \Arefx{LINK},
and it represents
a possible extension of VOTable.
\subsubsection{\elem{LINK} \attr{href} attribute}

The linked URI is given by the \attr{href} attribute.
The URI can be either plain, or templated with parameters enclosed in braces {\tt{\$\{...\}}}.

\begin{itemize}

\item \textbf{Plain URI}: Plain URI is dereferenced as is, and the content
retrieved is used as appropriate for the \attr{content-role}.
For instance, if \attrval{content-role}{doc}, the content can be
presented to the user as documentation about the parent element of the \elem{LINK}.

\item \textbf{Templated URI}: Templated URI parameters are enclosed in braces, e.g.:
\begin{verbatim}
<LINK href="http://ivoa.net/lookup?Galaxy=${Name}&amp;RA=${RA}&amp;DE=${DE}"/>
\end{verbatim}
In this case, the URL parameters behave as an XML reference \attr{ref}.
It is the client's responsibility to replace the URI parameters with values
extracted from the referenced elements.
If the referenced element is a FIELD, the URI must be resolved using the data
from the current row in the columns identified by that FIELD.
This mechanism can connect individual table rows to specific information resources.
The standard does not specify how clients should behave when the URI cannot be resolved or when
the targeted element makes non sense in the \elem{LINK} context (e.g. \elem{TABLE}).

\end{itemize}


%In the Astrores format, from which VOTable is derived,
%there are additional semantics for the {\elem{LINK}}
%element; the \elem{href} attribute is used as a template for creating
%URLs. This behavior is explained in \Arefx{LINK},
%and it represents
%a possible extension of VOTable.

\subsection{\elem{TABLE} Element}
\label{elem:TABLE}
Expand Down Expand Up @@ -1130,8 +1164,6 @@ \subsection{Summary of Attributes}

\item The \attr{type} attribute is {\em not} part of this standard,
but is reserved for future extensions (see
\Arefx{LINK},
\Arefx{query} and
\Arefx{location}).

\end{itemize}
Expand Down Expand Up @@ -2365,7 +2397,6 @@ \subsection{Differences Between Versions 1.2 and 1.3}
the new {\tt serialization} parameter that can be used to specify
serialization type.
\item The representation of STC information in \Aref{example1}
and \Aref{query}
has been modified to reflect the recommended usage from the
{\em STC in VOTable} Note. This usage is recommended even for
VOTable 1.2, so this change to the VOTable document represents
Expand Down Expand Up @@ -2447,6 +2478,11 @@ \subsection{Differences Between Versions 1.5 and 1.6}
URI schemes (\Aref{sec:stream}).
\item Remove outdated comments from XSD file.
\item Minor editorial corrections.
\item Appendices A.1 (VOTable LINK substitutions) and A2 (VOTable Query Extension) have been removed
and the way to process templated URLs has been moved to \Aref{sec:link}
(\elem{LINK} element).
\item Mentions of the possible use of the MIVOT datamodel mapping for
representing complex data in VOTables (not normative).
\end{itemize}

% NOTE: IVOA recommendations must be cited from docrepo.bib
Expand Down Expand Up @@ -2477,137 +2513,6 @@ \section{Possible VOTable extensions}
%make use of the Web Services Description Language (WSDL)
%\end{quote}


\subsection{VOTable LINK substitutions}
\label{LINK}

\begin{quote}\em \fg{DarkBlue}
The \elem{LINK} element in Astrores \citep{astrores}
contains a mechanism for string substitution,
which is a powerful way of defining a link to external data
which adapts to each record contained in the table \elem{DATA}.
\end{quote}

When a {\elem{LINK}} element appears within a \elem{RESOURCE} or a
{\elem{TABLE}} element,
extra functionality is implied: the {\attr{href}}
attribute may not be a simple link, but instead
a template for a link. If, in the example of
\Aref{example1}, we add the link

\begin{verbatim}
<LINK href="http://ivoa.net/lookup?Galaxy=${Name}&amp;RA=${RA}&amp;DE=${DE}"/>
\end{verbatim}

\noindent a substitution filter is applied in the context of a particular row.
For the first row of the table, the substitution would result in the URL

\begin{verbatim}
http://ivoa.net/lookup?Galaxy=N%20224&RA=010.68&DE=%2b41.27
\end{verbatim}

Whenever the pattern {\tt{\$\{...\}}}
is found in the original link, the part in the braces is compared
with the set of {\attr{ID}} (preferably) or \attr{name}
attributes of the fields of the table. If a match is found, then the
value from that field of the selected row is used in place of the
{\tt{\$\{...\}}}. If no match is found, no substitution is made. Thus the
parser makes available to the calling application a value of the {\attr{href}}
attribute that depends on which row of the table has been selected.
Another way to think of it is that there is not a single link
associated with the table, but rather an implicitly defined new
column of the table. This mechanism can be used to connect each row
of the table to further information resources.

%The {\attr{action}} attribute is related to the Query mechanism described in
%the \Aref{query}.


The purpose of the link is defined by the {\attr{content-role}}
attribute. The allowed values are {\literalvalue{query}}
(see \Aref{query}),
{\literalvalue{hints}} for information for use by the application,
and {\literalvalue{doc}} for human-readable documentation.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Question: laisser un simple string dans l'attribut content-role ???
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%The first implies that string substitution should be used as defined
%above, and the latter two imply first that no substitution is needed,
%and that the link points to either information for use by the
%application ({\literalvalue{hints}})
%or human-readable documentation ({\literalvalue{doc}}).

The column names invoked in the pattern of the \attr{href} attribute
of the \elem{LINK} element should exist in the document to
generate meaningful links.
In the common case where the VOTable was generated from a query
of a database and contains only some of the columns in that
database, it might be necessary to include columns additional to
those requested in order to ensure that the LINKS in the VOTable
are operational.
Such a \elem{FIELD} included ``by necessity'' is marked with
the attribute \attrval{type}{hidden}. The primary key of
a relational table is a typical example of a \elem{FIELD}
which would carry the \attrval{type}{hidden} attribute.

\subsection{VOTable Query Extension}
\label{query}

\begin{quote}\em\fg{DarkBlue}
The metadata part included in a \elem{RESOURCE} contains
all the details necessary to create a {\em form} for querying
the resource. The addition of a link having the \attr{action}
attribute can turn VOTable into a powerful query interface.
\end{quote}

\noindent In Astrores \citep{astrores},
the details on the input parameters available in
queries are described by the
{\elem{PARAM}} and {\elem{FIELD}} elements, and the syntax used
to generate the actual query is described in the ASU procotol \citep{asu}:
the {\elem{FIELD}} or \elem{PARAM} elements are
paired in the form {\it name}{\tt{=}}{\it value},
where {\it name} is the contents of the
\attr{name} attribute of a \elem{FIELD} or \elem{PARAM},
and {\it value} represents a constraint
written with the ASU conventions (e.g. \literalvalue{<8}
or {\literalvalue{12.0..12.5}}
which denotes a range of values).
Such pairs are appended to the
{\attr{action}} specified in the {\elem{LINK}}
element contained in the {{\elem{RESOURCE}}},
separated by the ampersand (\&) symbol --
in a way quite similar to the HTML syntax used to
describe a {\elem{FORM}}.

A special \attrval{type}{no\_query} attribute of the
\elem{PARAM} or \elem{FIELD} elements marks the fields
which are {\em not} part of the form, i.e. are ignored
in the collection of {\it name}{\tt{=}}{\it value} pairs.

The following is an example of a transformation of the VOTable
in \Aref{example1} into a form interface:
\label{form1}
\begingroup\small
\verbatiminput{stc_example2.vot}
%\caption{\label{example1}A simple VOTable example}
\endgroup

\noindent Note that the {\elem{RESOURCE}} displaying the parameters accessible
for a query has the {\attrval{type}{meta}}
attribute; it is also assumed that only one {\elem{LINK}}
having the {\attrval{content-role}{query}}
attribute together with an {\attr{action}}
attribute exists within the current {\elem{RESOURCE}}.
The \elem{PARAM} with \attrval{name}{-out.max} has been added in this
example to control the size of the result.

A valid query generated by this VOTable could be:

\begin{verbatim}
myQuery?-source=myGalaxies&-out.max=50&R=10..100
\end{verbatim}

%\subsection{Additional Propositions}

\subsection{Arrays of Variable-Length Strings}
Expand Down Expand Up @@ -2715,7 +2620,7 @@ \subsection{FIELDs as Data Pointers}
prefix {\tt cid:} [RFC2111]

Note that the {\em VOTable LINK substitution} proposed in
\Aref{LINK} fills a similar functionality:
\Aref{sec:link} fills a similar functionality:
generate a pointer which can incorporate in its address components
from the \elem{DATA} part for the VOTable.

Expand Down
Loading