/[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 5929 by msdemlei, Wed Aug 26 11:14:48 2020 UTC revision 5930 by msdemlei, Tue Feb 23 09:45:51 2021 UTC
# Line 41  Line 41 
41  \editor{Markus Demleitner}  \editor{Markus Demleitner}
42  \editor{Ray Plante}  \editor{Ray Plante}
43    
44    \previousversion[https://ivoa.net/documents/VODataService/20190715/PR-VODataService-1.2-20190715.html]{PR-2019-07-15}
45    \previousversion[https://ivoa.net/documents/VODataService/20181026/]{WD-2018-10-26}
46  \previousversion[http://www.ivoa.net/Documents/VODataService/20101202]{REC  \previousversion[http://www.ivoa.net/Documents/VODataService/20101202]{REC
47  1.1}  1.1}
 \previousversion[http://www.ivoa.net/Documents/VODataService/20100916]{PR-20100916}  
 \previousversion[http://www.ivoa.net/Documents/VODataService/20100914]{PR-20100914}  
 \previousversion[http://www.ivoa.net/Documents/VODataService/20100412]{PR-20100412}  
 \previousversion[http://www.ivoa.net/Documents/VODataService/20090903]{PR-20090903}  
 \previousversion[http://www.ivoa.net/Documents/WD/ReR/VODataService-20090508.html]{WD-20090508}  
       
48    
49  \begin{document}  \begin{document}
50  \begin{abstract}  \begin{abstract}
# Line 181  Line 177 
177  schema for the responses on the table metadata endpoint.  It also  schema for the responses on the table metadata endpoint.  It also
178  defines the ParamHTTP interface type currently used in the capabilities of most  defines the ParamHTTP interface type currently used in the capabilities of most
179  standard protocols.  standard protocols.
180  \item[RefTAP, v1.0 \citep{2014ivoa.spec.1208D}] RegTAP maps the concepts  \item[RegTAP, v1.0 \citep{2014ivoa.spec.1208D}] RegTAP maps the concepts
181  defined here into a relational structure.  In that sense it is the  defined here into a relational structure.  In that sense it is the
182  user interface to what is specified here.  user interface to what is specified here.
183  \end{description}  \end{description}
# Line 378  Line 374 
374  VODataService instance documents.  Hence, the namespace URI ending in  VODataService instance documents.  Hence, the namespace URI ending in
375  \verb|1.1| is also used for schema versions 1.2, 1.3, and so forth.  \verb|1.1| is also used for schema versions 1.2, 1.3, and so forth.
376    
 While VODataService 1.2 is not in REC\todo{Remove this before going  
 REC}, the draft schema file can be retrieved from the document  
 repository\footnote{For this WD: \auxiliaryurl{VODataService-v1.2.xsd}}.  
   
377  Resolving the VODataService namespace URI will redirect to a schema  Resolving the VODataService namespace URI will redirect to a schema
378  document having the actual version number (for the schema associated  document having the actual version number (for the schema associated
379  with this document version, this will end in VODataService-1.2.xsd).  with this document version, this will end in VODataService-1.2.xsd).
# Line 939  Line 931 
931  Resources that need to communicate high-resolution spatial coverage,  Resources that need to communicate high-resolution spatial coverage,
932  perhaps for some non-discovery use case, can use the \xmlel{footprint}  perhaps for some non-discovery use case, can use the \xmlel{footprint}
933  element with its \xmlel{ivo-id} attribute set to  element with its \xmlel{ivo-id} attribute set to
934  \nolinkurl{ivo://ivoa.net/std/moc} \todo{This doesn't match what this  \nolinkurl{ivo://ivoa.net/std/moc} to declare a URL giving a
 ivo-id was originally intended to be.  Can we hijack it like this and  
 change the semantics?} to declare a URL giving a  
935  footprint in one of the approved MOC serialisations and of arbitrary  footprint in one of the approved MOC serialisations and of arbitrary
936  level and size.  level and size.
937    
# Line 1285  Line 1275 
1275  (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance  (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance
1276  cross-correlations between them.  Each catalogue can be described in a  cross-correlations between them.  Each catalogue can be described in a
1277  separate \xmlel{schema} element, using the elements from  separate \xmlel{schema} element, using the elements from
1278  the \xmlel{vs:TableSchema} type.\todo{Is is a good idea to use  the \xmlel{vs:TableSchema} type.
 ``default'' as the NULL value?  Or should we rather have minOccurs 0 for  
 @name?}  
   
1279    
1280    
1281  % GENERATED: !schemadoc VODataService-v1.2.xsd TableSchema  % GENERATED: !schemadoc VODataService-v1.2.xsd TableSchema
# Line 1419  Line 1406 
1406      <xs:element name="title" type="xs:token" minOccurs="0" />      <xs:element name="title" type="xs:token" minOccurs="0" />
1407      <xs:element name="description" type="xs:token" minOccurs="0" />      <xs:element name="description" type="xs:token" minOccurs="0" />
1408      <xs:element name="utype" type="xs:token" minOccurs="0" />      <xs:element name="utype" type="xs:token" minOccurs="0" />
1409      <xs:element name="nrows" type="xs:NonNegativeInteger" minOccurs="0"      <xs:element name="nrows" type="xs:nonNegativeInteger" minOccurs="0"
1410                maxOccurs="1" />                maxOccurs="1" />
1411      <xs:element name="column" type="vs:TableParam" minOccurs="0"      <xs:element name="column" type="vs:TableParam" minOccurs="0"
1412                maxOccurs="unbounded" />                maxOccurs="unbounded" />
# Line 1440  Line 1427 
1427  \item[Meaning]  \item[Meaning]
1428                 A name for the role this table plays.  Recognized                 A name for the role this table plays.  Recognized
1429                 values include “output”, indicating this table is output                 values include “output”, indicating this table is output
1430                 from a query; “base\_table{"}, indicating a table                 from a query; “base\_table”, indicating a table
1431                 whose records represent the main subjects of its                 whose records represent the main subjects of its
1432                 schema; and “view”, indicating that the table represents                 schema; and “view”, indicating that the table represents
1433                 a useful combination or subset of other tables.  Other                 a useful combination or subset of other tables.  Other
# Line 1514  Line 1501 
1501  \end{description}  \end{description}
1502  \item[Element \xmlel{nrows}]  \item[Element \xmlel{nrows}]
1503  \begin{description}  \begin{description}
1504  \item[Type] non-negative integer  \item[Type] \xmlel{xs:nonNegativeInteger}
1505  \item[Meaning]  \item[Meaning]
1506                    The size of the table in rows.                    The size of the table in rows.
1507                                
# Line 1813  Line 1800 
1800                                            
1801  \item[Occurrence] optional; up to 2 occurrences allowed.  \item[Occurrence] optional; up to 2 occurrences allowed.
1802    
1803  \item[Allowed Values]\hfil  \item[Terms]\hfil
1804  \begin{longtermsdescription}  \begin{longtermsdescription}
1805  \item[GET]  \item[GET]
1806  \item[POST]  \item[POST]
# Line 1882  Line 1869 
1869  use of \verb|xsi:type="vs:ParamHTTP"| indicates that the interface  use of \verb|xsi:type="vs:ParamHTTP"| indicates that the interface
1870  accessed via the URL given by the \xmlel{accessURL}  accessed via the URL given by the \xmlel{accessURL}
1871  element complies with the general parameter-based protocol described  element complies with the general parameter-based protocol described
1872  in this section.\todo{resultType stinks when we have DALI  in this section.
1873  RESPONSEFORMAT.  Would anyone miss it?  If so, how can we fix it?}  
1874    % resultType stinks when we have DALI RESPONSEFORMAT.  Let's think
1875    % about fixing this in 1.3.
1876    
1877    
1878    
# Line 2027  Line 2016 
2016                    There are no requirements for compliance with any                    There are no requirements for compliance with any
2017                    particular UCD standard.  The format of the UCD can                    particular UCD standard.  The format of the UCD can
2018                    be used to distinguish between UCD1, UCD1+, and                    be used to distinguish between UCD1, UCD1+, and
2019                    SIA-UCD.  See                    SIA-UCD.
                   http://ivoa.net/Documents/latest/UCDlist.html  
                   for the latest IVOA standard set.    
2020                                
2021    
2022  \end{description}  \end{description}
# Line 2210  Line 2197 
2197  given in the type's element content, then, represents a commonly  given in the type's element content, then, represents a commonly
2198  understood “fallback” type.  For instance, in VOTable, timestamps are  understood “fallback” type.  For instance, in VOTable, timestamps are
2199  serialised into strings, which implies a VOTableType of char with  serialised into strings, which implies a VOTableType of char with
2200  arraysize *, as supported by all VOTable readers.  VOTable readers  arraysize \verb|*|, as supported by all VOTable readers.  VOTable readers
2201  interpreting the timestamp xtype, however, can turn this string into a  interpreting the timestamp xtype, however, can turn this string into a
2202  timestamp value native to its clients.  Such readers will interpret  timestamp value native to its clients.  Such readers will interpret
2203  a VOTable FIELD's xtype attribute. Such information is reflected in  a VOTable \xmlel{FIELD}'s \xmlel{xtype} attribute.
2204  \xmlel{extendedType}.    Such information is reflected in \xmlel{extendedType}.  
2205    
2206  Arbitrary information can also be  Arbitrary information can also be
2207  provided via any prefix-qualified, globally defined attribute drawn  provided via any prefix-qualified, globally defined attribute drawn
# Line 2242  Line 2229 
2229    
2230  Actual parameters are normally described with types derived from  Actual parameters are normally described with types derived from
2231  \xmlel{vs:BaseParam}.  The \xmlel{vs:InputParam} is intended  \xmlel{vs:BaseParam}.  The \xmlel{vs:InputParam} is intended
2232  for describing an input parameter to a service or function.  In this  for describing an input parameter to a service or function.  In previous
2233  version of VODataService, input parameters are restricted to be defined  versions of VODataService, input parameters were restricted to be defined
2234  in terms of simple data types\todo{On the other hand,  in terms of simple data types, which are intended to be
 also allowing VOTable types here would help a lot with, e.g., SODA and  
 friends.  If no objections are raised, we'll allow arbitrary type  
 systems here in REC.} which do not  
 imply a size or precise format. Rather, they are intended to be  
2235  sufficient for describing an input parameter to a simple REST-like  sufficient for describing an input parameter to a simple REST-like
2236  service or a function in a weakly-typed language.  They are defined  service or a function in a weakly-typed language.  They are defined
2237  in \xmlel{vs:SimpleDataType}:  in \xmlel{vs:SimpleDataType}:
# Line 2329  Line 2312 
2312    
2313  % /GENERATED  % /GENERATED
2314    
2315  The \xmlel{vs:InputParam} class then is a \xmlel{vs:DataType}  Since VODataService 1.2, input parameters can use any type system,
2316  constrained to these types and furnished with additional metadata  where non-DALI-compliant services SHOULD use \xmlel{vs:SimpleDataType}
2317    and DALI-compliant services SHOULD use \xmlel{vs:VOTableType}.  To
2318    ensure schema validation catches error, resource record authors are
2319    advised to declare the type system intended using \xmlel{xsi:type}; for
2320    instance, an SSAP service might declare:
2321    
2322    \begin{lstlisting}[language=XML]
2323      <param std="true">
2324        <name>POS</name>
2325        <description>ICRS position of target object</description>
2326        <dataType arraysize="*"
2327          xsi:type="vs:VOTableType"
2328          extendedType="point">char</dataType>
2329      </param>
2330    \end{lstlisting}
2331    
2332    The \xmlel{vs:InputParam} class then is a \xmlel{vs:BaseParam}
2333    furnished with additional metadata
2334  defining how to use the parameter and whether or not it is defined in  defining how to use the parameter and whether or not it is defined in
2335  the standard governing the capability the interface is in (if any):  the standard governing the capability the interface is in (if any):
2336    
# Line 2347  Line 2347 
2347           \par}           \par}
2348    
2349  \noindent{\small  \noindent{\small
2350              The allowed data type names do not imply a size or precise                  DALI-compliant services should use vs:VOTableType here, others
2351              format.  This type is intended to be sufficient for describing                  should use vs:SimpleDataType.
             an input parameter to a simple REST service or a function  
             written in a weakly-typed language.  
2352           \par}           \par}
2353    
2354  \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition}  \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition}
# Line 2360  Line 2358 
2358    <xs:complexContent >    <xs:complexContent >
2359      <xs:extension base="vs:BaseParam" >      <xs:extension base="vs:BaseParam" >
2360        <xs:sequence >        <xs:sequence >
2361          <xs:element name="dataType" type="vs:SimpleDataType" minOccurs="0" />          <xs:element name="dataType" type="vs:DataType" minOccurs="0" />
2362        </xs:sequence>        </xs:sequence>
2363        <xs:attribute name="use" type="vs:ParamUse" default="optional" />        <xs:attribute name="use" type="vs:ParamUse" default="optional" />
2364        <xs:attribute name="std" type="xs:boolean" default="true" />        <xs:attribute name="std" type="xs:boolean" default="true" />
# Line 2382  Line 2380 
2380                                        
2381  \item[Occurrence] optional  \item[Occurrence] optional
2382    
2383  \item[Allowed Values]\hfil  \item[Terms]\hfil
2384  \begin{longtermsdescription}  \begin{longtermsdescription}
2385  \item[required]  \item[required]
2386                    The parameter is required for the application or                    The parameter is required for the application or
# Line 2422  Line 2420 
2420    
2421  \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}]  \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}]
2422  \begin{description}  \begin{description}
2423  \item[Type] composite: \xmlel{vs:SimpleDataType}  \item[Type] a string with optional attributes
2424  \item[Meaning]  \item[Meaning]
2425                          A type of data contained in the parameter                          A type of data contained in the parameter.
2426                                            
2427  \item[Occurrence] optional  \item[Occurrence] optional
2428    
# Line 2608  Line 2606 
2606  The VODataService schema defines two type systems that derive from  The VODataService schema defines two type systems that derive from
2607  \xmlel{vs:TableDa\-taType}:  \xmlel{vs:VOTableType} and  \xmlel{vs:TableDa\-taType}:  \xmlel{vs:VOTableType} and
2608  \xmlel{vs:TAPType}.  Following the move to VOTable-compatible type  \xmlel{vs:TAPType}.  Following the move to VOTable-compatible type
2609  descriptions in TAP 1.1 \citep{todo:TAP1.1}, this version of  descriptions in TAP 1.1 \citep{2019ivoa.spec.0927D}, this version of
2610  VODataService deprecates the use of \xmlel{vs:TAPType}.  New software  VODataService deprecates the use of \xmlel{vs:TAPType}.  New software
2611  should only generate \xmlel{vs:VOTableType}s in \xmlel{tableset}s.  should only generate \xmlel{vs:VOTableType}s in \xmlel{tableset}s.
2612    
# Line 2707  Line 2705 
2705  \subsection{Changes since PR-20190715}  \subsection{Changes since PR-20190715}
2706    
2707  \begin{itemize}  \begin{itemize}
2708    \item dropped \verb|vs:Waveband| and changed waveband to being
2709    controlled by a vocabulary that initially grows a generic Photon and a
2710    Neutrino concept over what the previous Waveband had.
2711  \item table/@nrows is now constrained to be non-negative.  \item table/@nrows is now constrained to be non-negative.
2712    \item Now allowing any vs:DataType element to define vs:InputParams.
2713    In order to still ensure schema validation of type names,
2714    now advising to have an explicit xsi:type in param's dataTypes.
2715  \end{itemize}  \end{itemize}
2716    
2717  \subsection{Changes since  WD-20181026}  \subsection{Changes since  WD-20181026}

Legend:
Removed from v.5929  
changed lines
  Added in v.5930

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