/[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 5508 by msdemlei, Tue Jun 11 14:29:29 2019 UTC revision 5509 by msdemlei, Thu Jun 13 08:44:03 2019 UTC
# Line 143  Line 143 
143  structures, their service interfaces, and the location of the data  structures, their service interfaces, and the location of the data
144  served in space, time, and energy.  served in space, time, and energy.
145    
146    The remainder of the document introduces the use cases addressed by this
147    specification, then provides a high-level overview over the concepts and
148    usage patterns in sect.~\ref{sect:model} and finally discusses the
149    concrete classes in sect.~\ref{sect:metadata}.
150    
151    
152  \subsection{The Role in the IVOA Architecture}  \subsection{The Role in the IVOA Architecture}
153    
# Line 258  Line 263 
263  details.  To better support the scheme proposed there, version 1.2 adds  details.  To better support the scheme proposed there, version 1.2 adds
264  the \xmlel{vs:DataResource} and \xmlel{vs:CatalogResource} types  the \xmlel{vs:DataResource} and \xmlel{vs:CatalogResource} types
265  that identify a resource as data-like but  that identify a resource as data-like but
266  allows the addition of various capabilities to the record (which  permits the addition of various capabilities to the record (which
267  \xmlel{vs:DataCollection} did not).  An analogous use case would be  \xmlel{vs:DataCollection} did not).  An analogous use case would be
268  ``Find all TAP services publishing tables from Gaia DR2''.  ``Find all TAP services publishing tables from Gaia DR2''.
269    
# Line 269  Line 274 
274  problems.  The new \xmlel{nrows} child of \xmlel{vs:Table} communicates  problems.  The new \xmlel{nrows} child of \xmlel{vs:Table} communicates
275  it.  it.
276    
277    
278    \subsection{Additional Use Cases for Future Versions}
279    
280    The following use cases were originally envisioned for VODataService
281    1.2, but were postponed because building multiply implemented solutions
282    for them seemed likely to unnecessarily delay the standardisation of, in
283    particular, the STC part of the present document.  They will likely be
284    addressed by future versions of VODataService.
285    
286  \paragraph{Find a resource that has sources in M51 down to 27 mag in V.}  \paragraph{Find a resource that has sources in M51 down to 27 mag in V.}
287  The constraint about finding a resource that has V magnitudes for M51 is  The constraint about finding a resource that has V magnitudes for M51 is
288  expressible using spatial coverage and the column's UCDs.  To express  expressible using spatial coverage and the column's UCDs.  To express
289  something like ``down to $27^{\rm m}$'' one would at least need  something like ``down to $27^{\rm m}$'' one would at least need
290  VOTable-style \xmlel{VALUES} children for columns.\todo{Do we want  VOTable-style \xmlel{VALUES} children for columns; however, metadata
291  that?}  sufficient to address the next use case would certainly be sufficient
292    here as well.
293    
294  \paragraph{Plan a cross-service query.} Systems like OGSA-DAI  \paragraph{Plan a cross-service query.} Systems like OGSA-DAI
295  \citep{2011ASPC..442..579H} perform orchestration of SQL-like queries  \citep{2011ASPC..442..579H} perform orchestration of SQL-like queries
296  between multiple services automatically, in particular cross-service  between multiple services automatically, in particular cross-service
297  JOINs.  In order to work efficiently, such services need column  JOINs.  In order to work efficiently, such services need column
298  statistics like histograms and the percentage of NULL values.\todo{Do we  statistics like histograms and the percentage of NULL values.
 want this?  If so, what exactly?}  
299    
300  \paragraph{Find services serving time series.} In the current registry  \paragraph{Find services serving time series.} In the current registry
301  model, users looking for spectra would select SSAP services.  With the  model, users looking for spectra would select SSAP services.  With the
# Line 292  Line 306 
306  \verb|dataproduct_type| column. However, for dataset types not overly  \verb|dataproduct_type| column. However, for dataset types not overly
307  common, well more than 90\% of the services could be excluded without  common, well more than 90\% of the services could be excluded without
308  sending a query there based on a declaration of dataset types available  sending a query there based on a declaration of dataset types available
309  in the Registry.\todo{Actually, a VOTable VALUES workalike would be  in the Registry.
 enough for that and ObsCore.  But: SIAv2?  Data collections, perhaps?}  
310    
311  \paragraph{Facilitate discovery of full DALI services.}  The issue here  \paragraph{Facilitate discovery of full DALI services.}  The issue here
312  is that DALI forsees synchronous and asynchronous endpoints as the  is that DALI forsees synchronous and asynchronous endpoints as the
313  standard case for many protocols -- it already is standard for TAP.  standard case for many protocols -- it already is standard for TAP.
314  Also, several auxiliary endpoints (VOSI, examples) are declared as  Also, several auxiliary endpoints (VOSI, examples) are declared as
315  separate capabilities and need to be matched with the functional endpoints.  separate capabilities and need to be matched with the functional
316  This matching is becoming a problem when multiple  endpoints.  This matching is becoming a problem when multiple
317  authentication schemes or mirror sites  authentication schemes or mirror sites necessitate multiple sync/async
318  necessitate multiple sync/async pairs.\todo{See what UWSRegExt brings.}  pairs.  A longer treatment of this problem has been published while this
319    document was in WD \citep{note:caproles}, but at the time of writing the
320    process of finding consensus has just begun, so again a normative
321    solution has to be deferred to a later version of this standard.
322    
323    
324    
325  \section{The VODataService Data Model}  \section{The VODataService Data Model}
326    \label{sect:model}
327    
328    
329  The VODataService extension in general enables the description of two  The VODataService extension in general enables the description of two
# Line 374  Line 391 
391  all versions with the above schema URI are compatible with each  all versions with the above schema URI are compatible with each
392  other in the sense defined in the IVOA schema versioning policies.  other in the sense defined in the IVOA schema versioning policies.
393    
 The versioning policies in version 1.0 posit a requirement that instance  
 documents declare the minor version of the schema used to produce them  
 in the root element of elements coming from a schema.  VODataService has  
 no global elements, and hence there is no place for such a declaration.  
 We do not expect this to cause operational difficulties, since we cannot  
 see a use case for clients to distinguish minor versions of  
 VODataService instance documents.  
   
   
394  Authors of VOResource instance documents may choose to  Authors of VOResource instance documents may choose to
395  provide a location for the VOResource XML Schema document and its  provide a location for the VOResource XML Schema document and its
396  extensions using the  extensions using the
# Line 396  Line 404 
404                      http://www.ivoa.net/xml/VODataService/v1.1"                      http://www.ivoa.net/xml/VODataService/v1.1"
405  \end{verbatim}  \end{verbatim}
406    
   
 \begin{admonition}{Note}  
 The IVOA Registry Interface standard \citep{2018ivoa.spec.0723D}  
        actually \emph{requires} that the VOResource records it  
        shares with other registries provide location URLs via  
        \xmlel{xsi:schemaLocation} for the VOResource schema and  
        all legal extension schemas that are used in the records.  This  
        rule would apply to the VODataService schema.  
 \end{admonition}  
   
   
407  The canonical prefix for VODataService is \xmlel{vs}; this means, in  The canonical prefix for VODataService is \xmlel{vs}; this means, in
408  particular, that in non-XML contexts (e.g., relational mappings  particular, that in non-XML contexts (e.g., relational mappings
409  like RegTAP) the VODataService types \emph{must} be qualified with  like RegTAP) the VODataService types \emph{must} be qualified with
410  vs:.  The Registry Interfaces standard \citep{2018ivoa.spec.0723D} also  vs:.
 strongly recommends using the canonical prefixes in XML documents.  
411    
412  As recommend by the VOResource standard, the  As recommend by the VOResource standard, the
413  VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.  VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.
# Line 517  Line 513 
513  type declarations may be removed from the schema.  type declarations may be removed from the schema.
514    
515  \subsubsection{Discovering Data Within Other Services}  \subsubsection{Discovering Data Within Other Services}
516    \label{sect:discoverdata}
517    
518  The content models of CatalogResource and CatalogService are identical.  The content models of CatalogResource and CatalogService are identical.
519  To understand why the two classes are present nevertheless, a short  To understand why the two classes are present nevertheless, a short
# Line 619  Line 616 
616    
617    
618  This section enumerates the types and elements defined in the  This section enumerates the types and elements defined in the
619  VODataService extension schema and describes their meaning.  Where a  VODataService extension schema and describes their meaning.
 term matches a term in the RM, its meaning is given  
 in terms of the RM definition.    
620    
621    
622  \subsection{VODataService Resource Types}  \subsection{VODataService Resource Types}
# Line 630  Line 625 
625  \subsubsection{DataResource}  \subsubsection{DataResource}
626  \label{sect:DataResource}  \label{sect:DataResource}
627    
628  The \xmlel{vs:DataResource} resource type is for describing a  The \xmlel{vs:DataResource} resource type is used to describe a
629  resource containing generic astronomical data without a dominating  resource containing generic astronomical data without a dominating
630  tabular structure.  An example might be a largely unstructured archive  tabular structure.  An example might be a largely unstructured archive
631  of various observations.  Resources that have structured metadata tables  of various observations.  Resources that have structured metadata tables
632  (like most VO services) or are tabular in nature (like usual  (like most VO services) or are tabular in nature (like usual
633  astronomical catalogs) should use \xmlel{vs:CatalogResource}.  astronomical catalogues) should use \xmlel{vs:CatalogResource}.
634    
635  The type is derived from \xmlel{vr:Service}, which means that instances  The type is derived from \xmlel{vr:Service}, which means that instances
636  can have  can have
# Line 647  Line 642 
642    
643  In addition to \xmlel{vr:Service}'s content, DataResource adds  In addition to \xmlel{vr:Service}'s content, DataResource adds
644  elements for declaring the observing facilities and/or instruments used  elements for declaring the observing facilities and/or instruments used
645  to obtain the data, and it allows to declare  to obtain the data, and it supports the declaration of
646  the coordinate coverage of data via the \xmlel{coverage}  the physical coverage of data via the \xmlel{coverage}
647  element.  element.
648    
649  % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource  % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource
# Line 691  Line 686 
686  \begin{description}  \begin{description}
687  \item[Type] string with ID attribute: vr:ResourceName  \item[Type] string with ID attribute: vr:ResourceName
688  \item[Meaning]  \item[Meaning]
689                       the observatory or facility used to collect the data                       The observatory or facility used to collect the data
690                       contained or managed by this resource.                         contained or managed by this resource.  
691                                        
692  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
# Line 701  Line 696 
696  \begin{description}  \begin{description}
697  \item[Type] string with ID attribute: vr:ResourceName  \item[Type] string with ID attribute: vr:ResourceName
698  \item[Meaning]  \item[Meaning]
699                       the instrument used to collect the data contain or                       The instrument used to collect the data contain or
700                       managed by a resource.                         managed by a resource.  
701                                        
702  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
# Line 737  Line 732 
732  metadata should pertain to the service itself rather than any specific  metadata should pertain to the service itself rather than any specific
733  data collection served by it.  data collection served by it.
734    
735    As with \xmlel{vs:CatalogResource}, instances SHOULD
736    declare of the metadata of the table(s) underlying the service or
737    delivered by it in a \xmlel{tableset} element.
738    
739  Whenever the service operates on clearly definable tabular  Whenever the service operates on clearly definable tabular
740  data, the resource should use the \xmlel{vs:CatalogService} resource type  data, the resource should use the \xmlel{vs:CatalogService} resource type
741  in preference to \xmlel{vs:DataService}, and that tabular structure  in preference to \xmlel{vs:DataService}, and that tabular structure
742  should be given in a table set.  should be given in a table set.
743    
744  DataService's content model is exactly the one of  DataService's content model is exactly the one of
745  \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}.  \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}
746    for the motivation of this duplication.
747    
748    
749    
# Line 752  Line 752 
752  \label{sect:CatalogResource}  \label{sect:CatalogResource}
753    
754    
755  The \xmlel{vs:CatalogResource} resource type is for describing a  The \xmlel{vs:CatalogResource} resource type is used to descre a
756  resource containing astronomical data or metadata in a set of one or  resource containing astronomical data or metadata in a set of one or
757  more tables.  It extends \xmlel{vs:DataResource} and thus has metadata  more tables.  It extends \xmlel{vs:DataResource} and thus has metadata
758  on coverage and the facilities and instruments that produced the  on coverage and the facilities and instruments that produced the
759  resource.  Additionally, this type allows the  resource.  Additionally, \xmlel{vs:CatalogResource} instances SHOULD
760  declaration of the metadata of the table(s) underlying the data or  declare of the metadata of the table(s) making up the data
761  delivered by it in a \xmlel{tableset} element.  \xmlel{tableset} element.
762    
763  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
764  capabilities declared in the resource are either auxiliary or  capabilities declared in the resource are either auxiliary or
765  nonstandard.  This is typically the case for catalogs or data  nonstandard.  This is typically the case for catalogues or data
766  collections within larger TAP, ObsTAP, or perhaps SIAP services.  When  collections within larger TAP, ObsTAP, or perhaps SIAP services.  When
767  a service only publishes a single resource, use the  a service only publishes a single resource, use the
768  \xmlel{vs:CatalogService} type.  \xmlel{vs:CatalogService} type.
769    
 This is the type that should be used for publishing data collections  
 according to the IVOA Note on Discovering Data Collections  
 \citep{note:DataCollect}.  
   
770    
771  % GENERATED: !schemadoc VODataService-v1.2.xsd CatalogResource  % GENERATED: !schemadoc VODataService-v1.2.xsd CatalogResource
772  \begin{generated}  \begin{generated}
# Line 783  Line 779 
779           \par}           \par}
780    
781  \noindent{\small  \noindent{\small
782              While this includeds classical astronomical catalogs,              While this includes classical astronomical catalogues,
783              this resource is also appropriate for collections of observations              this resource is also appropriate for collections of observations
784              or simulation results provided their metadata are available              or simulation results provided their metadata are available
785              in a sufficiently structured form (e.g., Obscore, SSAP, etc).              in a sufficiently structured form (e.g., Obscore, SSAP, etc).
# Line 840  Line 836 
836    
837  \subsubsection{CatalogService}  \subsubsection{CatalogService}
838    
839  The \xmlel{vs:CatalogService} resource type is for describing a  The \xmlel{vs:CatalogService} resource type is used to describe a
840  service publishing astronomical data or metadata based on tabular  service publishing astronomical data or metadata based on tabular
841  representations.  Its relationship to \xmlel{vs:CatalogResource}  representations.  Its relationship to \xmlel{vs:CatalogResource}
842  is as between \xmlel{vs:DataResource}  is as between \xmlel{vs:DataResource}
# Line 855  Line 851 
851  services.  services.
852    
853  CatalogService's content model is exactly the one of  CatalogService's content model is exactly the one of
854  \xmlel{vs:CatalogResource}; please refer to sect.~\ref{sect:CatalogResource}.  \xmlel{vs:CatalogResource}; please refer to sect.~\ref{sect:CatalogResource}
855    for the motivation of this duplication.
856    
857  \subsubsection{DataCollection}  \subsubsection{DataCollection}
858  \label{sect:datacollection}  \label{sect:datacollection}
# Line 895  Line 892 
892    
893  The \xmlel{vs:Coverage} type summarily describes how the data served is  The \xmlel{vs:Coverage} type summarily describes how the data served is
894  distributed on the  distributed on the
895  sky, in energy, and in time.  For the energy coverage, there is a  sky, in energy, and in time.  For the energy coverage on the
896  also qualitative classification in the \xmlel{waveband} \todo{Worry  electromagnetic spectrum, there is a
897  about non-EM messengers in waveband (use a vocabulary?)} element.  also qualitative classification in the \xmlel{waveband} element.
898    
899  Historically, the quantitative footprints were expected to be given in  Historically, the quantitative footprints were expected to be given in
900  the element of type \xmlel{stc:STCResourceProfile}.  As discussed in  the element of type \xmlel{stc:STCResourceProfile}.  As discussed in
# Line 913  Line 910 
910  Spatial coverage is conveyed as a MOC.  To enable easy embedding into  Spatial coverage is conveyed as a MOC.  To enable easy embedding into
911  resource records written in VOResource (i.e., XML),  resource records written in VOResource (i.e., XML),
912  we represent MOCs in the ASCII convention  we represent MOCs in the ASCII convention
913  proposed in the MOC specification \citep{2014ivoa.spec.0602F}.\todo{We  proposed in MOC 1.0 \citep{2014ivoa.spec.0602F}\footnote{Version 1.1 of MOC
914  need a REC to cite -- DALI? us? VOTable?}  will give a normative specification of ASCII MOCs, which is expected to
915    exactly match the non-normative proposal in version 1.0.}
916  By default, the MOCs are to be interpreted in the ICRS.  It is forseen  
917  that future extensions \todo{We should really do this now -- proposals,  By default, the MOCs are to be interpreted in the ICRS.  Future
918  anyone?} to this will allow non-celestial frames (e.g., on planet  extensions to non-celestial frames (e.g., on planet
919  surfaces).  However, the only celestial reference system allowed is  surfaces) will use the \xmlel{frame} attribute.  
920    However, the only celestial reference system allowed is
921  ICRS.  If a resource's native coordinates are given for another frame (e.g.,  ICRS.  If a resource's native coordinates are given for another frame (e.g.,
922  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
923  responsibility to convert the spatial coverage into the ICRS.  responsibility to convert the spatial coverage into the ICRS.
# Line 1020  Line 1018 
1018                                
1019  \item[Occurrence] optional  \item[Occurrence] optional
1020  \item[Comment]  \item[Comment]
1021                    The MOC is to be understood in the ICRS reference frame.                    The MOC is to be understood in the ICRS reference frame
1022                      unless a frame attribute is given.
1023                    Resources should give the coverage at least to order 6                    Resources should give the coverage at least to order 6
1024                    (a resolution of about one degree).  The order should be                    (a resolution of about one degree).  The order should be
1025                    chosen so as to keep the resulting MOC smaller than a few                    chosen so as to keep the resulting MOC smaller than a few
# Line 1040  Line 1039 
1039    
1040  \item[Comment]  \item[Comment]
1041                    This is written as for VOTable tabledata (i.e.,                    This is written as for VOTable tabledata (i.e.,
1042                    white-separated C-style floating point literals).                    whitespace-separated C-style floating point literals).
1043                    The limits must be given as MJD.  While they                    The limits must be given as MJD.  While they
1044                    are not intended to be precise, they are to be understood                    are not intended to be precise, they are to be understood
1045                    in TDB for the solar system barycenter.  The total coverage                    in TDB for the solar system barycenter.  The total coverage
# Line 1059  Line 1058 
1058    
1059  \item[Comment]  \item[Comment]
1060                    This is written as for VOTable tabledata (i.e.,                    This is written as for VOTable tabledata (i.e.,
1061                    white-separated C-style floating point literals).                    whitespace-separated C-style floating point literals).
1062                    The limits must be given in Joules of particle                    The limits must be given in Joules of particle
1063                    energies.  While the limits are not intended                    energies.  While the limits are not intended
1064                    to be precise, they are to be understood for the                    to be precise, they are to be understood for the
# Line 1075  Line 1074 
1074  \begin{description}  \begin{description}
1075  \item[Type] a URI with optional attributes  \item[Type] a URI with optional attributes
1076  \item[Meaning]  \item[Meaning]
1077                    a reference to a footprint service for retrieving                    A reference to a footprint service for retrieving
1078                    precise and up-to-date description of coverage.                      precise and up-to-date description of coverage.  
1079                                
1080  \item[Occurrence] optional  \item[Occurrence] optional
1081  \item[Comment]  \item[Comment]
1082                    the ivo-id attribute refers to a Service record                    The ivo-id attribute refers to a Service record
1083                    that describes the Footprint capability.  That is,                    that describes the Footprint capability.  That is,
1084                    the record will have a capability element describing                    the record will have a capability element describing
1085                    the service.  The resource refered to may be the                    the service.  The resource refered to may be the
# Line 1092  Line 1091 
1091  \begin{description}  \begin{description}
1092  \item[Type] string with controlled vocabulary  \item[Type] string with controlled vocabulary
1093  \item[Meaning]  \item[Meaning]
1094                    a named spectral region of the electro-magnetic spectrum                    A named spectral region of the electro-magnetic spectrum
1095                    that the resource's spectral coverage overlaps with.                    that the resource's spectral coverage overlaps with.
1096                                
1097  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
# Line 1125  Line 1124 
1124                   energy >= 120 keV                   energy >= 120 keV
1125                                
1126  \end{longtermsdescription}  \end{longtermsdescription}
1127    \item[Comment]
1128                      Observations using non-electromagnetic messengers should
1129                      not give a waveband in version 1.2 of VODataService.  It
1130                      is expected that additional terms for these will be provided
1131                      in a future version.
1132                  
1133    
1134  \end{description}  \end{description}
1135  \item[Element \xmlel{regionOfRegard}]  \item[Element \xmlel{regionOfRegard}]
1136  \begin{description}  \begin{description}
1137  \item[Type] floating-point number: \xmlel{xs:float}  \item[Type] floating-point number: \xmlel{xs:float}
1138  \item[Meaning]  \item[Meaning]
1139                    a single numeric value representing the angle, given                    A single numeric value representing the angle, given
1140                    in decimal degrees, by which a positional query                    in decimal degrees, by which a positional query
1141                    against this resource should be “blurred” in order                    against this resource should be “blurred” in order
1142                    to get an appropriate match.                    to get an appropriate match.
# Line 1141  Line 1146 
1146                    In the case of image repositories, it might refer to                    In the case of image repositories, it might refer to
1147                    a typical field-of-view size, or the primary beam                    a typical field-of-view size, or the primary beam
1148                    size for radio aperture synthesis data.  In the case                    size for radio aperture synthesis data.  In the case
1149                    of object catalogs RoR should normally be the                    of object catalogues RoR should normally be the
1150                    largest of the typical size of the objects, the                    largest of the typical size of the objects, the
1151                    astrometric errors in the positions, or the                    astrometric errors in the positions, or the
1152                    resolution of the data.                      resolution of the data.  
# Line 1263  Line 1268 
1268  \begin{description}  \begin{description}
1269  \item[Type] composite: \xmlel{vs:TableSchema}  \item[Type] composite: \xmlel{vs:TableSchema}
1270  \item[Meaning]  \item[Meaning]
1271                  A named description of a set of logically related tables.                  A named description of a group of logically related tables.
1272                                
1273  \item[Occurrence] required; multiple occurrences allowed.  \item[Occurrence] required; multiple occurrences allowed.
1274  \item[Comment]  \item[Comment]
1275                  The name given by the “name” child element must                  The name given by the “name” child element must
1276                  be unique within this TableSet instance.  If there is                  be unique within this TableSet instance.  If there is
1277                  only one schema in this set and/or there's no locally                  only one schema in this set and/or there is no locally
1278                  appropriate name to provide, the name can be set to                  appropriate name to provide, the name can be set to
1279                  “default”.                    “default”.  
1280                                
1281  \item[Comment]  \item[Comment]
1282                  This aggregation does not need to map to an                  This aggregation does not need to map to an
1283                  actual database, catalog, or schema, though the                  actual database, catalogue, or schema, though the
1284                  publisher may choose to aggregate along such                  publisher may choose to aggregate along such
1285                  designations, or particular service protocol may                  designations.  Particular service protocols may
1286                  recommend it.                    require stricter patterns.
1287                                
1288    
1289  \end{description}  \end{description}
# Line 1292  Line 1297 
1297  % /GENERATED  % /GENERATED
1298    
1299    
1300  The \xmlel{vs:TableSchema} type collects  The \xmlel{vs:TableSchema} type groups
1301  tables together that are logically related.  tables that are logically related.
1302  For example, a single  For example, a single
1303  resource may provide access several major astronomical catalogs  resource may provide access several major astronomical catalogues
1304  (e.g. SDSS, 2MASS, and FIRST) from one site, enabling high-performance  (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance
1305  cross-correlations between them.  Each catalog can be described in a  cross-correlations between them.  Each catalogue can be described in a
1306  separate \xmlel{schema} element, using the elements from  separate \xmlel{schema} element, using the elements from
1307  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
1308  ``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
# Line 1312  Line 1317 
1317          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Documentation}
1318    
1319  \noindent{\small  \noindent{\small
1320             A detailed description of a logically-related set of tables             A detailed description of a logically related group of tables.
1321           \par}           \par}
1322    
1323  \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Definition}
# Line 1338  Line 1343 
1343  \begin{description}  \begin{description}
1344  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1345  \item[Meaning]  \item[Meaning]
1346                 A name for the set of tables.                   A name for the group of tables.  
1347                            
1348  \item[Occurrence] required  \item[Occurrence] required
1349  \item[Comment]  \item[Comment]
1350                 This is used to uniquely identify the table set among                 This is used to uniquely identify the group of tables among
1351                 several table sets.  If a title is not present, this                 several groups.  If no title is given, this
1352                 name can be used for display purposes.                 name can be used for display purposes.
1353                            
1354  \item[Comment]  \item[Comment]
1355                 If there is no appropriate logical name associated with                 If there is no appropriate logical name associated with
1356                 this set, the name should be explicitly set to                 this group, the name should be explicitly set to
1357                 “default”.                   “default”.  
1358                            
1359    
# Line 1357  Line 1362 
1362  \begin{description}  \begin{description}
1363  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1364  \item[Meaning]  \item[Meaning]
1365                    a descriptive, human-interpretable name for the table set.                    A descriptive, human-interpretable name for the group of
1366                      tables.
1367                                
1368  \item[Occurrence] optional  \item[Occurrence] optional
1369  \item[Comment]  \item[Comment]
# Line 1373  Line 1379 
1379  \begin{description}  \begin{description}
1380  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1381  \item[Meaning]  \item[Meaning]
1382                 A free text description of the tableset that should                 A free text description of the group of tables that should
1383                 explain in general how all of the tables are related.                 explain in general how all of the tables in the group are
1384                   related.
1385                            
1386  \item[Occurrence] optional  \item[Occurrence] optional
1387    
# Line 1383  Line 1390 
1390  \begin{description}  \begin{description}
1391  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1392  \item[Meaning]  \item[Meaning]
1393                    an identifier for a concept in a data model that                    An identifier for a concept in a data model that
1394                    the data in this schema as a whole represent.                      the data in this schema as a whole represent.  
1395                                
1396  \item[Occurrence] optional  \item[Occurrence] optional
# Line 1398  Line 1405 
1405  \begin{description}  \begin{description}
1406  \item[Type] composite: \xmlel{vs:Table}  \item[Type] composite: \xmlel{vs:Table}
1407  \item[Meaning]  \item[Meaning]
1408                 A description of one of the tables that makes up the set.                 A description of one table.
1409                            
1410  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
 \item[Comment]  
                The table names for the table should be unique.  
               
1411    
1412  \end{description}  \end{description}
1413    
# Line 1453  Line 1457 
1457  \begin{description}  \begin{description}
1458  \item[Type] string: \xmlel{xs:string}  \item[Type] string: \xmlel{xs:string}
1459  \item[Meaning]  \item[Meaning]
1460                 a name for the role this table plays.  Recognized                 A name for the role this table plays.  Recognized
1461                 values include “output”, indicating this table is output                 values include “output”, indicating this table is output
1462                 from a query; “base\_table{"}, indicating a table                 from a query; “base\_table{"}, indicating a table
1463                 whose records represent the main subjects of its                 whose records represent the main subjects of its
# Line 1475  Line 1479 
1479  \begin{description}  \begin{description}
1480  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1481  \item[Meaning]  \item[Meaning]
1482                    the fully qualified name of the table.  This name                    The fully qualified name of the table.  This name
1483                    should include all catalog or schema prefixes                    should include all catalogue or schema prefixes
1484                    needed to sufficiently uniquely distinguish it in a                    needed to sufficiently uniquely distinguish it in a
1485                    query.                      query.  
1486                                
# Line 1485  Line 1489 
1489                    In general, the format of the qualified name may                    In general, the format of the qualified name may
1490                    depend on the context; however, when the                    depend on the context; however, when the
1491                    table is intended to be queryable via ADQL, then the                    table is intended to be queryable via ADQL, then the
1492                    catalog and schema qualifiers are delimited from the                    catalogue and schema qualifiers are delimited from the
1493                    table name with dots (.).                      table name with dots (.).  
1494                                
1495    
# Line 1494  Line 1498 
1498  \begin{description}  \begin{description}
1499  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1500  \item[Meaning]  \item[Meaning]
1501                    a descriptive, human-interpretable name for the table.                    A descriptive, human-interpretable name for the table.
1502                                
1503  \item[Occurrence] optional  \item[Occurrence] optional
1504  \item[Comment]  \item[Comment]
# Line 1507  Line 1511 
1511  \begin{description}  \begin{description}
1512  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1513  \item[Meaning]  \item[Meaning]
1514                    a free-text description of the table's contents                    A free-text description of the table's contents
1515                                
1516  \item[Occurrence] optional  \item[Occurrence] optional
1517    
# Line 1516  Line 1520 
1520  \begin{description}  \begin{description}
1521  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1522  \item[Meaning]  \item[Meaning]
1523                    an identifier for a concept in a data model that                    An identifier for a concept in a data model that
1524                    the data in this table represent.                      the data in this table represent.  
1525                                
1526  \item[Occurrence] optional  \item[Occurrence] optional
# Line 1531  Line 1535 
1535  \begin{description}  \begin{description}
1536  \item[Type] integer  \item[Type] integer
1537  \item[Meaning]  \item[Meaning]
1538                    the size of the table in rows.                    The size of the table in rows.
1539                                
1540  \item[Occurrence] optional  \item[Occurrence] optional
1541  \item[Comment]  \item[Comment]
# Line 1545  Line 1549 
1549  \begin{description}  \begin{description}
1550  \item[Type] composite: \xmlel{vs:TableParam}  \item[Type] composite: \xmlel{vs:TableParam}
1551  \item[Meaning]  \item[Meaning]
1552                    a description of a table column.                    A description of a table column.
1553                                
1554  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
1555    
# Line 1554  Line 1558 
1558  \begin{description}  \begin{description}
1559  \item[Type] composite: \xmlel{vs:ForeignKey}  \item[Type] composite: \xmlel{vs:ForeignKey}
1560  \item[Meaning]  \item[Meaning]
1561                    a description of a foreign keys, one or more columns                    A description of a foreign keys, one or more columns
1562                    from the current table that can be used to join with                    from the current table that can be used to join with
1563                    another table.                      another table.  
1564                                
# Line 1585  Line 1589 
1589  a \xmlel{table}'s \xmlel{name} child must be in a form immediately  a \xmlel{table}'s \xmlel{name} child must be in a form immediately
1590  usable for use in ADQL or SQL queries. This corresponds to the analogous  usable for use in ADQL or SQL queries. This corresponds to the analogous
1591  requirement for \tapschema.  This means that all qualifications (schema,  requirement for \tapschema.  This means that all qualifications (schema,
1592  catalog) must be present, but also that when delimited  catalogue) must be present, but also that when delimited
1593  identifiers are used as table names on the relational side,  identifiers are used as table names on the relational side,
1594  the quotes must be part of \xmlel{name}'s value, and the  the quotes must be part of \xmlel{name}'s value, and the
1595  capitalisation used in the DDL must be preserved.  capitalisation used in the DDL must be preserved.
# Line 1608  Line 1612 
1612  constrain certain names to be unique.  In particular, all schema names  constrain certain names to be unique.  In particular, all schema names
1613  within a \xmlel{tableset} element must be unique, and all  within a \xmlel{tableset} element must be unique, and all
1614  table names within a \xmlel{schema} element must be  table names within a \xmlel{schema} element must be
1615  unique.  (A schema and table may share a common name, such as  unique.  A schema and table may share a common name, such as
1616  ``default''.)  These constraints makes it possible to uniquely locate  ``default''.  These constraints make it possible to uniquely locate
1617  the description of a schema or table within a VOResource description.    the description of a schema or table within a VOResource description.  
1618    
 Name uniqueness is only required when the table set description is  
 part of a VOResource description.  The name uniqueness rules  
 should also be applied to other uses of the  
 \xmlel{vs:TableSet} element outside of a VOResource  
 description.    
   
1619    
1620  \subsubsection{Foreign Keys}  \subsubsection{Foreign Keys}
1621  \label{sect:fkey}  \label{sect:fkey}
1622    
1623    
1624  The \xmlel{vs:ForeignKey} type allows one to describe foreign  The \xmlel{vs:ForeignKey} type is used to describe foreign
1625  keys in a table that allow it to be joined effectively with another  keys in a table that allow it to be joined efficiently with another
1626  table.  A foreign key is a set of columns that map to a corresponding  table.  A foreign key is a set of columns that map to a corresponding
1627  set of columns in another table.    set of columns in another table.  
1628    
# Line 1636  Line 1634 
1634          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Documentation}
1635    
1636  \noindent{\small  \noindent{\small
1637             A description of the mapping a foreign key--a set of             A description of the mapping a foreign key -- a set of
1638             columns from one table--to columns in another table.               columns from one table -- to columns in another table.  
1639           \par}           \par}
1640    
1641  \noindent{\small  \noindent{\small
1642             This definition that the foreign key is being described              When foreign keys are declared in this way, clients can expect
1643             within the context of the table containing the key.                that joins constrained with the foreign keys are preformed
1644                efficiently (e.g., using an index).
1645           \par}           \par}
1646    
1647  \vspace{1ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Definition}
# Line 1665  Line 1664 
1664  \begin{description}  \begin{description}
1665  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1666  \item[Meaning]  \item[Meaning]
1667                 the fully-qualified name (including catalog and schema, as                 The fully qualified name (including catalogue and schema, as
1668                 applicable) of the table that can be joined with the                 applicable) of the table that can be joined with the
1669                 table containing this foreign key.                 table containing this foreign key.
1670                            
# Line 1676  Line 1675 
1675  \begin{description}  \begin{description}
1676  \item[Type] composite: \xmlel{vs:FKColumn}  \item[Type] composite: \xmlel{vs:FKColumn}
1677  \item[Meaning]  \item[Meaning]
1678                 a pair of column names, one from this table and one                 A pair of column names, one from this table and one
1679                 from the target table that should be used to join the                 from the target table that should be used to join the
1680                 tables in a query.                   tables in a query.  
1681                            
# Line 1687  Line 1686 
1686  \begin{description}  \begin{description}
1687  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1688  \item[Meaning]  \item[Meaning]
1689                    a free-text description of what this key points to                    A free-text description of what this key points to
1690                    and what the relationship means.                      and what the relationship means.  
1691                                
1692  \item[Occurrence] optional  \item[Occurrence] optional
# Line 1697  Line 1696 
1696  \begin{description}  \begin{description}
1697  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1698  \item[Meaning]  \item[Meaning]
1699                    an identifier for a concept in a data model that                    An identifier for a concept in a data model that
1700                    the association enabled by this key represents.                      the association enabled by this key represents.  
1701                                
1702  \item[Occurrence] optional  \item[Occurrence] optional
# Line 1719  Line 1718 
1718    
1719    
1720  In this model, the source of the foreign  In this model, the source of the foreign
1721  key is the current table being described (i.e. represented by the  key is the current table being described (i.e., represented by the
1722  \xmlel{table} element that contains the  \xmlel{table} element that contains the
1723  \xmlel{vs:ForeignKey} description, and thus does not need to be  \xmlel{vs:ForeignKey} description, and thus does not need to be
1724  named explicitly).  The key that is described points to the table  named explicitly).  The key that is described points to the table
# Line 1769  Line 1768 
1768    
1769  \item Use the \xmlel{extendedType} attribute of the  \item Use the \xmlel{extendedType} attribute of the
1770         \xmlel{dataType} element (see         \xmlel{dataType} element (see
1771         section~\ref{sect:tbldatatypes}).         section~\ref{sect:tbldatatypes})
1772         to indicate a more specific data type then those defined by the         to indicate a more specific data type then those defined by the
1773         \xmlel{vs:TableParam} type.         \xmlel{vs:TableParam} type.
1774  \end{enumerate}  \end{enumerate}
# Line 1799  Line 1798 
1798    
1799  \noindent{\small  \noindent{\small
1800             Note that the URL for help with this service can be put into             Note that the URL for help with this service can be put into
1801             the Service/ReferenceURL element.             the service/referenceURL element.
1802          \par}          \par}
1803    
1804  \vspace{1ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Definition}
# Line 1816  Line 1815 
1815          <xs:element name="param" type="vs:InputParam" minOccurs="0"          <xs:element name="param" type="vs:InputParam" minOccurs="0"
1816                    maxOccurs="unbounded" />                    maxOccurs="unbounded" />
1817          <xs:element name="testQuery" type="xs:string" minOccurs="0"          <xs:element name="testQuery" type="xs:string" minOccurs="0"
1818                    maxOccurs="unbounded" />                    maxOccurs="1" />
1819        </xs:sequence>        </xs:sequence>
1820      </xs:extension>      </xs:extension>
1821    </xs:complexContent>    </xs:complexContent>
# Line 1841  Line 1840 
1840  \item[Comment]  \item[Comment]
1841                         The service may indicate support for both GET                         The service may indicate support for both GET
1842                         and POST by providing 2 queryType elements, one                         and POST by providing 2 queryType elements, one
1843                         with GET and one with POST.                         with GET and one with POST.  Since the IVOA standard
1844                           DALI requires standard services to support both
1845                           GET and POST, this piece of metadata is not
1846                           useful in the description of standard DAL services
1847                           and does not need to be given for those.
1848                                            
1849    
1850  \end{description}  \end{description}
# Line 1849  Line 1852 
1852  \begin{description}  \begin{description}
1853  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
1854  \item[Meaning]  \item[Meaning]
1855                         The MIME type of a document returned in the HTTP response.                         The MIME media type of a document returned in
1856                           the HTTP response.
1857                                            
1858  \item[Occurrence] optional  \item[Occurrence] optional
1859    
# Line 1858  Line 1862 
1862  \begin{description}  \begin{description}
1863  \item[Type] composite: \xmlel{vs:InputParam}  \item[Type] composite: \xmlel{vs:InputParam}
1864  \item[Meaning]  \item[Meaning]
1865                         a description of a input parameter that can be                         A description of a input parameter that can be
1866                         provided as a name=value argument to the service.                           provided as a name=value argument to the service.  
1867                                            
1868  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional; multiple occurrences allowed.
# Line 1868  Line 1872 
1872  \begin{description}  \begin{description}
1873  \item[Type] string: \xmlel{xs:string}  \item[Type] string: \xmlel{xs:string}
1874  \item[Meaning]  \item[Meaning]
1875                         an ampersand-delimited list of arguments that                         An ampersand-delimited list of arguments that
1876                         can be used to test this service interface;                         can be used to test this service interface;
1877                         when provided as the input to this interface,                         when provided as the input to this interface,
1878                         it will produce a legal, non-null response.                         it will produce a legal, non-null response.
1879                                            
1880  \item[Occurrence] optional; multiple occurrences allowed.  \item[Occurrence] optional
1881  \item[Comment]  \item[Comment]
1882                         When the interface supports GET, then the full                         When the interface supports GET, then the full
1883                         query URL is formed by the concatonation of the                         query URL is formed by the concatenation of the
1884                         base URL (given by the accessURL) and the value                         base URL (given by the accessURL) and the value
1885                         given by this testQuery element.                           given by this testQuery element.  
1886                                            
# Line 1905  Line 1909 
1909    
1910    
1911    
1912  A important intended use of the \xmlel{vs:ParamHTTP} type is  An important intended use of the \xmlel{vs:ParamHTTP} type is
1913  describing the interface of an IVOA standard service protocol  describing the interface of an IVOA standard service protocol
1914  of the ``simple'' variety, such as the Simple Image Access Protocol  of the ``simple'' variety, such as the Simple Image Access Protocol
1915  \citep{2015ivoa.spec.1223D}.  In particular, it is recommended that  \citep{2015ivoa.spec.1223D}.  In particular, it is recommended that
# Line 1938  Line 1942 
1942  \end{itemize}  \end{itemize}
1943    
1944    
1945  Of course, listing required parameters is always allowed, even when  Listing required parameters is allowed, even when
1946  describing a standard interface as long as these are consistent with  describing a standard interface as long as these are consistent with
1947  the service specification and the corresponding \xmlel{param}  the service specification and the corresponding \xmlel{param}
1948  elements include the attribute \verb|use="required"| (see  elements include the attribute \verb|std="true"| (see
1949  section~\ref{sect:inputparam}.  The \xmlel{param}  section~\ref{sect:inputparam}).  The \xmlel{param}
1950  elements for custom parameters that are not part of the standard (but  elements for custom parameters that are not part of the standard (but
1951  are rather local customizations) should include the attribute  are rather local customizations) should include the attribute
1952  \verb|std="false"|.  \verb|std="false"|.
# Line 1958  Line 1962 
1962  The VODataService schema provides several element types for describing  The VODataService schema provides several element types for describing
1963  different kinds of data parameters used in datasets and services,  different kinds of data parameters used in datasets and services,
1964  including service input parameters and table columns.  The parameter  including service input parameters and table columns.  The parameter
1965  types allow one to fully describe a parameter in terms of metadata  types describe a parameter in terms of elementary metadata
1966  that includes name, data type, and meaning.    including name, data type, and meaning.  
1967    
1968    
1969  All the VODataService parameter types derive from the base type  All the VODataService parameter types derive from the base type
# Line 1974  Line 1978 
1978          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Documentation}
1979    
1980  \noindent{\small  \noindent{\small
1981              a description of a parameter that places no restriction on              A description of a parameter that places no restriction on
1982              the parameter's data type.              the parameter's data type.
1983           \par}           \par}
1984    
1985  \noindent{\small  \noindent{\small
1986              As the parameter's data type is usually important, schemas              As the parameter's data type is usually important, schemas
1987              normally employ a sub-class of this type (e.g., Param),              normally employ a sub-class of this type
1988              rather than this type directly.              rather than this type directly.
1989           \par}           \par}
1990    
# Line 2005  Line 2009 
2009  \begin{description}  \begin{description}
2010  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2011  \item[Meaning]  \item[Meaning]
2012                    the name of the parameter or column                    The name of the parameter or column.
2013                                
2014  \item[Occurrence] optional  \item[Occurrence] optional
2015    
# Line 2014  Line 2018 
2018  \begin{description}  \begin{description}
2019  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2020  \item[Meaning]  \item[Meaning]
2021                    a free-text description of a parameter's or column's                    A free-text description of a parameter's or column's
2022                    contents                    contents.
2023                                
2024  \item[Occurrence] optional  \item[Occurrence] optional
2025    
# Line 2024  Line 2028 
2028  \begin{description}  \begin{description}
2029  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2030  \item[Meaning]  \item[Meaning]
2031                    the unit associated with the values in the parameter                    The unit associated with the values in the parameter
2032                    or column                    or column.
2033                                
2034  \item[Occurrence] optional  \item[Occurrence] optional
2035    
# Line 2034  Line 2038 
2038  \begin{description}  \begin{description}
2039  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2040  \item[Meaning]  \item[Meaning]
2041                    the name of a unified content descriptor that                    The name of a unified content descriptor that
2042                    describes the scientific content of the parameter.                      describes the scientific content of the parameter.
2043                                
2044  \item[Occurrence] optional  \item[Occurrence] optional
2045  \item[Comment]  \item[Comment]
# Line 2052  Line 2056 
2056  \begin{description}  \begin{description}
2057  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2058  \item[Meaning]  \item[Meaning]
2059                    an identifier for a concept in a data model that                    An identifier for a concept in a data model that
2060                    the data in this schema represent.                      the data in this schema represent.  
2061                                
2062  \item[Occurrence] optional  \item[Occurrence] optional
# Line 2090  Line 2094 
2094          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Documentation}
2095    
2096  \noindent{\small  \noindent{\small
2097              a type (in the computer language sense) associated with a              A type (in the computer language sense) associated with a
2098              parameter with an arbitrary name              parameter with an arbitrary name
2099           \par}           \par}
2100    
# Line 2122  Line 2126 
2126  \begin{description}  \begin{description}
2127  \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}  \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2128  \item[Meaning]  \item[Meaning]
2129                       the shape of the array that constitutes the value                       The shape of the array that constitutes the value.
2130                                        
2131  \item[Occurrence] optional  \item[Occurrence] optional
2132    
# Line 2138  Line 2142 
2142  \begin{description}  \begin{description}
2143  \item[Type] string: \xmlel{xs:string}  \item[Type] string: \xmlel{xs:string}
2144  \item[Meaning]  \item[Meaning]
2145                       a string that is used to delimit elements of an array                       A string that is used to delimit elements of an array
2146                       value in InputParams.                       value in InputParams.
2147                                        
2148  \item[Occurrence] optional  \item[Occurrence] optional
# Line 2208  Line 2212 
2212    
2213    
2214  A data type description can be augmented via a common set of  A data type description can be augmented via a common set of
2215  \xmlel{vs:DataType} attributes, defined below.  The  \xmlel{vs:DataType} attributes.  The
2216  \xmlel{arraysize} attribute indicates the parameter is an array  \xmlel{arraysize} attribute indicates the parameter is an array
2217  of values of the named type.  Its value describes the shape of the  of values of the named type.  Its value describes the shape of the
2218  array. When there is no natural serialisation defined through the type  array. When there is no natural serialisation defined through the type
# Line 2221  Line 2225 
2225    
2226  More descriptive information about the type can be provided via  More descriptive information about the type can be provided via
2227  \xmlel{extendedType} and \xmlel{extendedSchema}, which  \xmlel{extendedType} and \xmlel{extendedSchema}, which
2228  provide an alternate data type name.  It is expected that this name  provide an alternate data type name.  The name
2229  will only be understood by a special subset of applications.  The name  given in the type's element content, then, represents a commonly
2230  given in the element content, then, represents a more commonly  understood “fallback” type.  For instance, in VOTable, timestamps are
2231  understood “fall-back” type.   Arbitrary information can also be  serialised into strings, which implies a VOTableType of char with
2232    arraysize *, as supported by all VOTable readers.  VOTable readers
2233    interpreting the timestamp xtype, however, can turn this string into a
2234    timestamp value native to its clients.  Such readers will interpret
2235    a VOTable FIELD's xtype attribute. Such information is reflected in
2236    \xmlel{extendedType}.  
2237    
2238    Arbitrary information can also be
2239  provided via any prefix-qualified, globally defined attribute drawn  provided via any prefix-qualified, globally defined attribute drawn
2240  from an XML Schema other than VODataService (by virtue of the  from an XML Schema other than VODataService (by virtue of the
2241  \xmlel{xs:anyAttribute} specification present  \xmlel{xs:anyAttribute} specification present
# Line 2250  Line 2261 
2261    
2262  Actual parameters are normally described with types derived from  Actual parameters are normally described with types derived from
2263  \xmlel{vs:BaseParam}.  The \xmlel{vs:InputParam} is intended  \xmlel{vs:BaseParam}.  The \xmlel{vs:InputParam} is intended
2264  for describing an input parameter to a service or function.  The  for describing an input parameter to a service or function.  In this
2265  allowed data type names (given in the metadata table below) do not  version of VODataService, input parameters are restricted to be defined
2266  imply a size or precise format; rather, they are intended to be  in terms of simple data types\todo{On the other hand,
2267    also allowing VOTable types here would help a lot with, e.g., SODA and
2268    friends.  If no objections are raised, we'll allow arbitrary type
2269    systems here in REC.} which do not
2270    imply a size or precise format. Rather, they are intended to be
2271  sufficient for describing an input paramter to a simple REST-like  sufficient for describing an input paramter to a simple REST-like
2272  service or a function in a weakly-typed (e.g. scripting) language.    service or a function in a weakly-typed language.  They are defined
2273    in \xmlel{vs:SimpleDataType}:
2274    
2275    % GENERATED: !schemadoc VODataService-v1.2.xsd SimpleDataType
2276    \begin{generated}
2277    \begingroup
2278            \renewcommand*\descriptionlabel[1]{%
2279            \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Documentation}
2280    
2281    \noindent{\small
2282                A data type restricted to a small set of names which is
2283                imprecise as to the format of the individual values.
2284             \par}
2285    
2286    \noindent{\small
2287                This set is intended for describing simple input parameters to
2288                a service or function.
2289             \par}
2290    
2291    \vspace{1ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Definition}
2292    
2293    \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2294    <xs:complexType name="SimpleDataType" >
2295      <xs:simpleContent >
2296        <xs:restriction base="vs:DataType" >
2297          <xs:enumeration value="integer" />
2298          <xs:enumeration value="real" />
2299          <xs:enumeration value="complex" />
2300          <xs:enumeration value="boolean" />
2301          <xs:enumeration value="char" />
2302          <xs:enumeration value="string" />
2303          <xs:attribute name="arraysize" type="vs:ArrayShape" />
2304          <xs:attribute name="delim" type="xs:string" default=" " />
2305          <xs:attribute name="extendedType" type="xs:string" />
2306          <xs:attribute name="extendedSchema" type="xs:anyURI" />
2307          <xs:anyAttribute namespace="##other" />
2308        </xs:restriction>
2309      </xs:simpleContent>
2310    </xs:complexType>
2311    \end{lstlisting}
2312    
2313    \vspace{0.5ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Attributes}
2314    
2315    \begingroup\small\begin{bigdescription}
2316    \item[arraysize]
2317    \begin{description}
2318    \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2319    \item[Meaning] See vs:DataType.
2320    \item[Occurrence] optional
2321    
2322    \end{description}
2323    \item[delim]
2324    \begin{description}
2325    \item[Type] string: \xmlel{xs:string}
2326    \item[Meaning] See vs:DataType.
2327    \item[Occurrence] optional
2328    
2329    \end{description}
2330    \item[extendedType]
2331    \begin{description}
2332    \item[Type] string: \xmlel{xs:string}
2333    \item[Meaning] See vs:DataType.
2334    \item[Occurrence] optional
2335    \end{description}
2336    \item[extendedSchema]
2337    \begin{description}
2338    \item[Type] a URI: \xmlel{xs:anyURI}
2339    \item[Meaning] See vs:DataType.
2340    \item[Occurrence] optional
2341    \end{description}
2342    
2343    
2344    \end{bigdescription}\endgroup
2345    
2346    \endgroup
2347    \end{generated}
2348    
2349    % /GENERATED
2350    
2351    The \xmlel{vs:InputParam} class then is a \xmlel{vs:DataType}
2352    constrained to these types and furnished with additional metadata
2353    defining how to use the parameter and whether or not it is defined in
2354    the standard governing the capability the interface is in (if any):
2355    
2356    
2357  % GENERATED: !schemadoc VODataService-v1.2.xsd InputParam  % GENERATED: !schemadoc VODataService-v1.2.xsd InputParam
# Line 2264  Line 2361 
2361          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Documentation}
2362    
2363  \noindent{\small  \noindent{\small
2364              a description of a service or function parameter having a              A description of a service or function parameter having a
2365              fixed data type.              fixed data type.
2366           \par}           \par}
2367    
# Line 2272  Line 2369 
2369              The allowed data type names do not imply a size or precise              The allowed data type names do not imply a size or precise
2370              format.  This type is intended to be sufficient for describing              format.  This type is intended to be sufficient for describing
2371              an input parameter to a simple REST service or a function              an input parameter to a simple REST service or a function
2372              written in a weakly-typed (e.g., scripting) language.              written in a weakly-typed language.
2373           \par}           \par}
2374    
2375  \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition}
# Line 2307  Line 2404 
2404  \item[Allowed Values]\hfil  \item[Allowed Values]\hfil
2405  \begin{longtermsdescription}  \begin{longtermsdescription}
2406  \item[required]  \item[required]
2407                    the parameter is required for the application or                    The parameter is required for the application or
2408                    service to work properly.                      service to work properly.  
2409                                
2410  \item[optional]  \item[optional]
2411                    the parameter is optional but supported by the application or                    The parameter is optional but supported by the application or
2412                    service.                    service.
2413                                
2414  \item[ignored]  \item[ignored]
2415                    the parameter is not supported and thus is ignored by the                    The parameter is not supported and thus is ignored by the
2416                    application or service.                    application or service.
2417                                
2418  \end{longtermsdescription}  \end{longtermsdescription}
# Line 2346  Line 2443 
2443  \begin{description}  \begin{description}
2444  \item[Type] composite: \xmlel{vs:SimpleDataType}  \item[Type] composite: \xmlel{vs:SimpleDataType}
2445  \item[Meaning]  \item[Meaning]
2446                          a type of data contained in the parameter                          A type of data contained in the parameter
2447                                            
2448  \item[Occurrence] optional  \item[Occurrence] optional
2449    
# Line 2361  Line 2458 
2458  % /GENERATED  % /GENERATED
2459    
2460    
 By fixing the \xmlel{dataType} child element to that of the  
 \xmlel{vs:SimpleDataType}, the possible types are restricted to  
 predefined set appropriate for input parameters.\todo{On the other hand,  
 also allowing VOTable types here would help a lot with, e.g., SODA and  
 friends.  Anyone objecting to opening up the type system here?}  
   
   
   
 The \xmlel{vs:InputParam} type accepts two attributes that  
 indicate the role that the parameter plays as input to the service or  
 function.  
   
   
2461  Here is an example for a description  Here is an example for a description
2462  of an input parameter that might appear inside an  of an input parameter that might appear inside an
2463  \xmlel{vs:ParamHTTP} interface description.  As noted in  \xmlel{vs:ParamHTTP} interface description.  As noted in
# Line 2408  Line 2492 
2492          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Documentation}
2493    
2494  \noindent{\small  \noindent{\small
2495              a description of a table parameter having a fixed data type.              A description of a table parameter having a fixed data type.
          \par}  
   
 \noindent{\small  
             The allowed data type names match those supported by VOTable.  
2496           \par}           \par}
2497    
2498  \vspace{1ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Definition}
# Line 2441  Line 2521 
2521  \item[Meaning]  \item[Meaning]
2522                       If true, the meaning and use of this parameter is                       If true, the meaning and use of this parameter is
2523                       reserved and defined by a standard model.  If false,                       reserved and defined by a standard model.  If false,
2524                       it represents a database-specific parameter                       it represents a parameter specific to the data described
2525                       that effectively extends beyond the standard.  If                       If not provided, then the value is unknown.
                      not provided, then the value is unknown.  
2526                                        
2527  \item[Occurrence] optional  \item[Occurrence] optional
2528  \end{description}  \end{description}
# Line 2459  Line 2538 
2538  \begin{description}  \begin{description}
2539  \item[Type] \xmlel{vs:DataType} with optional attributes  \item[Type] \xmlel{vs:DataType} with optional attributes
2540  \item[Meaning]  \item[Meaning]
2541                          a type of data contained in the column                          A type of data contained in the column
2542                                            
2543  \item[Occurrence] optional  \item[Occurrence] optional
2544    
# Line 2468  Line 2547 
2547  \begin{description}  \begin{description}
2548  \item[Type] string: \xmlel{xs:token}  \item[Type] string: \xmlel{xs:token}
2549  \item[Meaning]  \item[Meaning]
2550                          a keyword representing traits of the column.                            A keyword representing traits of the column.  
2551                          Recognized values include “indexed”, “primary”, and                          Recognized values include “indexed”, “primary”, and
2552                          “nullable”.                            “nullable”.  
2553                                            
# Line 2495  Line 2574 
2574  XML type, \xmlel{vs:TableDataType}, is abstract, the  XML type, \xmlel{vs:TableDataType}, is abstract, the
2575  element MUST include an  element MUST include an
2576  \xmlel{xsi:type} attribute.  As discussed in  \xmlel{xsi:type} attribute.  As discussed in
2577  sect.~\ref{sect:tbldatatypes}, this should generally be  sect.~\ref{sect:tbldatatypes}, this SHOULD be
2578  \xmlel{vs:VOTableType} for VODataService 1.2 table columns.  \xmlel{vs:VOTableType} for VODataService 1.2 table columns.
2579    
2580  When the tableset describes a set of TAP-accessible tables, the value of  When the tableset describes a set of TAP-accessible tables, the value of
# Line 2511  Line 2590 
2590  a double-valued declination, of the (deprecated) \verb|size| column  a double-valued declination, of the (deprecated) \verb|size| column
2591  from TAP 1.0 which requires quotes because it otherwise clashes with a  from TAP 1.0 which requires quotes because it otherwise clashes with a
2592  SQL reserved name, and a SIAP 1.0-compatible \verb|wcs_cdmatrix|  SQL reserved name, and a SIAP 1.0-compatible \verb|wcs_cdmatrix|
2593  column that shows how multidimensional arrays are declared:  column that shows how multidimensional arrays are declared; note that in
2594    the last case, the content of \xmlel{unit} pertains to \emph{elements}
2595    of the array, not the array as a whole.
2596    
2597  \begin{lstlisting}[language=XML,basicstyle=\footnotesize]  \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2598  <column>  <column>
# Line 2543  Line 2624 
2624  \label{sect:tbldatatypes}  \label{sect:tbldatatypes}
2625    
2626    
2627  The VODataService schema defines two XML types that derive from  The VODataService schema defines two type systems that derive from
2628  \xmlel{vs:TableDataType}:  \xmlel{vs:VOTableType} and  \xmlel{vs:TableDa\-taType}:  \xmlel{vs:VOTableType} and
2629  \xmlel{vs:TAPType}.  Following the move to VOTable-compatible type  \xmlel{vs:TAPType}.  Following the move to VOTable-compatible type
2630  descriptions in TAP 1.1 \citep{todo:TAP1.1}, this version of  descriptions in TAP 1.1 \citep{todo:TAP1.1}, this version of
2631  VODataService deprecates the use of \xmlel{vs:TAPType}.  New software  VODataService deprecates the use of \xmlel{vs:TAPType}.  New software
# Line 2558  Line 2639 
2639          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Documentation}          \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Documentation}
2640    
2641  \noindent{\small  \noindent{\small
2642              a data type supported explicitly by the VOTable format              A data type supported explicitly by the VOTable format
2643           \par}           \par}
2644    
2645  \vspace{1ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Definition}
# Line 2595  Line 2676 
2676  \item[arraysize]  \item[arraysize]
2677  \begin{description}  \begin{description}
2678  \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}  \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2679  \item[Meaning]  \item[Meaning] See vs:DataType.
2680  \item[Occurrence] optional  \item[Occurrence] optional
2681    
2682  \end{description}  \end{description}
2683  \item[delim]  \item[delim]
2684  \begin{description}  \begin{description}
2685  \item[Type] string: \xmlel{xs:string}  \item[Type] string: \xmlel{xs:string}
2686  \item[Meaning]  \item[Meaning] See vs:DataType.
2687  \item[Occurrence] optional  \item[Occurrence] optional
2688    
2689  \end{description}  \end{description}
2690  \item[extendedType]  \item[extendedType]
2691  \begin{description}  \begin{description}
2692  \item[Type] string: \xmlel{xs:string}  \item[Type] string: \xmlel{xs:string}
2693  \item[Meaning]  \item[Meaning] See vs:DataType.
2694  \item[Occurrence] optional  \item[Occurrence] optional
2695  \end{description}  \end{description}
2696  \item[extendedSchema]  \item[extendedSchema]
2697  \begin{description}  \begin{description}
2698  \item[Type] a URI: \xmlel{xs:anyURI}  \item[Type] a URI: \xmlel{xs:anyURI}
2699  \item[Meaning]  \item[Meaning] See vs:DataType.
2700  \item[Occurrence] optional  \item[Occurrence] optional
2701  \end{description}  \end{description}
2702    
# Line 2645  Line 2726 
2726  \subsection{Changes since  WD-20181026}  \subsection{Changes since  WD-20181026}
2727    
2728  \begin{itemize}  \begin{itemize}
2729    \item Adding a summary of the discovering data collections EN.
2730  \item Spatial coverage now has a frame attribute.  \item Spatial coverage now has a frame attribute.
2731    \item Added a SHOULD requirement on CatalogResources to have a tableset.
2732    \item Restricted interface/@testQuery to zero or one occurrences (this
2733    is because there is no clear semantics to having multiple of those).
2734  \end{itemize}  \end{itemize}
2735    
2736  \subsection{Changes since REC-1.1}  \subsection{Changes since REC-1.1}
# Line 2669  Line 2754 
2754  place (e.g., for string arrays).  Now discouraging the use of delim  place (e.g., for string arrays).  Now discouraging the use of delim
2755  outside of InputParams.  outside of InputParams.
2756  \item Deprecated TAPType.  \item Deprecated TAPType.
2757    \item extendedType is now defined to correspond to VOTable xtypes in the
2758    absence of extendedSchema.
2759  \item No longer requiring unique table names within a tableset;  \item No longer requiring unique table names within a tableset;
2760  uniquness is now required within a schema (actually, many services have  uniquness is now required within a schema (actually, many services have
2761  been in violation of the old unique-within-tableset rule for a long time  been in violation of the old unique-within-tableset rule for a long time
2762  without operational difficulties).  without operational difficulties); but then that's largely a moot point
2763    because for the main uses of tableset, fully qualified names are now
2764    required.
2765  \item Ported source to \ivoatex.  \item Ported source to \ivoatex.
2766  \end{itemize}  \end{itemize}
2767    

Legend:
Removed from v.5508  
changed lines
  Added in v.5509

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