/[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 5192 by msdemlei, Thu Oct 25 12:38:16 2018 UTC revision 5193 by msdemlei, Thu Oct 25 13:39:27 2018 UTC
# Line 319  Line 319 
319  given object.  given object.
320    
321    
322  \lstinputlisting[language=XML,basicstyle=\footnotesize]{ipac-resource.xml}  \lstinputlisting[language=XML,basicstyle=\footnotesize,numbers=left]{ipac-resource.xml}
323    
324  This example illustrates some of the features of the VODataService  This example illustrates some of the features of the VODataService
325  extension:  extension:
326    
327  \begin{enumerate}  \begin{enumerate}
328  \item the extra namespaces associated with  \item The specific type of resource indicated by
        VODataService metadata.  
 \item the specific type of resource indicated by  
329         the value of the \xmlel{xsi:type} attribute; in this case         the value of the \xmlel{xsi:type} attribute; in this case
330         \xmlel{vs:CatalogService} indicates that this is         \xmlel{vs:CatalogService} indicates that this is
331         describing a service that accesses tabular data.         describing a service that accesses tabular data (line 1).
332  \item the location of the VOResource-related schema  \item The extra namespace declaration for with
333         documents used by this description,         VODataService metadata with the canonical prefix (line 5).
334  \item the core VOResource metadata,  \item The location of the VOResource-related schema
335  \item an interface described by the         documents used by this description (line 7ff.)
336    \item The core VOResource metadata (line 12ff.)
337    \item An interface described by the
338         VODataService type \xmlel{vs:ParamHTTP}; this         VODataService type \xmlel{vs:ParamHTTP}; this
339         type can indicate input arguments it supports.         type can indicate input arguments the service supports (line
340  \item a description of the         40ff.)
341    \item A description of the
342         coverage, including quantitative coverage         coverage, including quantitative coverage
343         plus waveband keywords.         plus waveband keywords (line 62ff.)
344  \item a description of the table that is returned  \item A description of the table that is returned
345         by the service.         by the service (line 73ff.)
346  \end{enumerate}  \end{enumerate}
347    
348  \subsection{The Schema Namespace and Location}  \subsection{The Schema Namespace and Location}
# Line 377  Line 378 
378  Authors of VOResource instance documents may choose to  Authors of VOResource instance documents may choose to
379  provide a location for the VOResource XML Schema document and its  provide a location for the VOResource XML Schema document and its
380  extensions using the  extensions using the
381  \xmlel{xsi:schemaLocation} attribute.  While the choice of  \xmlel{xsi:schemaLocation} attribute.  While authors are free to
382  the location value is the choice of the author, this specification  choose a location (as long as it resolves to the schema document), this
383    specification
384  recommends using the VODataService namespace URI as its location URL  recommends using the VODataService namespace URI as its location URL
385  (as illustrated in the example above), as in,  (as illustrated in the example above), as in,
386    
# Line 400  Line 402 
402    
403  The canonical prefix for VODataService is \xmlel{vs}; this means, in  The canonical prefix for VODataService is \xmlel{vs}; this means, in
404  particular, that in non-XML contexts (e.g., relational mappings  particular, that in non-XML contexts (e.g., relational mappings
405  like RegTAP) global VODataService elements \emph{must} be qualified with  like RegTAP) the VODataService types \emph{must} be qualified with
406  vs:.  The Registry Interfaces standard \citep{2018ivoa.spec.0723D} also  vs:.  The Registry Interfaces standard \citep{2018ivoa.spec.0723D} also
407  strongly recommends using the canonical prefixes in XML documents.  strongly recommends using the canonical prefixes in XML documents.
408    
# Line 442  Line 444 
444  \xmlel{vs:TableSet} consists of one or more (possibly anonymous)  \xmlel{vs:TableSet} consists of one or more (possibly anonymous)
445  \xmlel{vs:TableSchema} instances.  These have some very basic metadata  \xmlel{vs:TableSchema} instances.  These have some very basic metadata
446  (name, title, description, utype) and otherwise contain \xmlel{vs:Table}  (name, title, description, utype) and otherwise contain \xmlel{vs:Table}
447  instances.  These again have simple metadata, but mainly give column  instances.  These in turn have simple metadata, but mainly give column
448  metadata (including UCDs and units) in \xmlel{vs:TableParam}-typed  metadata (including UCDs and units) in \xmlel{vs:TableParam}-typed
449  elements.  These are the basis for enabling discovery queries like  children.  These are the basis for enabling discovery queries like
450  ``find all resources having redshifts and far infrared fluxes''.  ``find all resources having redshifts and far infrared fluxes''.
451    
452  Note that table and schema metadata is deliberately shallow.  If the  Note that table and schema metadata is deliberately shallow.  If the
# Line 453  Line 455 
455  data providers should define separate records for them as described in  data providers should define separate records for them as described in
456  the Note on Discovering Data Collections.  the Note on Discovering Data Collections.
457    
458  VODataService defines specialized interface type  VODataService further defines a specialized interface type
459  (inheriting from \xmlel{vr:Interface}) called  (inheriting from \xmlel{vr:Interface}) called
460  \xmlel{vs:ParamHTTP}.  This type is used to describe the commonly  \xmlel{vs:ParamHTTP}.  This type is used to describe
461  used interface that is invoked over HTTP as either a GET or a POST  straightforward HTTP interfaces directly operating on
462  in which the arguments are encoded as  arguments encoded as
463  \emph{name=value} pairs.  Such interface declarations should  \emph{name=value} pairs.  Such interface declarations can
464  enumerate the input arguments that are supported by the service  enumerate a service's input arguments, which enables clients
465  implementation; this is particularly useful in the generation of simple  to generate simple
466  user interfaces from VOSI capabilities responses.  user interfaces from VOSI capabilities responses.
467    
468  To be able to express the types of table columns and service arguments  To be able to express the types of table columns and service arguments
# Line 481  Line 483 
483    
484  While no common VO service discovery pattern relies on the type  of the  While no common VO service discovery pattern relies on the type  of the
485  resource,\footnote{Of course, in non-service discovery (e.g., authorities  resource,\footnote{Of course, in non-service discovery (e.g., authorities
486  or standards), resource types are important.} resources should  or standards), resource types are important.} resource
487  nevertheless choose an appropriate type for their resources.  At the  record authors should
488    nevertheless choose appropriate types for their resources.  At the
489  very least, this helps in Registry maintenance.  very least, this helps in Registry maintenance.
490    
491  VODataService provides four major resource classes; their derivation  VODataService provides four major resource classes; their derivation
# Line 490  Line 493 
493  that figure reflects whether a resource has an associated tableset  that figure reflects whether a resource has an associated tableset
494  (DataX vs.~CatalogX); you would typically use the DataX types when a  (DataX vs.~CatalogX); you would typically use the DataX types when a
495  resource does not naturally admit a relational structure.  The classical  resource does not naturally admit a relational structure.  The classical
496  example for this would be a couple of files on an FTP server.  CatalogX,  example for this would be a collection of files on an FTP server.  CatalogX,
497  on the other hand, has an associated tableset.  That does not mean that  on the other hand, has an associated tableset.  That does not mean that
498  it is limited to what is conventionally thought as a ``catalogue'',  it is limited to what is conventionally thought as a ``catalogue'',
499  i.e., a collection of metadata on astronomical objects.  On the  i.e., a collection of metadata on astronomical objects.  On the
500  contrary, CatalogX should also be used for collection of images,  contrary, CatalogX should also be used for collections of images,
501  spectra, time series, etc, as long as their metadata is sufficiently  spectra, time series, etc, as long as their metadata is sufficiently
502  structured.  Accessibility through IVOA standard protocols (ObsCore,  structured.  Accessibility through IVOA standard protocols (ObsCore,
503  SIAP, SSAP) certainly satisfies that requirement.  SIAP, SSAP) certainly satisfies that requirement.
# Line 506  Line 509 
509  TAP service or a collection of images or spectra within an ObsTAP  TAP service or a collection of images or spectra within an ObsTAP
510  service.  These should then have mainly auxiliary capabilities (where  service.  These should then have mainly auxiliary capabilities (where
511  a capability with a \xmlel{vr:WebBrowser}-typed interface to, say, an  a capability with a \xmlel{vr:WebBrowser}-typed interface to, say, an
512  form-based access point would certainly not hurt).  Choose XService when  form-based access point does not preclude the use of XResource).  
513    Choose XService when
514  there is a 1:1 relationship between the publishing service and the  there is a 1:1 relationship between the publishing service and the
515  published data.  published data or the resource published multiple data collections
516    registered in XResource records.
517    
518    
519  Two further resource classes in VODataService are deprecated in version  Two further resource classes defined VODataService 1.1,
520  1.2.    \xmlel{vs:DataCollection} and \xmlel{vs:StandardSTC},
521    are deprecated in version 1.2.  
 \xmlel{vs:DataCollection} was used in version 1.1 of this standard to  
 define simple collections of data, much like CatalogResource in the  
 current version.  It did not admit capabilities, though, and since the  
 addition of capabilities would essentially have a CatalogService clone  
 with a different child sequence, it was decided to abandon rather than  
 repair it.  
   
 \xmlel{vs:StandardSTC} was intended to declare standard combinations of  
 STC 1 reference frames and other coordinate metadata.  Since STC 1  
 coverage declaration is itself deprecated, so is \xmlel{vs:StandardSTC}.  
   
522  Resource record authors are requested to migrate or discard resource  Resource record authors are requested to migrate or discard resource
523  records using the deprecated types.  If all such records have  records using these deprecated types.  If all such records have
524  disappeared from the VO by version 1.3 of this specification, we may  disappeared from the VO by version 1.3 of this specification, their
525  remove the type declarations from the schema.  type declarations may be removed from the schema.
526    
527    
528  \section{The VODataService Metadata}  \section{The VODataService Metadata}
# Line 554  Line 548 
548  (like most VO services) or are tabular in nature (like usual  (like most VO services) or are tabular in nature (like usual
549  astronomical catalogs) should use \xmlel{vs:CatalogResource}.  astronomical catalogs) should use \xmlel{vs:CatalogResource}.
550    
551  The type is built on top of \xmlel{vr:Service}, so they can have  The type is derived from \xmlel{vr:Service}, which means that instances
552    can have
553  capabilities.  For \xmlel{vs:DataResource}, only auxiliary capabilities  capabilities.  For \xmlel{vs:DataResource}, only auxiliary capabilities
554  (e.g., TAP services giving access to the table) or plain capabilities  (e.g., TAP services giving access to the table) or plain capabilities
555  with \xmlel{vr:WebBrowser} interfaces should be given.  Resources with a  with \xmlel{vr:WebBrowser} interfaces should be given.  Resources with a
556  primary access mode dedicated to the resource should use  primary access mode dedicated to the resource's data content should use
557  \xmlel{vs:DataService}-typed resources.  \xmlel{vs:DataService}-typed resources.
558    
559  to the core VOResource service metadata the ability to associate an  In addition to \xmlel{vr:Service}'s content, DataResource adds
560  observing facility and/or instrument with the data as well as describe  elements for declaring the observing facilities and/or instruments used
561  the coordinate coverage of data via its child \xmlel{coverage}  to obtain the data, and it allows to declare
562  element.  Note that while these elements are all optional, a resource  the coordinate coverage of data via the \xmlel{coverage}
563  of this type still implies access to astronomical data.  element.
564    
565  % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource  % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource
566    \begin{generated}
567    \begingroup
568            \renewcommand*\descriptionlabel[1]{%
569            \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Documentation}
570    
571    \noindent{\small
572               A resource publishing astronomical data.
573             \par}
574    
575    \noindent{\small
576                This resource type should only be used if the resource has no
577                common underlying tabular schema (e.g., an inhomogeneous archive)
578                Use CatalogResource otherwise.
579             \par}
580    
581    \vspace{1ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Definition}
582    
583    \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
584    <xs:complexType name="DataResource" >
585      <xs:complexContent >
586        <xs:extension base="vr:Service" >
587          <xs:sequence >
588            <xs:element name="facility" type="vr:ResourceName" minOccurs="0"
589                      maxOccurs="unbounded" />
590            <xs:element name="instrument" type="vr:ResourceName" minOccurs="0"
591                      maxOccurs="unbounded" />
592            <xs:element name="coverage" type="vs:Coverage" minOccurs="0" />
593          </xs:sequence>
594        </xs:extension>
595      </xs:complexContent>
596    </xs:complexType>
597    \end{lstlisting}
598    
599    \vspace{0.5ex}\noindent\textbf{\xmlel{vs:DataResource} Extension Metadata Elements}
600    
601    \begingroup\small\begin{bigdescription}\item[Element \xmlel{facility}]
602    \begin{description}
603    \item[Type] string with ID attribute: vr:ResourceName
604    \item[Meaning]
605                         the observatory or facility used to collect the data
606                         contained or managed by this resource.  
607                      
608    \item[Occurrence] optional; multiple occurrences allowed.
609    
610    \end{description}
611    \item[Element \xmlel{instrument}]
612    \begin{description}
613    \item[Type] string with ID attribute: vr:ResourceName
614    \item[Meaning]
615                         the Instrument used to collect the data contain or
616                         managed by a resource.  
617                      
618    \item[Occurrence] optional; multiple occurrences allowed.
619    
620    \end{description}
621    \item[Element \xmlel{coverage}]
622    \begin{description}
623    \item[Type] composite: \xmlel{vs:Coverage}
624    \item[Meaning]
625                         Extent of the content of the resource over space, time,
626                         and frequency.
627                      
628    \item[Occurrence] optional
629    
630    \end{description}
631    
632    
633    \end{bigdescription}\endgroup
634    
635    \endgroup
636    \end{generated}
637    
638  % /GENERATED  % /GENERATED
639    
640  \subsubsection{DataService}  \subsubsection{DataService}
# Line 575  Line 642 
642  The \xmlel{vs:DataService} resource type has the same content model as  The \xmlel{vs:DataService} resource type has the same content model as
643  \xmlel{vs:DataResource}.  It should be used instead of  \xmlel{vs:DataResource}.  It should be used instead of
644  \xmlel{vs:DataResource} when the resource's capabilties give  \xmlel{vs:DataResource} when the resource's capabilties give
645  access to (essentially) only the resource's data, as for instance an  access to (essentially) only the resource's data, as for instance
646  ``SSAP service for the XY instrument'', of for a service giving access  ``ftp service for the XY instrument'', or for a service giving access
647  to multiple resources; in this latter case, make the resource-level  to multiple resources; in this latter case, the resource-level
648  metadata should pertain to the service itself rather than any specific  metadata should pertain to the service itself rather than any specific
649  data collection served by it.  data collection served by it.
650    
# Line 585  Line 652 
652  data, the \xmlel{vs:CatalogService} resource type should be used in  data, the \xmlel{vs:CatalogService} resource type should be used in
653  preference to \xmlel{vs:DataService}.  preference to \xmlel{vs:DataService}.
654    
655  For DataService's content model, refer to sect.~\ref{sect:DataResource}.  DataService's content model is exactly the one of
656    \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}.
657    
658    
659    
# Line 598  Line 666 
666  resource containing astronomical data or metadata in a set of one or  resource containing astronomical data or metadata in a set of one or
667  more tables.  It extends \xmlel{vs:DataResource} and thus has metadata  more tables.  It extends \xmlel{vs:DataResource} and thus has metadata
668  on coverage and the facilities and instruments that produced the  on coverage and the facilities and instruments that produced the
669  resource.  In addition to \xmlel{vs:DataResource}, this type allows the  resource.  Additionally, this type allows the
670  declaration of the metadata of the table(s) underlying the data or  declaration of the metadata of the table(s) underlying the data or
671  delivered by it in a tableset element.  delivered by it in a tableset element.
672    
673  As with \xmlel{vs:DataResource}, this type should only be used if all  As with \xmlel{vs:DataResource}, this type should only be used if all
674  capabilities declared in the resource are either auxiliary or  capabilities declared in the resource are either auxiliary or
675  nonstandard.  Use \xmlel{vs:CatalogService} instead.  nonstandard.  This is typically the case for catalogs or data
676    collections with in larger TAP, ObsTAP, or perhaps SIAP services.  When
677    a service only publishes a single resource, use the
678    \xmlel{vs:CatalogService} type.
679    
680  This is the type that should be used for publishing data collections  This is the type that should be used for publishing data collections
681  according to the IVOA Note on Discovering Data Collections  according to the IVOA Note on Discovering Data Collections
# Line 615  Line 686 
686  \begin{generated}  \begin{generated}
687  \begingroup  \begingroup
688          \renewcommand*\descriptionlabel[1]{%          \renewcommand*\descriptionlabel[1]{%
689          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:CatalogService} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Documentation}
690    
691  \noindent{\small  \noindent{\small
692              A service that interacts with with astronomical data              A resource giving astronomical data in tabular form.
             through one or more specified tables.  
693           \par}           \par}
694    
695  \noindent{\small  \noindent{\small
696              A table with sky coverage typically have columns that give              While this includeds classical astronomical catalogues,
697              longitude-latitude positions in some coordinate system.                this resource is also appropriate for collections of observations
698                or simulation results provided their metadata are available
699                in a sufficiently structured form (e.g., Obscore, SSAP, etc).
700           \par}           \par}
701    
702  \vspace{1ex}\noindent\textbf{\xmlel{vs:CatalogService} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Definition}
703    
704  \begin{lstlisting}[language=XML,basicstyle=\footnotesize]  \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
705  <xs:complexType name="CatalogService" >  <xs:complexType name="CatalogResource" >
706    <xs:complexContent >    <xs:complexContent >
707      <xs:extension base="vs:DataService" >      <xs:extension base="vs:DataResource" >
708        <xs:sequence >        <xs:sequence >
709          <xs:element name="tableset" type="vs:TableSet" minOccurs="0" >          <xs:element name="tableset" type="vs:TableSet" minOccurs="0" >
710            <xs:unique name="CatalogService-schemaName" >            <xs:unique name="CatalogService-schemaName" >
# Line 650  Line 722 
722  </xs:complexType>  </xs:complexType>
723  \end{lstlisting}  \end{lstlisting}
724    
725  \vspace{0.5ex}\noindent\textbf{\xmlel{vs:CatalogService} Extension Metadata Elements}  \vspace{0.5ex}\noindent\textbf{\xmlel{vs:CatalogResource} Extension Metadata Elements}
726    
727  \begingroup\small\begin{bigdescription}\item[Element \xmlel{tableset}]  \begingroup\small\begin{bigdescription}\item[Element \xmlel{tableset}]
728  \begin{description}  \begin{description}
# Line 678  Line 750 
750    
751  \subsubsection{CatalogService}  \subsubsection{CatalogService}
752    
753  The \xmlel{vs:CatalogResource} resource type is for describing a  The \xmlel{vs:CatalogService} resource type is for describing a
754  service publishing astronomical data or metadata based on tabular  service publishing astronomical data or metadata based on tabular
755  representations.  Its relationship is as between \xmlel{vs:DataResource}  representations.  Its relationship to \xmlel{vs:CatalogResource}
756    is as between \xmlel{vs:DataResource}
757  and \xmlel{vs:DataService}: Use \xmlel{vs:CatalogService} when either  and \xmlel{vs:DataService}: Use \xmlel{vs:CatalogService} when either
758  the resource's capabilties are exclusive to the resource described by  the resource's capabilties are exclusive to the resource described by
759  the resource-level metadata (``SSAP service for the XY instrument'') or  the resource-level metadata (``SSAP service for the XY instrument'') or
# Line 691  Line 764 
764  This is the type that should be used for typical, one-resource VO  This is the type that should be used for typical, one-resource VO
765  services.  services.
766    
767  For CatalogService's content model, refer to  CatalogService's content model is exactly the one of
768  sect.~\ref{sect:CatalogResource}.  \xmlel{vs:CatalogResource}; please refer to sect.~\ref{sect:CatalogResource}.
769    
770  \subsubsection{DataCollection}  \subsubsection{DataCollection}
771  \label{sect:datacollection}  \label{sect:datacollection}
772    
773  The \xmlel{vs:DataCollection} type is deprecated and should no longer be  The \xmlel{vs:DataCollection} type is deprecated and should no longer be
774  used in new resource records.  Existing \xmlel{vs:DataCollection}-typed  used in new resource records.  It was used in version 1.1 to define
775    simple collections of data, much like \xmlel{vs:CatalogResource} in the
776    current version.  It did not admit capabilities, though, and since the
777    addition of capabilities would essentially have created a CatalogService
778    clone with a different child sequence, it was decided to abandon rather
779    than repair it.
780    
781    Existing \xmlel{vs:DataCollection}-typed
782  records should be migrated to \xmlel{vs:DataResource} or  records should be migrated to \xmlel{vs:DataResource} or
783  \xmlel{vs:CatalogResource} as appropriate.  The \xmlel{accessURL} child  \xmlel{vs:CatalogResource} as appropriate.  If \xmlel{accessURL}
784  of \xmlel{vs:DataCollection} (which is not part of any of the new  children are present in the
785  classes) should be replaced by a plain capability with a  \xmlel{vs:DataCollection}s,
786    they can be replaced with a plain capability with a
787  \xmlel{vr:WebBrowser}-typed interface.  \xmlel{vr:WebBrowser}-typed interface.
788    
789    This type may be removed from the schema when all resource records using
790    it have vanished from the VO Registry.
791    
792  \subsubsection{StandardSTC}  \subsubsection{StandardSTC}
793    
794  The \xmlel{vs:StandardSTC} type is deprecated and should no longer be  The \xmlel{vs:StandardSTC} type is deprecated and should no longer be
795  used in new resource records.  Since the XML serialisation of the STC 1  used in new resource records.  Since the XML serialisation of the STC 1
796  data model was never promoted to an IVOA recommendation, there also is  data model was never promoted to an IVOA recommendation, there also is
797  no properly standardised way of creating such records.  no properly standardised way of creating such records.  Since no such
798    records ever existed in the Registry, this type will probably be removed
799    from the schema in version 1.3 of this specification.
800    
801    
802    

Legend:
Removed from v.5192  
changed lines
  Added in v.5193

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