diff --git a/Makefile b/Makefile index ebfa7a7..3bda93a 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,6 @@ FIGURES = role_diagram.svg VECTORFIGURES = # Additional files to distribute (e.g., CSS, schema files, examples...) -AUX_FILES = +AUX_FILES = VOEvent-v2.1.xsd VOEventRegExt-v2.0.xsd resrec-sample.vor include ivoatex/Makefile diff --git a/VOEvent.tex b/VOEvent.tex index ae71922..2bcbd2d 100644 --- a/VOEvent.tex +++ b/VOEvent.tex @@ -2,9 +2,10 @@ \input tthdefs \usepackage{hyperref} - -\lstloadlanguages{XML} -\lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False} +\usepackage{verbatim} +\lstloadlanguages{XML,SQL} +\lstset{flexiblecolumns=true,numberstyle=\small,showstringspaces=False, + identifierstyle=\texttt} \title{Sky Event Reporting Metadata (VOEvent)} @@ -1306,6 +1307,146 @@ \subsubsection{\tt name}\label{sec:3.9.5}[DEPRECATED] --- A short name as \end{lstlisting} +\section{Event Streams and the Registry} +\label{sec:registry-matters} + +In this section, we will reference several namespaced XML elements using +VO canonical prefixes. The prefixes used here are: + +\begin{itemize} +\item \verb|vr| -- \nolinkurl{http://www.ivoa.net/xml/VOResource/v1.0} +from \citet{2018ivoa.spec.0625P}. +\item \verb|vs| -- +\nolinkurl{http://www.ivoa.net/xml/VODataService/v1.1} +from \citet{todo:VODataService-1.2}. +\item \verb|xsi| -- +\nolinkurl{http://www.w3.org/2001/XMLSchema-instance}. +\end{itemize} + +The canonical prefix for the VOEvent registry extension is \verb|voe|, +which maps to the namespace URI +\nolinkurl{http://www.ivoa.net/xml/VOEventRegExt/v2}. + +\subsection{Registering Event Streams} +\label{sec:registering} + +Public VOEvent streams MUST be registered in the VO +Registry\footnote{For a hands-on introduction on how to do that, refer +to +\url{https://wiki.ivoa.net/twiki/bin/view/IVOA/GettingIntoTheRegistry}}. +This is necessary to + +\begin{compactitem} +\item ensure the validity of the event ids, as URIs with an \verb|ivo:| +scheme must resolve in a VO searchable registry to be valid +\citep{2016ivoa.spec.0523D}. +\item ensure the uniqueness of the event ids, as the event stream URI's +uniqueness is maintained using the Registry. +\item make the event streams enumeratable and findable. +\end{compactitem} + +It is recommended to register VOEvent streams using +\xmlel{vs:CatalogService} resources, as these allow service operators +to attach rich metadata like the originating facility and instrument, and +possibly extra stream metadata in a tableset. However, this +specification does not constrain the resource type. + +A public event stream MUST define a capability with standard id of +\nolinkurl{ivo://ivoa.net/std/VOEvent}. + +Note that path parts in IVOA identifiers are case-insensitive, and hence +when comparing ivoids, clients must ignore case. + +This specification does not constrain the type of the capability, but as +of this version, it is recommended to use plain \xmlel{vr:capability} +elements (i.e., not have \xmlel{xsi:type} attributes). + +Zero or more endpoints publishing the event stream are declared within +this capability element using \xmlel{vr:interface} elements with their +\xmlel{role} attributes set to \verb|std|; such standard interfaces MUST +be of type \xmlel{voe:StreamEndpoint} and then by the schema MUST have +a \xmlel{standardID} attribute, the value of which SHOULD reference one +of the keys in this standard's registry record, +\nolinkurl{ivo://ivoa.net/std/VOEvent}. + +As of this writing, these keys include: + +\begin{compactitem} +\item \verb|acc-vtp| The endpoint complies to IVOA VOEvent Transport + Protocol \citep{2017ivoa.spec.0320S} +\item \verb|acc-xmpp| The endpoint uses an informal method based on + XMPP (jabber). +\item \verb|acc-kafka| The endpoint uses Apache Kafka \citep{TODO}. +\item \verb|acc-proprietary| The endpoint is usable by some + method not (yet) mentioned in the VOEvent standard's registry record. +\end{compactitem} + +New keys may be added to the registry record by consensus between the +chairs of the IVOA DAL and Time Domain Working groups. + +Here is an example of a capability that will make a resource +discoverable as a VOEvent stream, with one endpoint each for VTP and +Kafka. The Kafka stream is also availble through some other +provider, perhaps to ensure high availability: + +\begin{lstlisting}[language=XML] + + + http://example.org/events/vtp + + + http://example.org/events/kafka + http://bigshot.com/streams/example-voe + + +\end{lstlisting} + +A full record describing a service running at the time of writing +comes with this +specification\footnote{\auxiliaryurl{resrec-sample.vor}}. This also +shows how to declare an archive of the VOEvents sent out. + +\subsection{Finding VOEvent Streams} + +Normatively, VOEvent streams are located in the VO Registry as resources +with capabilites whose \xmlel{standardID} attribute compares equal to +the VOEvent standard id \nolinkurl{ivo://ivoa.net/std/voevent}. + +This standard defines one mandatory details key for RegTAP +\citep{2019ivoa.spec.1011D}: \verb|capability/interface/standardID|. +Note that using this model, it is only possible to discover that a +service supports a given transport protocol but not to find out which +access URL corresponds to which transport protocol on multi-protocol +services. If a consumer must make this distinction, it will need to +retrieve the service's capabilities document and parse it itself. + +Using RegTAP, all registered VOEvent streams +can be located using a query like + +\begin{lstlisting}[language=SQL] +SELECT ivoid, res_title +FROM rr.resource + NATURAL JOIN rr.capability +WHERE standard_id='ivo://ivoa.net/std/voevent' +\end{lstlisting} + +To get URLs and titles of streams giving a subject containing supernova +in some way, use a query like + +\begin{lstlisting}[language=SQL] +SELECT res_title, access_url +FROM rr.resource + NATURAL JOIN rr.capability + NATURAL JOIN rr.interface + NATURAL JOIN rr.res_subject +WHERE + standard_id='ivo://ivoa.net/std/voevent' + AND 1=ivo_nocasematch(res_subject, '%supernova%') + AND role='std' +\end{lstlisting} + \section{VOEvent Example} \label{sec:4} This imaginary event is a brightness measurement of a past supernova from the diff --git a/VOEventRegExt-v2.0.xsd b/VOEventRegExt-v2.0.xsd new file mode 100644 index 0000000..ca11c87 --- /dev/null +++ b/VOEventRegExt-v2.0.xsd @@ -0,0 +1,54 @@ + + + + + + VOEventRegExt + xs + voe + + + Types for registering VOEvent services. + + + + + + + + + An endpoint through which a VOEvent stream can be followed. + + + Since VOEvent streams can be served through several + protocols, the actual protocol used on a particular endpoint + must be given in a standardID attribute. + + + + + + + + + A URI of the standard or convention this endpoint follows. + + + This will normally be a key from + ivo://ivoa.net/std/VOEvent starting with acc-. + + + + + + + + diff --git a/resrec-sample.vor b/resrec-sample.vor new file mode 100644 index 0000000..66217ec --- /dev/null +++ b/resrec-sample.vor @@ -0,0 +1,80 @@ + + Meteor Shower prediction + meteor_showers + ivo://vopdc.obspm/imcce/meteorshower/event + + Paris Astronomical Data Centre - IMCCE + + Jeremy Vaubaillon + + 2019-03-22T15:50:42 + + PADC support team +
77 av. Denfert Rochereau, 75014 Paris, FRANCE
+ vo.paris@observatoiredeparis.psl.eu + 0033140512082 + + + + Comet + Simulation + + This is an ephemeris of meteor showers occurring on solar + system planets, produced by simulating the ejection of + meteoroids from the sunlit hemisphere of cometary nuclei, typically + from 0 to 3 au, followed by the propagation of orbits of meteoroids + in the Solar System, taking into account the gravitation of the + Sun, the 8 planets, Pluto, and the Moon, as well as the radiation + pressure and the Poynting-Robertson drag. Note that asteroid parent + bodies were considered as active (i.e. comet-like bodies) even if + they are not active today. The showers are predicted when a planet + enters a large enough set of meteoroids, at a distance less than + typically 0.01 au. See Vaubaillon J., Colas F., Jorda L. 2005 A new + method to predict meteor showers. I. Description of the model, + Astronomy and Astrophysics, Volume 439/2 p.751-760, as well as: + Vaubaillon J. 2017 A confidence index for forecasting of meteor + showers, Planetary and Space Science, Volume 143 p.78-82 + + 2017P%26SS..143...78V + + http://voparis-tap-voevent.obspm.fr/tableinfo/meteor_showers.epn_core + + Other + Research + + + IsSourceOf + Meteor Shower prediction EPN-TAP service + + + + + + x-vtp://voparis-voevent-psws.obspm.fr:8099 + + + IMCCE + + Radio + Optical + Infrared + + + +