/[volute]/trunk/projects/grid/VOSI/VOSI.tex
ViewVC logotype

Diff of /trunk/projects/grid/VOSI/VOSI.tex

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

revision 3763 by major.brian, Mon Nov 21 21:40:27 2016 UTC revision 3764 by major.brian, Wed Dec 14 23:23:33 2016 UTC
# Line 88  Line 88 
88  \section{Interface bindings}  \section{Interface bindings}
89  \label{sec:bindings}  \label{sec:bindings}
90    
91    This section explains how services are to report VO support metadata through a standard interface.
92    
93  The standard interface returns metadata without changing the state of the service with which it is associated. This standard requires a REST binding of VOSI even when applied to services that do not have a RESTful interface.  The standard interface returns metadata without changing the state of the service with which it is associated. This standard requires a REST binding of VOSI even when applied to services that do not have a RESTful interface.
94    
95  In the REST binding, the support interfaces shall have distinct URLs in the HTTP scheme and shall be accessible by the GET operation in the HTTP protocol. The response to an HTTP POST, PUT or DELETE to these resources is not defined by this specification. However, if an implementation has no special action to perform for these requests, the normal response would be a HTTP 405 "Method not allowed" status code.  In the REST binding, the support interfaces shall have distinct URLs in the HTTP scheme and shall be accessible by the GET operation in the HTTP protocol. The response to an HTTP POST, PUT or DELETE to these resources is not defined by this specification. However, if an implementation has no special action to perform for these requests, the normal response would be a HTTP 405 "Method not allowed" status code.  Both the capabilities and availability bindings must be available to anonymous requests.
96    
97  The endpoints and interface types for the support interface shall be defined in the service's registration using one \xmlel{capability} element for each interface. The values of the \xmlel{standardID} attribute for these Capabilities are given in section~\ref{sec:endpoints}.  The endpoints and interface types for the support interface shall be defined in the service's registration using one \xmlel{capability} element for each interface. The values of the \xmlel{standardID} attribute for these Capabilities are given in section~\ref{sec:endpoints}.
98    
# Line 136  Line 138 
138  \item it may be read by the registry itself to compile the registry entry for the service. In this case, the resource metadata are entered into the registry directly and the service metadata are then read from the service. Since the service implementation usually knows its capabilities, this removes the need for a human to type them into the registry.  \item it may be read by the registry itself to compile the registry entry for the service. In this case, the resource metadata are entered into the registry directly and the service metadata are then read from the service. Since the service implementation usually knows its capabilities, this removes the need for a human to type them into the registry.
139  \end{itemize}  \end{itemize}
140    
141  The service metadata shall be represented as an XML document with the root element \xmlel{http://www.ivoa.net/xml/VOSICapabilities/v1.0\#capabilities}. (See Appendix \ref{appendix:capabilities} for the definition of the VOSICapabilities XML schema.) This element must contain one or more child capability elements that describe the capabilities of the service. Given that the capability element is defined to be of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}, a capability element may be represented by a legal sub-type of  The service metadata shall be represented as an XML document with the root element:\\
142  \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}, in which case, the capability element must use an \xmlel{xsi:type} attribute to identify the sub-type (see section 2.2.1 of VOResource \citep{std:VOR}).  $$\hbox{\xmlel{http://www.ivoa.net/xml/VOSICapabilities/v1.0\#capabilities}}$$\\
143    (See Appendix \ref{appendix:capabilities} for the definition of the VOSICapabilities XML schema.) This element must contain one or more child capability elements that describe the capabilities of the service. Given that the capability element is defined to be of type\\
144    $$\hbox{\xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}}$$\\
145    a capability element may be represented by a legal sub-type of\\
146    $$\hbox{\xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}}$$\\
147    in which case, the capability element must use an \xmlel{xsi:type} attribute to identify the sub-type (see section 2.2.1 of VOResource \citep{std:VOR}).
148    
149  \begin{admonition}{Note}  \begin{admonition}{Note}
150  The value of the capability element's \xmlel{standardID} attribute is used to indicate the service's support for particular standard protocols (such as Simple Image Access, Simple Cone Search, etc.). In the case of some protocols, the support for the standard is further characterized by additional metadata provided by a standard XML schema extension of \xmlel{Capability} for that protocol. The extension metadata is enabled by adding a \xmlel{xsi:type} attribute to the capability element set to the Capability sub-type value defined in the extension schema for that protocol (see example below).  The value of the capability element's \xmlel{standardID} attribute is used to indicate the service's support for particular standard protocols (such as Simple Image Access, Simple Cone Search, etc.). In the case of some protocols, the support for the standard is further characterized by additional metadata provided by a standard XML schema extension of \xmlel{Capability} for that protocol. The extension metadata is enabled by adding a \xmlel{xsi:type} attribute to the capability element set to the Capability sub-type value defined in the extension schema for that protocol (see example below).
# Line 194  Line 200 
200    
201  The VODataService standard \citep{std:VODS11} defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.  The VODataService standard \citep{std:VODS11} defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
202    
203  A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata for all content of a service shall be represented as an XML document of which the root element is of type  A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata for all content of a service shall be represented as an XML document of which the root element is of type\\
204  \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#TableSet}. The table metadata for a single table (see below) shall be represented as an  $$\hbox{\xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#TableSet}}$$\\
205  XML document of which the root element is of type \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#Table}. This element may contain any mix of elements allowed by the VODataService XML schema.  The table metadata for a single table (see below) shall be represented as an
206    XML document of which the root element is of type\\
207    $$\hbox{\xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#Table}}$$\\
208    This element may contain any mix of elements allowed by the VODataService XML schema.
209    
210  In the REST binding, the TableSet metadata shall be a hierarchical web resource with a registered URL.  There are two levels of TableSet metadata detail that may be returned from the base \textit{tables} endpoint.  Maximum detail (max) is the complete metadata including all details of the Table elements.  Minimum detail (min) includes the full set of Table elements with names and optional descriptions, but does not include Table elements of type Column or ForeignKey.  In the REST binding, the TableSet metadata shall be a hierarchical web resource with a registered URL.  There are two levels of TableSet metadata detail that may be returned from the base \textit{tables} endpoint.  Maximum detail (max) is the complete metadata including all details of the Table elements.  Minimum detail (min) includes the full set of Table elements with names and optional descriptions, but does not include Table elements of type Column or ForeignKey.
211    
# Line 245  Line 254 
254    
255  A capabilities endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI#capabilities}.  A capabilities endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI#capabilities}.
256    
257  A tables endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI\#tables}.  A tables endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI\#tables}, or, for version 1.1, \nolinkurl{ivo://ivoa.net/std/VOSI\#tables-1.1}.
258    
259  With all three VOSI functions, the \xmlel{capability} element that describes the function must contain an \xmlel{interface} element of a type semantically appropriate for the binding of the function to the service; the \xmlel{accessURL} element within the \xmlel{interface} element indicates the endpoint for the VOSI function. For the REST binding, this \xmlel{accessURL} element must set the \xmlel{use} attribute to \texttt{"full"}. Furthermore, for the REST binding, this document recommends using the \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#ParamHTTP} interface type to encode VOSI endpoints (see the examples given in section~\ref{sec:examples}).  With all three VOSI functions, the \xmlel{capability} element that describes the function must contain an \xmlel{interface} element of a type semantically appropriate for the binding of the function to the service; the \xmlel{accessURL} element within the \xmlel{interface} element indicates the endpoint for the VOSI function. For the REST binding, this \xmlel{accessURL} element must set the \xmlel{use} attribute to \texttt{"full"}. Furthermore, for the REST binding, this document recommends using the \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#ParamHTTP} interface type to encode VOSI endpoints (see the examples given in section~\ref{sec:examples}).
260    
# Line 262  Line 271 
271  <?xml version="1.0" encoding="UTF-8"?>  <?xml version="1.0" encoding="UTF-8"?>
272  <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"  <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
273      xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"      xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
274      xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"      xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
275      xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"      xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
276      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0  
         http://www.ivoa.net/xml/VOSI/v1.0  
       http://www.ivoa.net/xml/VOResource/v1.0  
         http://www.ivoa.net/xml/VOResource/v1.0  
       http://www.ivoa.net/xml/VODataService/v1.0  
         http://www.ivoa.net/xml/VODataService/v1.0  
       http://www.ivoa.net/xml/SIA/v1.0  
         http://www.ivoa.net/xml/SIA/v1.0">  
277    
278    <!-- a generic capability (for custom, non-standard interfaces) -->    <!-- a generic capability (for custom, non-standard interfaces) -->
279    <capability>    <capability>
# Line 354  Line 355 
355  <vosi:tableset  <vosi:tableset
356    xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"    xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
357    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
358    xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">    xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
359      version="1.1">
360    
361    <schema>    <schema>
362      <name>cfht </name>      <name>cfht </name>
# Line 362  Line 364 
364        <name>cfht.deepU </name>        <name>cfht.deepU </name>
365        <column>        <column>
366          <name>cfhtlsID </name>          <name>cfhtlsID </name>
367          <dataType xsi:type="vod:TAP" size="30">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="30">adql:VARCHAR </dataType>
368        </column>        </column>
369        <column>        <column>
370          <name>survey </name>          <name>survey </name>
371          <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="6">adql:VARCHAR </dataType>
372        </column>        </column>
373        <column>        <column>
374          <name>field </name>          <name>field </name>
375          <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="2">adql:VARCHAR </dataType>
376        </column>        </column>
377        <column>        <column>
378          <name>pointing </name>          <name>pointing </name>
379          <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="6">adql:VARCHAR </dataType>
380        </column>        </column>
381        <column>        <column>
382          <name>selectionFilter </name>          <name>selectionFilter </name>
383          <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="2">adql:VARCHAR </dataType>
384        </column>        </column>
385      </table>      </table>
386    
# Line 388  Line 390 
390          <name>key_id </name>          <name>key_id </name>
391          <description>unique key to join to TAP_SCHEMA.key_columns          <description>unique key to join to TAP_SCHEMA.key_columns
392          </description>          </description>
393          <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
394        </column>        </column>
395        <column>        <column>
396          <name>from_table </name>          <name>from_table </name>
397          <description>the table with the foreign key </description>          <description>the table with the foreign key </description>
398          <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
399        </column>        </column>
400        <column>        <column>
401          <name>target_table </name>          <name>target_table </name>
402          <description>the table with the primary key </description>          <description>the table with the primary key </description>
403          <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>          <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
404        </column>        </column>
405      </table>      </table>
406    
# Line 416  Line 418 
418  <vosi:tableset  <vosi:tableset
419    xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"    xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
420    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
421    xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">    xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
422      version="1.1">
423    
424    <schema>    <schema>
425      <name>cfht </name>      <name>cfht </name>
# Line 451  Line 454 
454  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
455  <?xml version="1.0" encoding="UTF-8"?>  <?xml version="1.0" encoding="UTF-8"?>
456  <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"  <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
457      xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1"      xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
458      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
459        type="output" version="1.1">
460    <name>TAP_SCHEMA.columns</name>    <name>TAP_SCHEMA.columns</name>
461    <column>    <column>
462      <name>table_name</name>      <name>table_name</name>
463      <description>the table this column belongs to</description>      <description>the table this column belongs to</description>
464      <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
465    </column>    </column>
466    <column>    <column>
467      <name>column_name</name>      <name>column_name</name>
468      <description>the column name</description>      <description>the column name</description>
469      <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
470    </column>    </column>
471    <column>    <column>
472      <name>utype</name>      <name>utype</name>
473      <description>lists the utypes of columns in the tableset</description>      <description>lists the utypes of columns in the tableset</description>
474      <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="512">VARCHAR</dataType>
475    </column>    </column>
476    <column>    <column>
477      <name>ucd</name>      <name>ucd</name>
478      <description>lists the UCDs of columns in the tableset</description>      <description>lists the UCDs of columns in the tableset</description>
479      <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
480    </column>    </column>
481    <column>    <column>
482      <name>unit</name>      <name>unit</name>
483      <description>lists the unit used for column values in the tableset</description>      <description>lists the unit used for column values in the tableset</description>
484      <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
485    </column>    </column>
486    <column>    <column>
487      <name>description</name>      <name>description</name>
488      <description>describes the columns in the tableset</description>      <description>describes the columns in the tableset</description>
489      <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="512">VARCHAR</dataType>
490    </column>    </column>
491    <column>    <column>
492      <name>datatype</name>      <name>datatype</name>
493      <description>lists the ADQL datatype of columns in the tableset</description>      <description>lists the ADQL datatype of columns in the tableset</description>
494      <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>      <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
495    </column>    </column>
496    <column>    <column>
497      <name>size</name>      <name>size</name>
498      <description>lists the size of variable-length columns in the tableset</description>      <description>lists the size of variable-length columns in the tableset</description>
499      <dataType xsi:type="vod:TAPType">INTEGER</dataType>      <dataType xsi:type="vs:TAPType">INTEGER</dataType>
500    </column>    </column>
501    <column>    <column>
502      <name>principal</name>      <name>principal</name>
503      <description>a principal column; 1 means 1, 0 means 0</description>      <description>a principal column; 1 means 1, 0 means 0</description>
504      <dataType xsi:type="vod:TAPType">INTEGER</dataType>      <dataType xsi:type="vs:TAPType">INTEGER</dataType>
505    </column>    </column>
506    <column>    <column>
507      <name>indexed</name>      <name>indexed</name>
508      <description>an indexed column; 1 means 1, 0 means 0</description>      <description>an indexed column; 1 means 1, 0 means 0</description>
509      <dataType xsi:type="vod:TAPType">INTEGER</dataType>      <dataType xsi:type="vs:TAPType">INTEGER</dataType>
510    </column>    </column>
511    <column>    <column>
512      <name>std</name>      <name>std</name>
513      <description>a standard column; 1 means 1, 0 means 0</description>      <description>a standard column; 1 means 1, 0 means 0</description>
514      <dataType xsi:type="vod:TAPType">INTEGER</dataType>      <dataType xsi:type="vs:TAPType">INTEGER</dataType>
515    </column>    </column>
516    <foreignKey>    <foreignKey>
517      <targetTable>TAP_SCHEMA.tables</targetTable>      <targetTable>TAP_SCHEMA.tables</targetTable>
# Line 542  Line 546 
546      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
547      elementFormDefault="qualified"      elementFormDefault="qualified"
548      attributeFormDefault="unqualified"      attributeFormDefault="unqualified"
549      version="1.0rc1">      version="1.1">
550    
551    <xsd:annotation>    <xsd:annotation>
552       <xsd:documentation>       <xsd:documentation>
# Line 606  Line 610 
610      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
611      elementFormDefault="qualified"      elementFormDefault="qualified"
612      attributeFormDefault="unqualified"      attributeFormDefault="unqualified"
613      version="1.0rc1">      version="1.1">
614    
615    <xsd:annotation>    <xsd:annotation>
616       <xsd:documentation>       <xsd:documentation>

Legend:
Removed from v.3763  
changed lines
  Added in v.3764

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