/[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 3232 by pdowler.cadc, Wed Jan 27 21:48:47 2016 UTC revision 3233 by pdowler.cadc, Wed Jan 27 23:03:44 2016 UTC
# Line 13  Line 13 
13    
14  \editor{Matthew Graham}  \editor{Matthew Graham}
15  \editor{Guy Rixon}  \editor{Guy Rixon}
16    \editor{Patrick Dowler}
17    
18  %\previousversion[http://www.ivoa.net/documents/VOSI/20110531/REC-VOSI-1.0-20110531.html]{VOSI-1.0}  \previousversion[http://www.ivoa.net/documents/VOSI/20110531/REC-VOSI-1.0-20110531.html]{VOSI-1.0}
19    
20  \begin{document}  \begin{document}
21  \begin{abstract}  \begin{abstract}
# Line 189  Line 190 
190    
191  The VODataService standard [14] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.  The VODataService standard [14] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
192    
193  A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata shall be represented as an XML document of which the root element is of type {http://www.ivoa.net/xml/VODataService/v1.1}TableSet. This element may contain any mix of elements allowed by the VODataService XML schema.  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
194    {http://www.ivoa.net/xml/VODataService/v1.1}TableSet. The table metadata for a single table (see below) shall be represented as an
195    XML document of which the root element is of type {http://www.ivoa.net/xml/VODataService/v1.1}Table. This element may contain any mix of elements allowed by the VODataService XML schema.
196    
197  In the REST binding, the table metadata shall be a single web resource with a registered URL.  In the REST binding, the tableset metadata shall be a hierarchical web resource with a registered URL. This base REST endpoint must support an optional query parameter named detail with value min.
198    
199    \begin{verbatim}
200    GET http://example.net/srv/tables?detail=min
201    \end{verbatim}
202    
203    If the caller requests detail=min, the response (TableSet) document must not incude elements of type Column or ForeignKey; the tables described have names and optional descriptions but no column or foreigh key details).
204    
205    The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be
206    named with the fully-qualified table name and without any intervening schema name. For example:
207    
208    \begin{verbatim}
209    GET http://example.net/srv/tables/ivoa.ObsCore
210    \end{verbatim}
211    
212    would return a Table document describing the ivoa.ObsCore table.
213    
214    Services with a large number of tables and/or columns cannot normally respond with a usable TableSet document. These services may
215    force the caller to accept the minimum detail level by redirecting requests without the detail=min parameter. The redirect should use HTTP status code 303 (See Other) with a (HTTP header) Location value that includes the detail=min parameter. Clients can make use of detail=min to get a list of available tables and then use the child table resource to get details about individual tables.
216    
217    
218  \section{Registration of VOSI endpoints}  \section{Registration of VOSI endpoints}
219    
# Line 202  Line 224 
224  Endpoint type & standardID value \\  Endpoint type & standardID value \\
225  availability & ivo://ivoa.net/std/VOSI\#availability \\  availability & ivo://ivoa.net/std/VOSI\#availability \\
226  capabilities & ivo://ivoa.net/std/VOSI\#capabilities \\  capabilities & ivo://ivoa.net/std/VOSI\#capabilities \\
227  tables & ivo://ivoa.net/std/VOSI\#tables \\  tables (1.0) & ivo://ivoa.net/std/VOSI\#tables \\
228    tables (1.1) & ivo://ivoa.net/std/VOSI\#tables-1.1 \\
229  \end{tabular}  \end{tabular}
230    
231  An availability endpoint shall be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability (defined by the standard VOResource XML schema [12]). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI\#availability.  An availability endpoint shall be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability (defined by the standard VOResource XML schema [12]). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI\#availability.
# Line 354  Line 377 
377  </vosi:tableset>  </vosi:tableset>
378  \end{lstlisting}  \end{lstlisting}
379    
380    Example 3:
381    A sample response from a tables resource with detail=min parameter (e.g. http://example.net/srv/tables?detail=min).
382    
383    \begin{lstlisting}[language=XML]
384    <?xml version="1.0" encoding="UTF-8"?>
385    <vosi:tableset
386      xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
387      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
388      xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
389    
390      <schema>
391        <name>cfht </name>
392        <table type="output">
393          <name>cfht.deepU </name>
394        </table>
395      </schema>
396      
397      <schema>
398        <name>TAP_SCHEMA</schema>
399        <table type="output">
400          <name>TAP_SCHEMA.tables </name>
401        </table>
402        <table type="output">
403          <name>TAP_SCHEMA.columns </name>
404        </table>
405        <table type="output">
406          <name>TAP_SCHEMA.keys </name>
407        </table>
408        <table type="output">
409          <name>TAP_SCHEMA.key_columns </name>
410        </table>
411      </schema>
412    
413    </vosi:tableset>
414    \end{lstlisting}
415    
416    Example 4:
417    A sample response from a child table resource (e.g. http://example.net/srv/tables/TAP\_SCHEMA.columns).
418    
419    \begin{lstlisting}[language=XML]
420    <?xml version="1.0" encoding="UTF-8"?>
421    <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
422        xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1"
423        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">
424      <name>TAP_SCHEMA.columns</name>
425      <column>
426        <name>table_name</name>
427        <description>the table this column belongs to</description>
428        <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
429      </column>
430      <column>
431        <name>column_name</name>
432        <description>the column name</description>
433        <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
434      </column>
435      <column>
436        <name>utype</name>
437        <description>lists the utypes of columns in the tableset</description>
438        <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>
439      </column>
440      <column>
441        <name>ucd</name>
442        <description>lists the UCDs of columns in the tableset</description>
443        <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
444      </column>
445      <column>
446        <name>unit</name>
447        <description>lists the unit used for column values in the tableset</description>
448        <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
449      </column>
450      <column>
451        <name>description</name>
452        <description>describes the columns in the tableset</description>
453        <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>
454      </column>
455      <column>
456        <name>datatype</name>
457        <description>lists the ADQL datatype of columns in the tableset</description>
458        <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
459      </column>
460      <column>
461        <name>size</name>
462        <description>lists the size of variable-length columns in the tableset</description>
463        <dataType xsi:type="vod:TAPType">INTEGER</dataType>
464      </column>
465      <column>
466        <name>principal</name>
467        <description>a principal column; 1 means 1, 0 means 0</description>
468        <dataType xsi:type="vod:TAPType">INTEGER</dataType>
469      </column>
470      <column>
471        <name>indexed</name>
472        <description>an indexed column; 1 means 1, 0 means 0</description>
473        <dataType xsi:type="vod:TAPType">INTEGER</dataType>
474      </column>
475      <column>
476        <name>std</name>
477        <description>a standard column; 1 means 1, 0 means 0</description>
478        <dataType xsi:type="vod:TAPType">INTEGER</dataType>
479      </column>
480      <foreignKey>
481        <targetTable>TAP_SCHEMA.tables</targetTable>
482        <fkColumn>
483          <fromColumn>table_name</fromColumn>
484          <targetColumn>table_name</targetColumn>
485        </fkColumn>
486      </foreignKey>
487    </vosi:table>
488    \end{lstlisting}
489    
490    Example 5:
491    A sample response from an availability resource.
492    
493    \begin{lstlisting}[language=XML]
494    <vosi:availability xmlns:vosi="http://www.ivoa.net/xml/VOSIAvailability/v1.0">
495      <vosi:available>true</vosi:available>
496      <vosi:note>service is accepting queries</vosi:note>
497    </vosi:availability>
498    \end{lstlisting}
499    
500  \appendix  \appendix
501    
502  \section{The Complete VOSICapabilities Schema}  \section{The Complete VOSICapabilities Schema}
# Line 508  Line 651 
651    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
652    elementFormDefault="qualified"    elementFormDefault="qualified"
653    attributeFormDefault="unqualified"    attributeFormDefault="unqualified"
654    version="1.0">    version="1.1">
655    
656    <xsd:annotation>    <xsd:annotation>
657      < xsd:documentation>      < xsd:documentation>
# Line 524  Line 667 
667      schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" />      schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" />
668    
669    <!--    <!--
670      -  the root element for a VOSI table metadata (section 3.4)      -  the root element for a VOSI tableset metadata
671      -->      -->
672    <xsd:element name="tableset" type="vs:TableSet" >    <xsd:element name="tableset" type="vs:TableSet" >
673      <xsd:annotation>      <xsd:annotation>
# Line 534  Line 677 
677        </xsd:documentation>        </xsd:documentation>
678      </xsd:annotation>      </xsd:annotation>
679    </xsd:element>    </xsd:element>
680      
681      <!--
682        -  single table root element for a VOSI table metadata
683        -->
684      <xsd:element name="table" type="vs:Table" >
685         <xsd:annotation>
686           <xsd:documentation>
687             A description of a single table supported by the
688             service associated with a VOSI-enabled resource.
689           </xsd:documentation>
690         </xsd:annotation>
691      </xsd:element>
692    
693  </xsd:schema>  </xsd:schema>
694  \end{lstlisting}  \end{lstlisting}
# Line 556  Line 711 
711    
712  \section{Changes from Previous Versions}  \section{Changes from Previous Versions}
713    
714    \subsection{Changes in WD-VOSI-1.1-20160129}
715    
716    Added alternate root element (table) to VOSITables schema. Extended VOSITables REST binding to include detail=min param and child table resource for scalability. Defined \#tables-1.1 standardID.
717    
718  \subsection{Changes since PR-20101206}  \subsection{Changes since PR-20101206}
719    
720  Added Appendix B, use case discussion  Added Appendix B, use case discussion

Legend:
Removed from v.3232  
changed lines
  Added in v.3233

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