/[volute]/trunk/projects/registry/VODataService/VODataService.tex
ViewVC logotype

Diff of /trunk/projects/registry/VODataService/VODataService.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 5111 by msdemlei, Tue Aug 14 08:22:01 2018 UTC revision 5112 by msdemlei, Thu Aug 23 09:54:59 2018 UTC
# Line 211  Line 211 
211    
212  \begin{enumerate}  \begin{enumerate}
213  \item the extra namespaces associated with  \item the extra namespaces associated with
214         VODataService metadata; if STC coverage information         VODataService metadata.
         is not  
        included, then only the VODataService namespaced is needed.  
215  \item the specific type of resource indicated by  \item the specific type of resource indicated by
216         the value of the \xmlel{xsi:type} attribute; in this case         the value of the \xmlel{xsi:type} attribute; in this case
217         \xmlel{vs:CatalogService} indicates that this is         \xmlel{vs:CatalogService} indicates that this is
# Line 225  Line 223 
223         VODataService interface type, \xmlel{vs:ParamHTTP}; this         VODataService interface type, \xmlel{vs:ParamHTTP}; this
224         type can indicate input arguments it supports.         type can indicate input arguments it supports.
225  \item a description of the  \item a description of the
226         coverage, including an STC         coverage, including quantitative coverage
227         description plus waveband keywords.         plus waveband keywords.
228  \item a description of the table that is returned  \item a description of the table that is returned
229         by the service.         by the service.
230  \end{enumerate}  \end{enumerate}
# Line 289  Line 287 
287         cannot be overridden.  At this writing, there are no IVOA         cannot be overridden.  At this writing, there are no IVOA
288         applications in which this is the case.  Consult         applications in which this is the case.  Consult
289         appendix~\ref{vods10-compat} for more details on         appendix~\ref{vods10-compat} for more details on
290         compatibility issues.</dd>         compatibility issues.
291  \end{admonition}  \end{admonition}
292    
293    
# Line 323  Line 321 
321         \todo{deprecate}         \todo{deprecate}
322    
323  \item[\xmlel{vs:StandardSTC}]  \item[\xmlel{vs:StandardSTC}]
324  This resource type declares one or more coordinate systems described  This resource type was intended to declare standard combinations of
325         using STC \citep{2007ivoa.spec.1030R} such that each can be  STC 1 reference frames and other coordinate metadata.  It is no longer
326         assigned a globally unique identifier (based on the IVOA  in use and retained only for compatibility.  It may be removed in a
327         identifier for the resource record itself).  This identifier  later version of VODataService version 1.
        can then be referenced in any other STC description in lieu of  
        a fully described coordinate system.  Coordinate systems  
        described in this way become reusable standards once they are  
        registered in an IVOA registry.\todo{deprecate/remove}  
328  \end{bigdescription}  \end{bigdescription}
329    
330  The other two resource types represent specialized services:  The other two resource types represent specialized services:
# Line 358  Line 352 
352  the extent that data samples the measurement range of the sky (space),  the extent that data samples the measurement range of the sky (space),
353  frequency, and time.  The coverage metadata (encoded via the  frequency, and time.  The coverage metadata (encoded via the
354  \xmlel{vs:Coverage} type) has two parts.  The first part  \xmlel{vs:Coverage} type) has two parts.  The first part
355  allows a full STC profile description (via the imported STC element,  allows a full STC profile description in space, time, and energy.
356  \xmlel{stc:STCResourceProfile})\todo{deprecate}.  The second part  The second part
357  captures key coverage metadata defined in the IVOA Resource Metadata  captures key coverage metadata defined in the IVOA Resource Metadata
358  standard \citep{2007ivoa.spec.0302H}.  The RM-derived coverage elements can  standard \citep{2007ivoa.spec.0302H}.  The RM-derived coverage elements can
359  be considered summarizing metadata for many of the details that  be considered summarizing metadata for many of the details that
# Line 368  Line 362 
362    
363    
364    
 The detailed STC profile contained within the  
 \xmlel{stc:STCResourceProfile} element is capable of  
 describing coverage not only in space, time, and frequency but also  
 velocity and redshift.  The profile contains up to three types of  
 component descriptions:  
 coordinate systems, coordinate values, and coordinate areas or ranges.  
 The first component describes the coordinate systems to which coordinate  
 values, areas, and regions are referenced.  While any arbitrary  
 system can be described in this first part, it is expected that most  
 VODataService instances will provide a simple pointer to a predefined  
 system in a registered \xmlel{vs:StandardSTC} record (using the  
 mechanism summarized in section~\ref{todo} below).  The coordinate values  
 part will usually be used to describe the coordinate resolution,  
 errors, or typical sizes.  The coordinate areas part describes actual  
 regions or ranges covered by the resource in any of the given  
 coordinate systems.    
   
365    
366  Table descriptions appear within a single \xmlel{tableset}  Table descriptions appear within a single \xmlel{tableset}
367  element.  This element can in turn can contain one or more  element.  This element can in turn can contain one or more
# Line 670  Line 647 
647  the \xmlel{vs:TableSet} type for describing tables.    the \xmlel{vs:TableSet} type for describing tables.  
648    
649    
 \subsubsection{StandardSTC}  
 \label{sect:standardstc}  
   
   
 The \xmlel{vs:StandardSTC} resource type is used to register standard  
 coordinate systems, positions, or regions using the Space-Time  
 Coordinate standard schema \citep{2007ivoa.spec.1030R} so that  
 they can by uniquely referenced by name by other resource descriptions  
 or applications.  This resource type extends the core metadata with a  
 single element, \xmlel{stcDefinitions}, which contains  
 the STC definitions.    
   
   
 % GENERATED: !schemadoc VODataService-v1.2.xsd StandardSTC  
 \begin{generated}  
 \begingroup  
         \renewcommand*\descriptionlabel[1]{%  
         \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:StandardSTC} Type Schema Documentation}  
   
 \noindent{\small  
            a description of standard space-time coordinate systems,  
            positions, and regions.  
          \par}  
   
 \noindent{\small  
            This resource provides a mechanism for registering standard  
            coordinate systems which other resources may reference as  
            part of a coverage descripiton.  In particular, coverage  
            descriptions will refer to components of the STC  
            descriptions in this resource via an IVOA identifier.  It  
            is intended that an application consuming such coverage  
            descriptions be able to semantically interpret the  
            identifier without resolving it.  For this reason, once a  
            standard STC description is registered with this resource  
            type, updating the description is strongly discouraged.    
          \par}  
   
 \vspace{1ex}\noindent\textbf{\xmlel{vs:StandardSTC} Type Schema Definition}  
   
 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]  
 <xs:complexType name="StandardSTC" >  
   <xs:complexContent >  
     <xs:extension base="vr:Resource" >  
       <xs:sequence >  
         <xs:element name="stcDefinitions"  
                   type="stc:stcDescriptionType"  
                   minOccurs="1"  
                   maxOccurs="unbounded" />  
       </xs:sequence>  
     </xs:extension>  
   </xs:complexContent>  
 </xs:complexType>  
 \end{lstlisting}  
   
 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:StandardSTC} Extension Metadata Elements}  
   
 \begingroup\small\begin{bigdescription}\item[Element \xmlel{stcDefinitions}]  
 \begin{description}  
 \item[Type] \xmlel{stc:stcDescriptionType}  
 \item[Meaning]  
                        An STC description of coordinate systems,  
                        positions, and/or regions  
                       
 \item[Occurrence] required; multiple occurrences allowed.  
 \item[Comment]  
                        Each system, position, and region description  
                        should have a an XML ID assigned to it.  
                       
 \item[Comment]  
                        Because the STC schema sets  
                        elementFormDefault={"}qualified{"}, it is  
                        recommended that this element specify the STC  
                        default namespace via an xmlns namespace.  
                       
   
 \end{description}  
   
   
 \end{bigdescription}\endgroup  
   
 \endgroup  
 \end{generated}  
   
 % /GENERATED  
   
   
 The curation metadata that is part of the core VODataService should  
 generally refer to the publishing organization and persons that are  
 responsible for defining the systems, updating the definitions as  
 needed, and responding to user questions about the definitions.  The  
 content metadata, in particular the textual contents of the  
 \xmlel{description} element, should describe the purpose  
 of the definition and where references to the defined systems,  
 positions, or regions may be used.    
   
   
 The content of the \xmlel{stcDefinitions} element is  
 controlled by the STC schema.  Because that schema uses the  
 \verb|elementFormDefault="true"| and most of the STC elements  
 are defined to be global,  
 \xmlel{stcDefinitions} child elements must be qualified  
 as being in the STC namespace  
 (http://www.ivoa.net/xml/STC/stc-v1.30.xsd), by either setting the  
 default namespace (via the \xmlel{xmlns} attribute) or via  
 explicit qualification via a prefix (see example).    
   
650    
651  \subsubsection{DataService}  \subsubsection{DataService}
 DataService">  
652    
653    
654  The \xmlel{vs:DataService} resource type is for describing a  The \xmlel{vs:DataService} resource type is for describing a
# Line 945  Line 815 
815  The definition of \xmlel{tableset} element forces certain  The definition of \xmlel{tableset} element forces certain
816  names within its description to be unique; these constraints are explained  names within its description to be unique; these constraints are explained
817  further in section~\ref{sect:unique}.  further in section~\ref{sect:unique}.
   
818  \subsection{Coverage}  \subsection{Coverage}
819  \label{sect:cover}  \label{sect:cover}
820    
821    
822  The \xmlel{vs:Coverage} type describes how the data samples the  The \xmlel{vs:Coverage} type summarily describes how the data served is
823  sky, frequency, and time.    distributed on the
824    sky, in energy, and in time.  For the energy coverage, there is a
825    qualitative classification in the \xmlel{waveband} \todo{Worry
826    about non-EM messengers in waveband (use a vocabulary?)} element.
827    
828    Historically, the quantitative footprints were expected to be given in
829    the element of type \xmlel{stc:STCResourceProfile}.  As discussed in
830    \citet{note:regstc}, this expectation turned out to be erroneous,
831    and the underlying standard \citep{note:stcx} never proceeded to become
832    a recommendation.  Hence, this version of VODataService deprecates the
833    use of \xmlel{STCResourceProfile}.
834    
835    Instead, resource record authors are strongly encouraged to provide
836    coverage information in the \xmlel{spatial}, \xmlel{spectral}, and
837    \xmlel{temporal} children of \xmlel{coverage}.
838    
839    Spatial coverage is conveyed as a MOC.  To enable easy embedding into
840    resource records written in VOResource (i.e., XML),
841    we represent MOCs in the ASCII convention
842    proposed in the MOC specification \citep{2014ivoa.spec.0602F}.\todo{We
843    need a REC to cite -- DALI? us? VOTable?}
844    
845    By default, the MOCs are to be interpreted in the ICRS.  It is forseen
846    that future extensions \todo{We should really do this now -- proposals,
847    anyone?} to this will allow non-celestial frames (e.g., on planet
848    surfaces).  However, whenever a resource's coordinates can be expressed
849    as ICRS (e.g., Galactic or Ecliptic coordinates of extrasolar objects),
850    the coverage must be expressed in the ICRS.
851    
852    An important characteristic of MOCs is the order of the smallest scale
853    (the ``MOC resolution'').  Higher orders yield more faithful
854    representations of the actual coverage, but also lead to a possibly
855    significant increase of the size of the serialised MOC.  We suggest a
856    ``typical resolution'' of the Registry of about a degree (i.e., MOC
857    order 6), but resources are free to choose a higher maximum orders if
858    appropriate and the resource record size remains reasonable.
859    
860    Resources that need to communicate high-resolution spatial coverage,
861    perhaps for some non-discovery use case, can use the \xmlel{footprint}
862    element with its \xmlel{ivo-id} attribute set to
863    \nolinkurl{ivo://ivoa.net/std/moc} to declare a URL giving a MOC
864    footprint of arbitrary level and size; however, MOCs returned from
865    footprint services must be in the MOC FITS serialisation.
866    
867    Time and spectral coverage are modeled as unions of simple
868    intervals over real numbers; the serialisation here is a space-separated
869    pair of floating point numbers as governed by the DALI \emph{interval}
870    xtype.
871    
872    Times are given in Barycentric Dynamical Time (TDB) at the solar system
873    barycenter.  They must be specified as Modified Julian Dates.  Since
874    discovery use cases in which high-precision times are required are not
875    forseen, resource record authors are encouraged to pad their actual
876    temporal coverage such that differences in time scales (of the order of
877    10s of seconds) or reference positions (of the order of minutes between
878    ground-based observatories and the barycenter) do not matter.  In other
879    words, the temporal resolution of the Registry at this point should be
880    assumed to be of order 10 minutes.
881    
882    Deviating from common VO practice (which currently fairly consistently
883    uses wavelengths of elecromagnetic waves in vacuum), spectral limits are
884    given in Joules of particle energy.  This is intended to allow seamless
885    integration of non-electromagnetic messengers.  The reference position
886    for the spectral axis is the solar system barycenter.  Again, discovery
887    use cases on a level where the difference between reference frames of
888    ground-based observatories versus the solar system barycenter matters
889    are not forseen, and resource record authors are advised to pad their
890    intervals on that level.
891    
892  % GENERATED: !schemadoc VODataService-v1.2.xsd Coverage  % GENERATED: !schemadoc VODataService-v1.2.xsd Coverage
893  \begin{generated}  \begin{generated}
# Line 973  Line 907 
907  <xs:complexType name="Coverage" >  <xs:complexType name="Coverage" >
908    <xs:sequence >    <xs:sequence >
909      <xs:element ref="stc:STCResourceProfile" minOccurs="0" />      <xs:element ref="stc:STCResourceProfile" minOccurs="0" />
910        <xs:element name="spatial" type="xs:string" minOccurs="0" />
911        <xs:element name="temporal" type="xs:string" minOccurs="0"
912                  maxOccurs="unbounded" />
913        <xs:element name="spectral" type="xs:string" minOccurs="0"
914                  maxOccurs="unbounded" />
915      <xs:element name="footprint" type="vs:ServiceReference" minOccurs="0" />      <xs:element name="footprint" type="vs:ServiceReference" minOccurs="0" />
916      <xs:element name="waveband" type="vs:Waveband" minOccurs="0"      <xs:element name="waveband" type="vs:Waveband" minOccurs="0"
917                maxOccurs="unbounded" />                maxOccurs="unbounded" />
# Line 987  Line 926 
926  \begin{description}  \begin{description}
927  \item[Type]  \item[Type]
928  \item[Meaning]  \item[Meaning]
929                   The STC description of the location of the resource's                   An STC 1.0 description of the location of the resource's
930                   data (or behavior on data) on the sky, in time, and in                   data on the sky, in time, and in frequency space,
931                   frequency space, including resolution.                   including resolution.   This is deprecated in favour
932                     of the separate spatial, temporal, and spectral elements.
933                                
934  \item[Occurrence] optional  \item[Occurrence] optional
935    
936    \end{description}
937    \item[Element \xmlel{spatial}]
938    \begin{description}
939    \item[Type] string: \xmlel{xs:string}
940    \item[Meaning]
941                      An ASCII-serialised MOC defining the spatial coverage
942                      of the resource.
943                  
944    \item[Occurrence] optional
945    \item[Comment]
946                      The MOC is to be understood in the ICRS reference frame.
947                      Resources should give the coverage at least to order 6
948                      (a resolution of about one degree).  The order should be
949                      chosen so as to keep the resulting MOC smaller than a few
950                      dozens of kB.  If desired, a more precise MOC can be provided
951                      on a dedicated endpoint declared in the footprint element.
952                  
953    
954    \end{description}
955    \item[Element \xmlel{temporal}]
956    \begin{description}
957    \item[Type] string: \xmlel{xs:string}
958    \item[Meaning]
959                      A pair of lower, upper limits of a time interval
960                      for which the resource offers data.
961                  
962    \item[Occurrence] optional; multiple occurrences allowed.
963  \item[Comment]  \item[Comment]
964                   In general, this description should be approximate; a                    This is written as for VOTable tabledata (i.e.,
965                   more precise description can be provided by the                    white-separated C-style floating point literals).
966                   footprint service.                      The limits must be given as MJD.  While they
967                      are not intended to be precise, they are to be understood
968                      in TDB for the solar system barycenter.  The total coverage
969                      of the resource is the union of all such intervals.
970                  
971    
972    \end{description}
973    \item[Element \xmlel{spectral}]
974    \begin{description}
975    \item[Type] string: \xmlel{xs:string}
976    \item[Meaning]
977                      A pair of lower, upper limits of a spectral interval
978                      for which the resource offers data.
979                  
980    \item[Occurrence] optional; multiple occurrences allowed.
981    \item[Comment]
982                      This is written as for VOTable tabledata (i.e.,
983                      white-separated C-style floating point literals).
984                      The limits must be given in Joules of particle
985                      energies.  While the limits are not intended
986                      to be precise, they are to be understood for the
987                      solar system barycenter.
988                  
989    \item[Comment]
990                      For instance, the Johnson V waveband (480 .. 730 nm)
991                      would be specified as {"}2.72e-19 4.14e-19{"}
992                                
993    
994  \end{description}  \end{description}
# Line 1091  Line 1084 
1084    
1085  % /GENERATED  % /GENERATED
1086    
 A detailed, systematic description of coverage is provided via the  
 child \xmlel{stc:STCResourceProfile} element, taken from  
 the STC schema, version 1.3, with the namespace,  
 \xmlel{http://www.ivoa.net/xml/STC/stc-v1.30.xsd} (hereafter  
 referred using the \xmlel{stc:} prefix).  This element is defined  
 in the STC schema as a global element; furthermore, the STC schema  
 sets its global \verb|elementFormDefault="qualified"|.  
 Consequently, the \xmlel{stc:STCResourceProfile} element  
 and all its child elements must be qualified as part of the STC  
 namespace as required by XML Schema.  
 In applications where common use of XML prefixes is required or  
 encouraged (e.g. the IVOA Registry Interfaces \citep{todo:RI1.1}),  
 use of the \xmlel{stc:} prefix to represent the STC namespace is  
 encouraged.    
   
   
 \begin{admonition}{Note}  
 The STC scheme provides rich mark-up for expressing the  
        details of the coverage.  In particular, the mark-up is quite  
        flexible in the units that can be used.  For example, spectral  
        coverage can be given in terms of frequency, wavelength, or  
        energy.  While it is recommended that the overall description  
        given in the \xmlel{stc:STCResourceProfile} be  
        fairly general and approximate, leveraging the richness for a  
        detailed description is allowed.  
 \end{admonition}  
   
   
   
 The remaining elements provide some summary information about the  
 coverage.  
   
   
   
 \begin{admonition}{Note on Footprint Service}  
 The \xmlel{footprint} element has been defined in  
        anticipation of a future standard IVOA footprint service  
        protocol that can be used to respond to detailed spatial  
        overlap queries.  Consequently, in the future, applications may  
        be able to assume the protocol that footprint service URL  
        supports.  When an application is unable to make any  
        assumptions, the IVOA Identifier given by the attribute should  
        be resolved and the returned resource description should be  
        searched for a recognized footprint service capability.</dd>  
 \end{admonition}  
   
1087  \subsection{Tabular Data}  \subsection{Tabular Data}
1088  \label{sect:table}  \label{sect:table}
1089    
# Line 2739  Line 2686 
2686  \subsection{Changes from REC-1.1}  \subsection{Changes from REC-1.1}
2687    
2688  \begin{itemize}  \begin{itemize}
2689    \item Deprecating STCResourceProfile and replacing it with
2690    \xmlel{spatial}, \xmlel{temporal}, and \xmlel{spectral} elements.
2691  \item Ported source to \ivoatex.  \item Ported source to \ivoatex.
2692  \end{itemize}  \end{itemize}
2693    

Legend:
Removed from v.5111  
changed lines
  Added in v.5112

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26