/[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 3305 by major.brian, Thu Apr 14 18:47:12 2016 UTC revision 3306 by major.brian, Thu Apr 14 23:46:17 2016 UTC
# Line 14  Line 14 
14  \editor{Matthew Graham}  \editor{Matthew Graham}
15  \editor{Guy Rixon}  \editor{Guy Rixon}
16  \editor{Patrick Dowler}  \editor{Patrick Dowler}
17    \editor{Brian Major}
18    
19  \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}
20    
21  \begin{document}  \begin{document}
22  \begin{abstract}  \begin{abstract}
23  This document describes the minimum interface that a (SOAP- or REST-based) web service requires to participate in the IVOA. Note that this is not required of standard VO services developed prior to this specification, although uptake is strongly encouraged on any subsequent revision. All new standard VO services, however, must feature a VOSI-compliant interface.  This document describes the minimum interface that a web service requires to participate in the IVOA. Note that this is not required of standard VO services developed prior to this specification, although uptake is strongly encouraged on any subsequent revision. All new standard VO services, however, must feature a VOSI-compliant interface.
24  \end{abstract}  \end{abstract}
25    
26    
# Line 47  Line 48 
48    
49    
50  \section{Introduction}  \section{Introduction}
51    \label{sec:introduction}
52    
53  The web services that comprise much of the Virtual Observatory (VO) come in two forms: SOAP-based (Simple Object Access Protocol, [1]) ones such as footprint and spectrum services [2], SkyNodes and Open SkyQuery [3], registry interfaces [4] and CDS access [5]; and RESTful (REpresentational State Transfer, [6]) ones such as TAP [7] and other second generation data access (DAL) services, and VOSpace 2.0 [8]. This document describes a set of common basic functions that all these services should provide in the form of a standard support interface in order to support the effective management of the VO. It is agreed that VO service standards previous to VOSI may not be forced to retrospectively implement VOSI (although that should be encouraged). Nonetheless, all new VO service standards (or updated existing ones) must enforce the VOSI implementation.  This document describes a set of common basic functions that VO web services provide in the form of a standard support interface in order to allow for the effective management of the VO.  There are three basic support functions that this document describes:  The reporting of capability metadata, the reporting of service availability metadata, and the reporting of table metadata (if applicable).
54    
55    VO service standards previous to VOSI may not be forced to retrospectively implement VOSI (although that should be encouraged). Nonetheless, all new VO service standards (or updated existing ones) must enforce the VOSI implementation.
56    
 The IVOA Web Services Basic Profile [9] mandates that a compliant SOAP-based web service should have the interface defined in this specification, as expressed using the standard WSDL (Web Services Description Language, [10]) format. For RESTful services, the requirement for the support interface is stated in the specification for each kind of service. A contract for a RESTful service may specify extra constraints (e.g., on the form of the URIs) for the support interface. Such a contract might be expressed using the WADL (Web Application Description Language, [15]) format.  
57    
58  \subsection{Role within the VO Architecture}  \subsection{Role within the VO Architecture}
59    
60  The IVOA Architecture [11] provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Fig. 1.  The IVOA Architecture \citep{note:VOARCH} provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Figure ~\ref{fig:archdiag}.
61    
62  \begin{figure}  \begin{figure}
63  \centering  \centering
# Line 71  Line 74 
74  \label{fig:archdiag}  \label{fig:archdiag}
75  \end{figure}  \end{figure}
76    
77  In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services--that is, resources--of interest (represented in the Resource Layer). A registry plays a role in discovery by harvesting metadata that describe archives and services and making them searchable from a central service. The VOSI interface provides a means for a service to provide some of this metadata itself; this allows a registry to pull the metadata from the service rather than relying on a human to provide it (e.g. by typing the data into a registration form manually). This mechanism can make it easier to collect highly detailed metadata (e.g. descriptions of columns in a catalog) that might not be practically provided otherwise. As some of this metadata describes the service interface and how it behaves, other applications can use this information for controlling how they use the service. Even when the service is "discovered" through some means other than a registry, an application can still understand how to use the service by querying for this information directly. (See Appendix B for a more detailed description of this use case.)  In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services--that is, resources--of interest (represented in the Resource Layer). A registry plays a role in discovery by harvesting metadata that describe archives and services and making them searchable from a central service. The VOSI interface provides a means for a service to provide some of this metadata itself; this allows a registry to pull the metadata from the service rather than relying on a human to provide it (e.g. by typing the data into a registration form manually). This mechanism can make it easier to collect highly detailed metadata (e.g. descriptions of columns in a catalog) that might not be practically provided otherwise. As some of this metadata describes the service interface and how it behaves, other applications can use this information for controlling how they use the service. Even when the service is "discovered" through some means other than a registry, an application can still understand how to use the service by querying for this information directly. (See Appendix \ref{appendix:harvesting} for a more detailed description of this use case.)
78    
79  Once a user discovers data and services of interest, she will want to engage them in an analysis process. Success requires that the selected services are actually up and running properly as a down service can cause automated processing to fail completely. Registry and workflow services can assist with this by tracking the availability of services and alerting users about downtime. We envision that VOSI will allow VO projects to better track the overall health of the VO ecosystem.  Once a user discovers data and services of interest, she will want to engage them in an analysis process. Success requires that the selected services are actually up and running properly as a down service can cause automated processing to fail completely. Registry and workflow services can assist with this by tracking the availability of services and alerting users about downtime. We envision that VOSI will allow VO projects to better track the overall health of the VO ecosystem.
80    
81  \section{Interface bindings}  \section{Interface bindings}
82    \label{sec:bindings}
83    
84  The standard interface returns metadata without changing the state of the service with which it is associated. This could, in principle, be implemented in any of three ways:  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.
   
     As extra SOAP operations on an existing SOAP endpoint of the service with which it is associated. This would be a 'SOAP binding' of VOSI.  
     As SOAP operations on a separate SOAP endpoint. This would be an alternate form of the SOAP binding.  
     As web resources with distinct URLs, without using the SOAP protocol. This is the 'REST binding' for the standard interface.  
   
 This standard requires the REST binding of VOSI even when applied to services that otherwise use SOAP. No details of the SOAP binding are given in this version of the standard.  
85    
86  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.
87    
88  The endpoints and interface types for the support interface shall be defined in the service's registration using one Capability element for each interface. The values of the standardID attribute for these Capabilitys are given in section 4.  The endpoints and interface types for the support interface shall be defined in the service's registration using one Capability element for each interface. The values of the standardID attribute for these Capabilities are given in section 4.
89    
90  When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the service's entry in the VO registry and, in general, should not try and infer the URLs from any other URLs for that service. However, standards for specific services may put extra constraints on the form of the URLs.  When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the service's entry in the VO registry and, in general, should not try and infer the URLs from any other URLs for that service. However, standards for specific services may put extra constraints on the form of the URLs.
91    
92  \section{Metadata specification}  \section{Metadata specification}
93    \label{sec:metadata}
94    
95   There are various classes of metadata that might be returned by a service through its standard interface:   There are various classes of metadata that might be returned by a service through its standard interface:
96    
# Line 105  Line 104 
104  This section defines how each of these classes is represented. The following typographic convention is used to represent a XML element defined within a particular namespace:  This section defines how each of these classes is represented. The following typographic convention is used to represent a XML element defined within a particular namespace:
105    
106  \begin{verbatim}  \begin{verbatim}
107  {http://some.name.space}elementName  http://some.name.space\#elementName
108  \end{verbatim}  \end{verbatim}
109    
110  For example, {http://www.ivoa.net/xml/VOResource/v1.0}resource indicates a XML element named resource that is described in the XML schema associated with the 'http://www.ivoa.net/xml/VOResource/v1.0' namespace - in this case, this would be VOResource.xsd [12].  For example, http://www.ivoa.net/xml/VOResource/v1.0\#resource indicates a XML element named resource that is described in the XML schema associated with the 'http://www.ivoa.net/xml/VOResource/v1.0' namespace - in this case, this would be VOResource.xsd \citep{std:VOR}.
111    
112  \subsection{Capability metadata}  \subsection{Capability metadata}
113    
   
114  Note:  Note:
115      'Capability' is unfortunately an overloaded term in the VO referring to both a functional aspect of a service and also particular pieces of metadata defined by various XML schema. When referring to an XML element called 'capability', it shall be be put in italics. Its parent namespace may also be included (using the syntax described above) if it is ambiguous which XML schema is being referred to.      'Capability' is unfortunately an overloaded term in the VO referring to both a functional aspect of a service and also particular pieces of metadata defined by various XML schema. When referring to an XML element called 'capability', it shall be be put in italics. Its parent namespace may also be included (using the syntax described above) if it is ambiguous which XML schema is being referred to.
116            
# Line 126  Line 124 
124    
125  For example, one Capability might describe a cone search function and another the TAP implementation but these two might well apply to the same service.  For example, one Capability might describe a cone search function and another the TAP implementation but these two might well apply to the same service.
126    
127  An entry for a service in the resource registry - i.e., its VOResource - contains the Dublin Core resource metadata (identifier, curation information, content description, etc.) followed by the service's capability descriptions (expressed as a series of {http://www.ivoa.net/xml/VOResource/v1.0}Capability elements). Effectively, the resource metadata describes the service to human users and the capability list describes it to software. Therefore, the latter list has two uses:  An entry for a service in the resource registry - i.e., its VOResource - contains the Dublin Core resource metadata (identifier, curation information, content description, etc.) followed by the service's capability descriptions (expressed as a series of http://www.ivoa.net/xml/VOResource/v1.0\#Capability elements). Effectively, the resource metadata describes the service to human users and the capability list describes it to software. Therefore, the latter list has two uses:
128    
129  \begin{itemize}  \begin{itemize}
130  \item it may be read by a client application to find out how to invoke the service. This presumes that the service has been already been selected and the VOSI endpoint located.  \item it may be read by a client application to find out how to invoke the service. This presumes that the service has been already been selected and the VOSI endpoint located.
131  \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.
132  \end{itemize}  \end{itemize}
133    
134  The service metadata shall be represented as an XML document with the root element {http://www.ivoa.net/xml/VOSICapabilities/v1.0}capabilities. (See Appendix A.1 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 {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 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 http://www.ivoa.net/xml/VOResource/v1.0\#Capability, a capability element may be represented by a legal sub-type of
135  {http://www.ivoa.net/xml/VOResource/v1.0}Capability, in which case, the capability element must use an xsi:type attribute to identify the sub-type (see section 2.2.1 of [12]).  http://www.ivoa.net/xml/VOResource/v1.0\#Capability, in which case, the capability element must use an xsi:type attribute to identify the sub-type (see section 2.2.1 of VOResource \citep{std:VOR}).
136    
137    
138  Note:  Note:
139      The value of the capability element's 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 Capability for that protocol. The extension metadata is enabled by adding a 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 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 Capability for that protocol. The extension metadata is enabled by adding a 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).
140            
141   The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section 4.   The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section \ref{sec:endpoints}.
142    
143  In the REST binding, the service metadata shall be a single web resource with a registered URL. The date and time at which the metadata last changed shall be obtained from the Last-Modified HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.  In the REST binding, the service metadata shall be a single web resource with a registered URL. The date and time at which the metadata last changed shall be obtained from the Last-Modified HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.
144    
# Line 151  Line 149 
149  There may be other metadata associated with a service than the capability metadata described above.  There may be other metadata associated with a service than the capability metadata described above.
150    
151  \begin{itemize}  \begin{itemize}
152  \item Every service has the Dublin Core resource metadata [13].  \item Every service has the Dublin Core resource metadata \citep{std:DUBLINCORE}.
153  \item Some services are associated with registered applications.  \item Some services are associated with registered applications.
154  \item Some services are associated with registered data collections.  \item Some services are associated with registered data collections.
155  \end{itemize}  \end{itemize}
# Line 160  Line 158 
158    
159  \subsection{Availability metadata}  \subsection{Availability metadata}
160    
161  This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests. The availability shall be represented as an XML document in which the root element is {http://www.ivoa.net/xml/Availability/v1.0}availability. This element shall contain child elements providing the following information.  This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests. The availability shall be represented as an XML document in which the root element is http://www.ivoa.net/xml/Availability/v1.0\#availability. This element shall contain child elements providing the following information.
162    
163  \begin{itemize}  \begin{itemize}
164  \item available - whether the service is currently accepting requests  \item available - whether the service is currently accepting requests
165  \item upSince - duration for which the service has been continuously available  \item upSince - duration for which the service has been continuously available
166  \item downAt - the instant at which the service is next scheduled to be unavailable  \item downAt - the instant at which the service is next scheduled to be unavailable
167  \item backAt - the instant at which the service is scheduled to become available again after down time;  \item backAt - the instant at which the service is scheduled to become available again after down time;
168  \item note - textual note, e.g. explaining the reason for unavailaility.  \item note - textual note, e.g. explaining the reason for unavailability.
169  \end{itemize}  \end{itemize}
170    
171  The elements upSince, downAt, backAt and note are optional. The available element is mandatory. There may be more than one note element.  The elements upSince, downAt, backAt and note are optional. The available element is mandatory. There may be more than one note element.
172    
173  The XML document shall conform to the schema given in appendix A.2 of this specification.  The XML document shall conform to the schema given in appendix \ref{appendix:availability} of this specification.
174    
175  When reporting availability, the service should do a good check on its underlying parts to see if it is still operational and not just make a simple return from a web server, e.g., if it relies on a database it should check that the database is still up. If any of these checks fail, the service should set available to false in the availability output.  When reporting availability, the service should do a good check on its underlying parts to see if it is still operational and not just make a simple return from a web server, e.g., if it relies on a database it should check that the database is still up. If any of these checks fail, the service should set available to false in the availability output.
176    
# Line 186  Line 184 
184    
185  \subsection{Table metadata}  \subsection{Table metadata}
186    
187   Some services deal with tabular data. These data may be the target of ADQL queries, as in TAP [7], or they may be the output of other operations, as in SIAP queries. In each case, it is useful if the service describes the details of the tables concerned. It is more useful if this description can be captured in the resource registry.   Some services deal with tabular data. These data may be the target of ADQL queries, as in TAP \citep{std:TAP}, or they may be the output of other operations, as in SIAP queries. In each case, it is useful if the service describes the details of the tables concerned. It is more useful if this description can be captured in the resource registry.
188    
189  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 \citep{std:VODS11} defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
190    
191  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
192  {http://www.ivoa.net/xml/VODataService/v1.1}TableSet. The table metadata for a single table (see below) shall be represented as an  http://www.ivoa.net/xml/VODataService/v1.1\#TableSet. The table metadata for a single table (see below) shall be represented as an
193  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.  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.
194    
195  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.  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.
196    
# Line 200  Line 198 
198  GET http://example.net/srv/tables?detail=min  GET http://example.net/srv/tables?detail=min
199  \end{verbatim}  \end{verbatim}
200    
201  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).  If the caller requests detail=min, the response (TableSet) document must not include elements of type Column or ForeignKey; the tables described have names and optional descriptions but no column or foreign key details).
202    
203  The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be  The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be
204  named with the fully-qualified table name and without any intervening schema name. For example:  named with the fully-qualified table name and without any intervening schema name. For example:
# Line 216  Line 214 
214    
215    
216  \section{Registration of VOSI endpoints}  \section{Registration of VOSI endpoints}
217    \label{sec:endpoints}
218    
219  The endpoints for the service and availability metadata shall be included in the registration of each service that provides them.  The endpoints for the service and availability metadata shall be included in the registration of each service that provides them.
220    
# Line 228  Line 227 
227  tables (1.1) & ivo://ivoa.net/std/VOSI\#tables-1.1 \\  tables (1.1) & ivo://ivoa.net/std/VOSI\#tables-1.1 \\
228  \end{tabular}  \end{tabular}
229    
230  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 \citep{std:VOR}). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI\#availability.
231    
232  A capabilities endpoint should be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#capabilities.  A capabilities endpoint should be represented by an element named capability, of type http://www.ivoa.net/xml/VOResource/v1.0\#Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#capabilities.
233    
234  A tables endpoint should be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#tables.  A tables endpoint should be represented by an element named capability, of type http://www.ivoa.net/xml/VOResource/v1.0\#Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#tables.
235    
236  With all three VOSI functions, the Capability element that describes the function must contain an interface element of a type semantically appropriate for the binding of the function to the service; the accessURL element within the interface element indicates the endpoint for the VOSI function. For the REST binding, this accessURL element must set the use attribute to "full". Furthermore, for the REST binding, this document recommends using the {http://www.ivoa.net/xml/VODataService/v1.1}ParamHTTP interface type to encode VOSI endpoints (see example given in section 2.1).  With all three VOSI functions, the Capability element that describes the function must contain an interface element of a type semantically appropriate for the binding of the function to the service; the accessURL element within the interface element indicates the endpoint for the VOSI function. For the REST binding, this accessURL element must set the use attribute to "full". Furthermore, for the REST binding, this document recommends using the http://www.ivoa.net/xml/VODataService/v1.1\#ParamHTTP interface type to encode VOSI endpoints (see example given in section 2.1).
237    
238  \section{Example VOSI responses}  \section{Example VOSI responses}
239    \label{sec:examples}
240    
241  Example 1:  Example 1:
242  A sample response from a capabilities resource describing an SIA service.  A sample response from a capabilities resource describing an SIA service.
# Line 500  Line 500 
500  \appendix  \appendix
501    
502  \section{The Complete VOSICapabilities Schema}  \section{The Complete VOSICapabilities Schema}
503    \label{appendix:capabilities}
504  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
505  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
506      xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"      xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
# Line 563  Line 564 
564  \end{lstlisting}  \end{lstlisting}
565    
566  \section{The Complete VOSIAvailability Schema}  \section{The Complete VOSIAvailability Schema}
567    \label{appendix:availability}
568  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
569  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
570      xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"      xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
# Line 642  Line 644 
644  \end{lstlisting}  \end{lstlisting}
645    
646  \section{The Complete VOSITables Schema}  \section{The Complete VOSITables Schema}
647    \label{appendix:tables}
648  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
649  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSITables/v1.0"  <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSITables/v1.0"
650    xmlns:tns="http://www.ivoa.net/xml/VOSITables/v1.0"    xmlns:tns="http://www.ivoa.net/xml/VOSITables/v1.0"
# Line 694  Line 697 
697  \end{lstlisting}  \end{lstlisting}
698    
699  \section{Use Case for Capability Harvesting (non-normative)}  \section{Use Case for Capability Harvesting (non-normative)}
700    \label{appendix:harvesting}
701    
702   In the section 1.2, we summarized the role that the metadata retrieval functions (sections 3.1 and 3.4) play in the discovery of services. In particular, it mentions that a registry can harvest this information from a service's VOSI interface to save the provider from entering the information explicitly into a web form. In this appendix, we describe this use case in more detail, including both the publishing of the metadata and its typical use by service clients.   In the section \ref{sec:introduction}, we summarized the role that the metadata retrieval functions play in the discovery of services. In particular, it mentions that a registry can harvest this information from a service's VOSI interface to save the provider from entering the information explicitly into a web form. In this appendix, we describe this use case in more detail, including both the publishing of the metadata and its typical use by service clients.
703    
704  Some publishing registries [4] provide a publically accessible publishing tool: it allows any data service provider to "register" his service by providing the necessary metadata adequate to describe it. Such a tool typically provides a form that the provider fills out to enter all the metadata; the form processor uses those inputs to format a VOResource record that describes the service based on that metadata. Prior to the registry's support for the VOSI metadata functions, entering all of the metadata (particularly, fully describing all of the table columns) would often be laborious; consequently, providers are effectively discouraged from providing the mostly optional information.  Some publishing registries \citep{std:RI1} provide a publicly accessible publishing tool: it allows any data service provider to "register" his service by providing the necessary metadata adequate to describe it. Such a tool typically provides a form that the provider fills out to enter all the metadata; the form processor uses those inputs to format a VOResource record that describes the service based on that metadata. Prior to the registry's support for the VOSI metadata functions, entering all of the metadata (particularly, fully describing all of the table columns) would often be laborious; consequently, providers are effectively discouraged from providing the mostly optional information.
705    
706  With support for the VOSI metadata functions, the registry's publishing tool can now offer an alternative mechanism for providing much of the information. After generally describing the service via core metadata (e.g., its title, identifier, general description, contact information, etc.), the registry can offer the option of entering the VOSI URLs that provide the capability and table metadata. In the case of TAP, where these VOSI functions are mandated as part of the TAP interface, it would only be necessary for the user to enter the TAP service's base URL (in VOResource parlance, the "access URL"). In either case, the tool would access the VOSI URLs, pull over the metadata, integrate it into the core metadata, and show the provider the combined results before publishing it to the registry. The tool might also ask the provider if this data is expected to change over time and thus whether the VOSI URLs should be polled regularly to update the service description held by the registry. Alternatively, the tool may may allow the provider to quickly update the service description via a single button click that causes the tool to re-access the VOSI endpoints and refresh service description held by the registry.  With support for the VOSI metadata functions, the registry's publishing tool can now offer an alternative mechanism for providing much of the information. After generally describing the service via core metadata (e.g., its title, identifier, general description, contact information, etc.), the registry can offer the option of entering the VOSI URLs that provide the capability and table metadata. In the case of TAP, where these VOSI functions are mandated as part of the TAP interface, it would only be necessary for the user to enter the TAP service's base URL (in VOResource parlance, the "access URL"). In either case, the tool would access the VOSI URLs, pull over the metadata, integrate it into the core metadata, and show the provider the combined results before publishing it to the registry. The tool might also ask the provider if this data is expected to change over time and thus whether the VOSI URLs should be polled regularly to update the service description held by the registry. Alternatively, the tool may may allow the provider to quickly update the service description via a single button click that causes the tool to re-access the VOSI endpoints and refresh service description held by the registry.
707    
# Line 710  Line 714 
714  We have implied in the above discussion that the capability and table metadata are the same whether they are retrieved from the registry or from the service. It is possible, however, that the service could change--new capabilities or table columns could be added--and the registry could (at least temporarily, depending on the registry) get out of sync with the service. This circumstance may occur rarely; nevertheless, if being up-to-date is important, then the client may need to be more sophisticated in its retrieval. That is, it could retrieve the resource description from the registry; then if the description indicates support for VOSI, the VOSI URLs would be accessed to get the latest, up-to-date information.  We have implied in the above discussion that the capability and table metadata are the same whether they are retrieved from the registry or from the service. It is possible, however, that the service could change--new capabilities or table columns could be added--and the registry could (at least temporarily, depending on the registry) get out of sync with the service. This circumstance may occur rarely; nevertheless, if being up-to-date is important, then the client may need to be more sophisticated in its retrieval. That is, it could retrieve the resource description from the registry; then if the description indicates support for VOSI, the VOSI URLs would be accessed to get the latest, up-to-date information.
715    
716  \section{Changes from Previous Versions}  \section{Changes from Previous Versions}
717    \label{appendix:changes}
718    
719  \subsection{Changes since REC-VOSI-20110531}  \subsection{Changes since REC-VOSI-20110531}
720    
721  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.  Added alternate root element (table) to VOSITables schema.
722    
723    Extended VOSITables REST binding to include detail=min param and child table resource for scalability.
724    
725    Defined \#tables-1.1 standardID.
726    
727    Removed references to SOAP bindings.
728    
729  \subsection{Changes since PR-20101206}  \subsection{Changes since PR-20101206}
730    

Legend:
Removed from v.3305  
changed lines
  Added in v.3306

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