ivoa-std · Zarquan · Nov 9, 2020 · May 6, 2020 · May 6, 2020 · May 6, 2020
diff --git 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
@@ -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
 </VOEvent> 
 \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]
+<capability standardID="ivo://ivoa.net/std/voevent">
+  <interface xsi:type="voe:StreamEndpoint" role="std"
+      standardID="ivo://ivoa.net/std/voevent#acc-vtp">
+    <accessURL>http://example.org/events/vtp</accessURL>
+  </interface>
+  <interface xsi:type="voe:StreamEndpoint" role="std"
+      standardID="ivo://ivoa.net/std/voevent#acc-vtp">
+    <accessURL>http://example.org/events/kafka</accessURL>
+    <accessURL>http://bigshot.com/streams/example-voe</accessURL>
+  </interface>
+</capability>
+\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
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
+           xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
+           xmlns:voe="http://www.ivoa.net/xml/VOEventRegExt/v2"
+           xmlns:vm="http://www.ivoa.net/xml/VOMetadata/v0.1"
+           targetNamespace="http://www.ivoa.net/xml/VOEventRegExt/v2"
+           elementFormDefault="unqualified" attributeFormDefault="unqualified"
+           version="2.0pre1">
+
+   <xs:annotation>
+      <xs:appinfo>
+        <vm:schemaName>VOEventRegExt</vm:schemaName>
+        <vm:schemaPrefix>xs</vm:schemaPrefix>
+        <vm:targetPrefix>voe</vm:targetPrefix>
+      </xs:appinfo>
+      <xs:documentation>
+     	  Types for registering VOEvent services.
+      </xs:documentation>
+   </xs:annotation>
+
+   <xs:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
+              schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0"/>
+
+   <xs:complexType name="StreamEndpoint">
+      <xs:annotation>
+         <xs:documentation>
+            An endpoint through which a VOEvent stream can be followed.
+         </xs:documentation>
+         <xs:documentation>
+            Since VOEvent streams can be served through several
+            protocols, the actual protocol used on a particular endpoint
+            must be given in a standardID attribute.
+         </xs:documentation>
+      </xs:annotation>
+
+      <xs:complexContent>
+         <xs:extension base="vr:Interface">
+            <xs:attribute name="standardID" type="xs:anyURI" use="required">
+               <xs:annotation>
+                  <xs:documentation>
+                     A URI of the standard or convention this endpoint follows.
+                  </xs:documentation>
+                  <xs:documentation>
+                     This will normally be a key from 
+                     ivo://ivoa.net/std/VOEvent starting with acc-.
+                  </xs:documentation>
+               </xs:annotation>
+            </xs:attribute>
+         </xs:extension>
+      </xs:complexContent>
+   </xs:complexType>
+</xs:schema>
+<!-- vim:et:sw=3
+-->
diff --git a/resrec-sample.vor b/resrec-sample.vor
@@ -0,0 +1,80 @@
+<ri:Resource
+    xmlns:voe="http://www.ivoa.net/xml/VOEventRegExt/v2"
+    xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0"
+    xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
+    xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    created="2020-10-28T15:11:00Z"
+    status="active"
+    updated="2020-10-28T15:11:00Z"
+    xsi:type="vs:CatalogService">
+    <title>Meteor Shower prediction</title>
+    <shortName>meteor_showers</shortName>
+    <identifier>ivo://vopdc.obspm/imcce/meteorshower/event</identifier>
+    <curation>
+        <publisher ivo-id="ivo://vopdc.obspm/imcce"
+          >Paris Astronomical Data Centre - IMCCE</publisher>
+        <creator>
+            <name>Jeremy Vaubaillon</name>
+        </creator>
+        <date role="updated">2019-03-22T15:50:42</date>
+        <contact>
+            <name>PADC support team</name>
+            <address>77 av. Denfert Rochereau, 75014 Paris, FRANCE</address>
+            <email>[email protected]</email>
+            <telephone>0033140512082</telephone>
+        </contact>
+    </curation>
+    <content>
+        <subject>Comet</subject>
+        <subject>Simulation</subject>
+        <description>
+            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
+        </description>
+        <source format="bibcode">2017P%26SS..143...78V</source>
+        <referenceURL>
+          http://voparis-tap-voevent.obspm.fr/tableinfo/meteor_showers.epn_core
+        </referenceURL>
+        <type>Other</type>
+        <contentLevel>Research</contentLevel>
+        <relationship>
+            <!-- TAP service containing/archiving all previous
+              events produced by this stream -->
+            <relationshipType>IsSourceOf</relationshipType>
+            <relatedResource ivo-id="ivo://vopdc.obspm/imcce/meteorshower/epn"
+              >Meteor Shower prediction EPN-TAP service</relatedResource>
+        </relationship>
+    </content>
+    <capability standardID="ivo://ivoa.net/std/VOEvent">
+        <!-- TODO: figure out if this needs a declaration like
+          "This is VOEvent 2 in XML serialisation" – or if that's
+          implied in something else we're saying here -->
+        <interface role="std" xsi:type="voe:StreamEndpoint"
+          standardID="ivo://ivoa.net/std/VOEvent#acc-vtp">
+            <accessURL>x-vtp://voparis-voevent-psws.obspm.fr:8099</accessURL>
+        </interface>
+    </capability>
+    <facility>IMCCE</facility>
+    <coverage>
+        <waveband>Radio</waveband>
+        <waveband>Optical</waveband>
+        <waveband>Infrared</waveband>
+    </coverage>
+</ri:Resource>
+
+<!-- vim:et:sw=2
+-->