/[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 5203 by msdemlei, Fri Oct 26 14:36:47 2018 UTC revision 5204 by msdemlei, Fri Oct 26 15:41:13 2018 UTC
# Line 387  Line 387 
387  choose a location (as long as it resolves to the schema document), this  choose a location (as long as it resolves to the schema document), this
388  specification  specification
389  recommends using the VODataService namespace URI as its location URL  recommends using the VODataService namespace URI as its location URL
390  (as illustrated in the example above), as in,  (as illustrated in the example above), as in
391    \begin{verbatim}
 \begin{lstlisting}[language=XML]  
392  xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1  xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
393                      http://www.ivoa.net/xml/VODataService/v1.1"                      http://www.ivoa.net/xml/VODataService/v1.1"
394  \end{lstlisting}  \end{verbatim}
395    
396    
397  \begin{admonition}{Note}  \begin{admonition}{Note}
# Line 411  Line 410 
410  vs:.  The Registry Interfaces standard \citep{2018ivoa.spec.0723D} also  vs:.  The Registry Interfaces standard \citep{2018ivoa.spec.0723D} also
411  strongly recommends using the canonical prefixes in XML documents.  strongly recommends using the canonical prefixes in XML documents.
412    
 Note also that in this document, the \xmlel{vr} prefix is used to  
 label, as shorthand, a type or element name that is defined in the  
 VOResource schema, as in \xmlel{vr:Resource}.  
   
   
   
   
413  As recommend by the VOResource standard, the  As recommend by the VOResource standard, the
414  VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.  VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.
415  This means that element names defined  This means that element names defined
# Line 444  Line 436 
436  indication of the spatial resolution within a service.  indication of the spatial resolution within a service.
437    
438  VODataService has several classes for the declaration of the tabular  VODataService has several classes for the declaration of the tabular
439  structure underlying a service; this can be the tables in a TAP service,  structure underlying a service; this can be the tables in a
440  or it can relate to the data structure returned by the service.  A  TAP-accessible resource,
441  \xmlel{vs:TableSet} consists of one or more (possibly anonymous)  or it can relate to the data structure returned by the service.  This
442    metadata is held in
443    \xmlel{vs:TableSet}-typed elements consisting
444    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 in turn have simple metadata, but mainly give column  instances.  These in turn have simple metadata, but mainly give column
# Line 486  Line 481 
481  \label{fig:rescls}  \label{fig:rescls}
482  \end{figure}  \end{figure}
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 XSD 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.} resource  or standards), resource types are important.} resource
487  record authors should  record authors should
488  nevertheless choose appropriate types for their resources.  At the  nevertheless choose appropriate types for their resources.  At the
489  very least, this helps in Registry maintenance.  very least, this helps Registry maintenance.
490    
491  VODataService provides four major resource classes; their derivation  VODataService provides four major resource classes; their derivation
492  tree is shown in Fig.~\ref{fig:rescls}.  The vertical distinction in  tree is shown in Fig.~\ref{fig:rescls}.  The vertical distinction in
# Line 500  Line 495 
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 collection 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 ``catalog'',
499  i.e., a collection of metadata on astronomical objects.  On the  i.e., a table of data on astronomical objects.  On the
500  contrary, CatalogX should also be used for collections 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,
# Line 517  Line 512 
512  form-based access point does not preclude the use of XResource).    form-based access point does not preclude the use of XResource).  
513  Choose XService when  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 or the resource published multiple data collections  published data, or if the service publishes multiple data collections
516  registered in XResource records.  registered in separate XResource records.
517    
518    
519  Two further resource classes defined VODataService 1.1,  Two further resource classes defined VODataService 1.1,
# Line 556  Line 551 
551  The type is derived from \xmlel{vr:Service}, which means that instances  The type is derived from \xmlel{vr:Service}, which means that instances
552  can have  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., DataServices serving multiple DataResources) 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's data content 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.
# Line 579  Line 574 
574    
575  \noindent{\small  \noindent{\small
576              This resource type should only be used if the resource has no              This resource type should only be used if the resource has no
577              common underlying tabular schema (e.g., an inhomogeneous archive)              common underlying tabular schema (e.g., an inhomogeneous archive).
578              Use CatalogResource otherwise.              Use CatalogResource otherwise.
579           \par}           \par}
580    
# Line 617  Line 612 
612  \begin{description}  \begin{description}
613  \item[Type] string with ID attribute: vr:ResourceName  \item[Type] string with ID attribute: vr:ResourceName
614  \item[Meaning]  \item[Meaning]
615                       the Instrument used to collect the data contain or                       the instrument used to collect the data contain or
616                       managed by a resource.                         managed by a resource.  
617                                        
618  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
# Line 653  Line 648 
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    
651  Note that whenever the service operates on clearly definable tabular  Whenever the service operates on clearly definable tabular
652  data, the \xmlel{vs:CatalogService} resource type should be used in  data, the resource should use the \xmlel{vs:CatalogService} resource type
653  preference to \xmlel{vs:DataService}.  in preference to \xmlel{vs:DataService}, and that tabular structure
654    should be given in a table set.
655    
656  DataService's content model is exactly the one of  DataService's content model is exactly the one of
657  \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}.  \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}.
# Line 673  Line 669 
669  on coverage and the facilities and instruments that produced the  on coverage and the facilities and instruments that produced the
670  resource.  Additionally, this type allows the  resource.  Additionally, this type allows the
671  declaration of the metadata of the table(s) underlying the data or  declaration of the metadata of the table(s) underlying the data or
672  delivered by it in a tableset element.  delivered by it in a \xmlel{tableset} element.
673    
674  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
675  capabilities declared in the resource are either auxiliary or  capabilities declared in the resource are either auxiliary or
676  nonstandard.  This is typically the case for catalogs or data  nonstandard.  This is typically the case for catalogs or data
677  collections with in larger TAP, ObsTAP, or perhaps SIAP services.  When  collections within larger TAP, ObsTAP, or perhaps SIAP services.  When
678  a service only publishes a single resource, use the  a service only publishes a single resource, use the
679  \xmlel{vs:CatalogService} type.  \xmlel{vs:CatalogService} type.
680    
# Line 698  Line 694 
694           \par}           \par}
695    
696  \noindent{\small  \noindent{\small
697              While this includeds classical astronomical catalogues,              While this includeds classical astronomical catalogs,
698              this resource is also appropriate for collections of observations              this resource is also appropriate for collections of observations
699              or simulation results provided their metadata are available              or simulation results provided their metadata are available
700              in a sufficiently structured form (e.g., Obscore, SSAP, etc).              in a sufficiently structured form (e.g., Obscore, SSAP, etc).
# Line 766  Line 762 
762  case, again, the resource-level metadata should not refer to any  case, again, the resource-level metadata should not refer to any
763  specific data collection contained.  specific data collection contained.
764    
765  This is the type that should be used for typical, one-resource VO  This is the type that should be used for one-resource VO
766  services.  services.
767    
768  CatalogService's content model is exactly the one of  CatalogService's content model is exactly the one of
# Line 784  Line 780 
780  than repair it.  than repair it.
781    
782  Existing \xmlel{vs:DataCollection}-typed  Existing \xmlel{vs:DataCollection}-typed
783  records should be migrated to \xmlel{vs:DataResource} or  records should be migrated to records of type \xmlel{vs:DataResource} or
784  \xmlel{vs:CatalogResource} as appropriate.  If \xmlel{accessURL}  \xmlel{vs:CatalogResource} as appropriate.  If \xmlel{accessURL}
785  children are present in the  children are present in the
786  \xmlel{vs:DataCollection}s,  \xmlel{vs:DataCollection}\/s,
787  they can be replaced with a plain capability with a  they can be replaced with a plain capability with a
788  \xmlel{vr:WebBrowser}-typed interface.  \xmlel{vr:WebBrowser}-typed interface.
789    
# Line 835  Line 831 
831  that future extensions \todo{We should really do this now -- proposals,  that future extensions \todo{We should really do this now -- proposals,
832  anyone?} to this will allow non-celestial frames (e.g., on planet  anyone?} to this will allow non-celestial frames (e.g., on planet
833  surfaces).  However, the only celestial reference system allowed is  surfaces).  However, the only celestial reference system allowed is
834  ICRS.  If a resource's coordinates are natively in another frame (e.g.,  ICRS.  If a resource's native coordinates are given for another frame (e.g.,
835  Galactic or FK4 for some equinox), it is the resource record author's  Galactic or FK4 for some equinox), it is the resource record author's
836  responsibility to convert the spatial coverage into the ICRS.  responsibility to convert the spatial coverage into the ICRS.
837    
# Line 850  Line 846 
846  Resources that need to communicate high-resolution spatial coverage,  Resources that need to communicate high-resolution spatial coverage,
847  perhaps for some non-discovery use case, can use the \xmlel{footprint}  perhaps for some non-discovery use case, can use the \xmlel{footprint}
848  element with its \xmlel{ivo-id} attribute set to  element with its \xmlel{ivo-id} attribute set to
849  \nolinkurl{ivo://ivoa.net/std/moc} to declare a URL giving a MOC  \nolinkurl{ivo://ivoa.net/std/moc} \todo{This doesn't match what this
850    ivo-id was originally intended to be.  Can we hijack it like this and
851    change the semantics?} to declare a URL giving a MOC
852  footprint of arbitrary level and size; however, MOCs returned from  footprint of arbitrary level and size; however, MOCs returned from
853  footprint services must be in the MOC FITS serialisation.  footprint services must be in the MOC FITS serialisation.
854    
# Line 870  Line 868 
868  assumed to be of order 10 minutes.  assumed to be of order 10 minutes.
869    
870  Deviating from common VO practice (which currently fairly consistently  Deviating from common VO practice (which currently fairly consistently
871  uses wavelengths of elecromagnetic waves in vacuum), spectral limits are  uses wavelengths of electromagnetic waves in vacuum), spectral limits are
872  given in Joules of messenger energy.  This is intended to allow seamless  given in Joules of messenger energy.  This is intended to allow seamless
873  integration of non-electromagnetic messengers.  The reference position  integration of non-electromagnetic messengers.  The reference position
874  for the spectral axis is the solar system barycenter.  Again, discovery  for the spectral axis is the solar system barycenter.  Again, discovery
# Line 1157  Line 1155 
1155  separate \xmlel{schema} element, using the elements from  separate \xmlel{schema} element, using the elements from
1156  the \xmlel{vs:TableSchema} type.\todo{Is is a good idea to use  the \xmlel{vs:TableSchema} type.\todo{Is is a good idea to use
1157  ``default'' as the NULL value?  Or should we rather have minOccurs 0 for  ``default'' as the NULL value?  Or should we rather have minOccurs 0 for
1158  title?}  @name?}
1159    
1160    
1161    
# Line 1470  Line 1468 
1468    
1469  Name uniqueness is only required when the table set description is  Name uniqueness is only required when the table set description is
1470  part of a VOResource description.  The name uniqueness rules  part of a VOResource description.  The name uniqueness rules
1471  \emph{should} also be applied to other uses of the  should also be applied to other uses of the
1472  \xmlel{vs:TableSet} element outside of a VOResource  \xmlel{vs:TableSet} element outside of a VOResource
1473  description.    description.  
1474    
# Line 1818  Line 1816 
1816  that includes name, data type, and meaning.    that includes name, data type, and meaning.  
1817    
1818    
1819  All the VODataService parameter types derive from a base type called  All the VODataService parameter types derive from the base type
1820  \xmlel{vs:BaseParam} which defines all the common parameter  \xmlel{vs:BaseParam} which defines all the common parameter
1821  metadata except the data type.    metadata except the data type.  
1822    
# Line 2176  Line 2174 
2174                                
2175  \end{longtermsdescription}  \end{longtermsdescription}
2176  optional  optional
 \item[Comment]  
                      Allowed values are “required” and “optional”.  
                     
2177  \end{description}  \end{description}
2178  \item[std]  \item[std]
2179  \begin{description}  \begin{description}
# Line 2488  Line 2483 
2483    
2484    
2485    
 In general, the \xmlel{vs:TableParam}'s \xmlel{dataType}  
 can support any non-abstract type legally derived from  
 \xmlel{vs:TableDataType}.  However, in the context of a  
 \xmlel{vs:DataCollection} or \xmlel{vs:CatalogService}  
 resource description, it is strongly recommended that  
 \xmlel{vs:VOTableType}  be used to  
 ensure maximum interoperability.    
   
2486  When the actual column type is not  When the actual column type is not
2487  well matched to a VOTable data type, authors are  well matched to a VOTable data type, authors are
2488  encouraged to use the \xmlel{extendedType} attribute to refer to  encouraged to use the \xmlel{extendedType} attribute to refer to

Legend:
Removed from v.5203  
changed lines
  Added in v.5204

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