ࡱ > @ [ bjbj ,J TN % $ 8 ʙ ~ 4 ½ " } \ $ R C @ 6 - J \ h 6 c R 6 6 6 p L 6 J 6 6 y - l , T p 4 ~ > , 6 C $ g 6 6 $ D* . d `6 j . International
Virtual
Observatory
Alliance
IVOA Registry Interfaces
Version 0.8.5
IVOA Working Draft 2004 June 16
This version:
0.8.11 http://www.ivoa.net/internal/IVOA/RegistryInterface/IVOARegistryIntervace-0.8.11.pdf
Latest version:
MACROBUTTON AcceptChangesSelected LatestVersion
Previous versions:
MACROBUTTON AcceptChangesSelected PreviousVersion(s)-YYYYMMDD
Authors:
HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/KevinBenson" Kevin Benson, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/ElizabethAuden" Elizabeth Auden, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham" Matthew Graham, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/GretchenGreene" Gretchen Greene, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/MartinHill" Martin Hill, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/TonyLinde" Tony Linde, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris" Dave Morris, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/WilOMullane" Wil OMullane, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante" Ray Plante, HYPERLINK "http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon" Guy Rixon, Kona Andrews
Abstract
Registries provide a mechanism with which VO applications can discover and select resourcese.g. data and servicesthat are relevant for a particular scientific problem. This specification defines the interfaces that support interactions between applications and registries as well as between the registries themselves. It is based on a general, distributed model composed of so-called searchable and publishing registries. The specification has two main components: an interface for searching and an interface for harvesting. All interfaces are defined by a standard Web Service Description Language (WSDL) document; however, harvesting is also supported through the existing Open Archives Initiative Protocol for Metadata Harvesting, defined as an HTTP GET REST interface. Finally, this specification details the metadata used to describe registries themselves as resources using an extension of the VOResource metadata schema.
Status of This Document
This is a Working Draft. The HYPERLINK "http://www.ivoa.net/Documents/"first release of this document was DATE \@ "yyyy MMMM dd" \* MERGEFORMAT 2006 June 282006 June 242005 July 252005 March 16.
This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress.
A list of HYPERLINK "http://www.ivoa.net/Documents/" current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
Acknowledgements
This document has been developed with support from the HYPERLINK "http://www.nsf.gov" National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the HYPERLINK "http://www.pparc.ac.uk" UK Particle Physics and Astronomy Research Council (PPARC), and from the HYPERLINK "http://fp6.cordis.lu/fp6/home.cfm" European Commission's Sixth Framework Program via the HYPERLINK "http://www.astro-opticon.org/" Optical Infrared Coordination Network (OPTICON).
Conformance-related definitions
The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 [RFC 2119].
The Virtual Observatory (VO) is a general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The HYPERLINK "http://www.ivoa.net/" International Virtual Observatory Alliance (IVOA) is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications.
A Web Service (when capitalized as it is here) refers to a service that is in actuality described by a HYPERLINK "http://www.w3.org/TR/wsdl/" Web Service Description Language (WSDL) HYPERLINK \l "wsdlv1_1" [WSDLv1.1] document.
Editors Note:
Boxed comments labeled Note, such as this one, This document contains two types of boxed comments like this one. Those marked Editors Note represents comments intended for the standard editors and for reviewers; these comments would be removed when the issues they discuss are addressed. Those marked simply as Note are intended for those who will implement the standard, and are intended to provide tips and further explanation of how the standard is expected to be used or implemented. These notes are expected to remain embedded in the final version of the documentTheir content are non-conformant t h a t i s , t h e y a r e n o t t e c h n i c a l l y p a r t o f t h e s t a n d a r d s p e c i f i c a t i o n .
C o n t e n t s
T O C \ o " 3 - 3 " \ h \ z \ t " H e a d i n g 1 , 1 , H e a d i n g 2 , 2 , H e a d i n g 1 1 , 2 , P r e f a c e H e a d i n g , 1 " H Y P E R L I N K \ l " _ T o c 1 3 8 4 7 7 1 9 6 " A b s t r a c t P A G E R E F _ T o c 1 3 8 4 7 7 1 9 6 \ h 1
H Y P E R L I N K \ l " _ Toc138477197" Status of This Document PAGEREF _Toc138477197 \h 2
HYPERLINK \l "_Toc138477198" Acknowledgements PAGEREF _Toc138477198 \h 2
HYPERLINK \l "_Toc138477199" Conformance-related definitions PAGEREF _Toc138477199 \h 2
HYPERLINK \l "_Toc138477200" Contents PAGEREF _Toc138477200 \h 3
HYPERLINK \l "_Toc138477201" 1 Introduction PAGEREF _Toc138477201 \h 4
HYPERLINK \l "_Toc138477202" 1.1 Registry Architecture and Definitions PAGEREF _Toc138477202 \h 4
HYPERLINK \l "_Toc138477203" 1.2 Specification Summary PAGEREF _Toc138477203 \h 6
HYPERLINK \l "_Toc138477204" 2 Searching PAGEREF _Toc138477204 \h 7
HYPERLINK \l "_Toc138477205" 2.1 Required Search Operations PAGEREF _Toc138477205 \h 8
HYPERLINK \l "_Toc138477206" 2.1.1 Output Format PAGEREF _Toc138477206 \h 8
HYPERLINK \l "_Toc138477232" 2.1.2 Constraint-based Search Query PAGEREF _Toc138477232 \h 12
HYPERLINK \l "_Toc138477237" 2.1.3 Keyword Search Query PAGEREF _Toc138477237 \h 15
HYPERLINK \l "_Toc138477244" 2.2 Resolve Operations PAGEREF _Toc138477244 \h 18
HYPERLINK \l "_Toc138477245" 2.2.1 Output Format PAGEREF _Toc138477245 \h 18
HYPERLINK \l "_Toc138477246" 2.2.2 Identifier Resolution PAGEREF _Toc138477246 \h 18
HYPERLINK \l "_Toc138477247" 2.2.3 Identity Query PAGEREF _Toc138477247 \h 19
HYPERLINK \l "_Toc138477249" 2.3 XQuery Search PAGEREF _Toc138477249 \h 19
HYPERLINK \l "_Toc138477250" 3 Harvesting PAGEREF _Toc138477250 \h 20
HYPERLINK \l "_Toc138477251" 3.1 Harvesting Interface PAGEREF _Toc138477251 \h 21
HYPERLINK \l "_Toc138477252" 3.1.1 A Summary of the OAI Web Service Interface PAGEREF _Toc138477252 \h 21
HYPERLINK \l "_Toc138477253" 3.1.2 Metadata Formats for Resource Descriptions PAGEREF _Toc138477253 \h 23
HYPERLINK \l "_Toc138477254" 3.1.3 Identifiers in OAI Messages PAGEREF _Toc138477254 \h 24
HYPERLINK \l "_Toc138477255" 3.1.4 Required Records PAGEREF _Toc138477255 \h 25
HYPERLINK \l "_Toc138477256" 3.1.5 The Identify Operation PAGEREF _Toc138477256 \h 25
HYPERLINK \l "_Toc138477257" 3.1.6 IVOA Supported Sets PAGEREF _Toc138477257 \h 26
HYPERLINK \l "_Toc138477258" 3.2 Harvesters PAGEREF _Toc138477258 \h 26
HYPERLINK \l "_Toc138477259" 4 Registering Registries PAGEREF _Toc138477259 \h 27
HYPERLINK \l "_Toc138477260" 4.1 Namespace and Schema Location PAGEREF _Toc138477260 \h 27
HYPERLINK \l "_Toc138477261" 4.2 The Registry Resource Extension PAGEREF _Toc138477261 \h 27
HYPERLINK \l "_Toc138477262" 4.3 The Authority Resource Extension PAGEREF _Toc138477262 \h 28
HYPERLINK \l "_Toc138477263" Appendix A.1 Web Services Definition Language Document for Search Interface PAGEREF _Toc138477263 \h 29
HYPERLINK \l "_Toc138477264" Appendix A.2 PAGEREF _Toc138477264 \h 29
HYPERLINK \l "_Toc138477265" Web Services Definition Language Document for the Harvesting Interface PAGEREF _Toc138477265 \h 29
HYPERLINK \l "_Toc138477266" Appendix A.3 VORegistry: the VOResource Extension Schema for Registering Registries PAGEREF _Toc138477266 \h 30
Abstract
Status of This Document
Acknowledgements
Conformance-related definitions
Contents
1 Introduction
1.1 Registry Architecture and Definitions
1.2 Specification Summary
2 Searching
2.1 Handling large volume of data
2.1.1 Paginate Scheme
2.1.2 Identifiers scheme
2.2 Constraint-based Search Query
2.2.1 Restrictions on the use of XPath in ADQL
2.3 Keyword Search Query
2.4 Single Resource Search Query
2.5 Xquery Search
2.6 Using Registry Resource for Specific Searching
3 Harvesting
3.1 Harvesting Interface
3.1.1 A Summary of the OAI Web Service Interface
3.1.2 Metadata Formats for Resource Descriptions
3.1.3 Identifiers in OAI Messages
3.1.4 Required Records
3.1.5 The Identify Operation
3.1.6 IVOA Supported Sets
3.2 Harvesters
4 Registering Registries Harvesting
Appendix A.1 Sample extension of vg:Registry
Appendix A.2 Web Services Definition Language Document for Search Interface
Appendix A.3
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface
Abstract 1
Status of This Document 2
Acknowledgements 2
Conformance-related definitions 2
Contents 3
1 Introduction 3
1.1 Registry Architecture and Definitions 4
1.2 Specification Summary 6
2 Searching 7
2.1 Handling large volume of data 8
2.1.1 Paginate Scheme 8
2.1.2 Identifiers scheme 9
2.2 Constraint-based Search Query 9
2.2.1 Restrictions on the use of XPath in ADQL 10
2.3 Keyword Search Query 11
2.4 Single Resource Search Query 12
2.5 Xquery Search 13
2.6 Using Registry Resource for Specific Searching 13
3 Harvesting 14
3.1 Harvesting Interface 14
3.1.1 A Summary of the OAI Web Service Interface 14
3.1.2 Metadata Formats for Resource Descriptions 16
3.1.3 Identifiers in OAI Messages 17
3.1.4 Required Records 18
3.1.5 The Identify Operation 19
3.1.6 IVOA Supported Sets 19
3.2 Harvesters 20
4 Registering Registries Harvesting 20
Appendix A.1 Web Services Definition Language Document for the Search Interface 21
Appendix A.2 Web Services Definition Language Document for OAI-PHM 21
Appendix A.3 Recommended Descriptions for IVOA Reserved Sets 21
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface 21
Abstract 1
Status of This Document 2
Acknowledgements 2
Conformance-related definitions 2
Contents 3
1 Introduction 3
1.1 Registry Architecture and Definitions 4
1.2 Specification Summary 6
2 Searching 7
2.1 Handling large volume of data 8
2.1.1 Paginate Scheme 8
2.1.2 Identifiers scheme 9
2.2 Constraint-based Search Query 9
2.2.1 Restrictions on the use of XPath in ADQL 10
2.3 Keyword Search Query 11
2.4 Single Resource Search Query 12
2.5 Xquery Search 13
2.6 Interrogate Registry Resource for Searching 13
3 Harvesting 14
3.1 Harvesting Interface 14
3.1.1 A Summary of the OAI Web Service Interface 14
3.1.2 Metadata Formats for Resource Descriptions 16
3.1.3 Identifiers in OAI Messages 17
3.1.4 Required Records 18
3.1.5 The Identify Operation 19
3.1.6 IVOA Supported Sets 19
3.2 Harvesters 20
4 Registering Registries Harvesting 20
Appendix A.1 Web Services Definition Language Document for the Search Interface 21
Appendix A.2 Web Services Definition Language Document for OAI-PHM 21
Appendix A.3 Recommended Descriptions for IVOA Reserved Sets 21
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface 21
Abstract 1
Status of This Document 2
Acknowledgements 2
Conformance-related definitions 2
Contents 3
1 Introduction 3
1.1 Registry Architecture and Definitions 4
1.2 Specification Summary 6
2 Searching 7
2.1 Handling large volume of data 8
2.1.1 Paginate Scheme 8
2.1.2 Identifiers scheme 9
2.2 Constraint-based Search Query 9
2.2.1 Restrictions on the use of XPath in ADQL 10
2.3 Keyword Search Query 11
2.4 Single Resource Search Query 12
2.5 Xquery Search 13
3 Harvesting 13
3.1 Harvesting Interface 13
3.1.1 A Summary of the OAI Web Service Interface 14
3.1.2 Metadata Formats for Resource Descriptions 16
3.1.3 Identifiers in OAI Messages 17
3.1.4 Required Records 18
3.1.5 The Identify Operation 18
3.1.6 IVOA Supported Sets 19
3.2 Harvesters 20
4 Registering Registries Harvesting 20
Appendix A.1 Web Services Definition Language Document for the Search Interface 20
Appendix A.2 Web Services Definition Language Document for OAI-PHM 20
Appendix A.3 Recommended Descriptions for IVOA Reserved Sets 20
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface 20
Abstract 1
Status of This Document 2
Acknowledgements 2
Conformance-related definitions 2
Contents 3
1 Introduction 4
1.1 Registry Architecture and Definitions 5
1.2 Specification Summary 6
2 Searching 7
2.1 Constraint-based Search Query 8
2.1.1 Restrictions on the use of XPath in ADQL 10
2.2 Xquery Search 11
2.3 Keyword Search Query 12
2.4 Single Resource Search Query 13
3 Harvesting 13
3.1 Harvesting Interface 14
3.1.1 A Summary of the OAI Web Service Interface 14
3.1.2 Metadata Formats for Resource Descriptions 16
3.1.3 Identifiers in OAI Messages 17
3.1.4 Required Records 18
3.1.5 The Identify Operation 19
3.1.6 IVOA Supported Sets 19
3.2 Harvesters 20
4 Registering Registries Harvesting 21
Appendix A.1 Web Services Definition Language Document for the Search Interface 21
Appendix A.2 Web Services Definition Language Document for OAI-PHM 21
Appendix A.3 Recommended Descriptions for IVOA Reserved Sets 21
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface 21
Abstract 1
Status of This Document 2
Acknowledgements 2
Conformance-related definitions 2
Contents 3
1 Introduction 4
1.1 Registry Architecture and Definitions 4
1.2 Specification Summary 6
2 Searching 7
2.1 Constraint-based Search Query 9
Restrictions on the use of XPath in ADQL 10
2.2 Keyword Search Query 12
2.3 Finding Other Registries 13
3 Harvesting 14
3.1 Harvesting Interface 14
3.1.1 A Summary of the OAI Web Service Interface 15
3.1.2 Metadata Formats for Resource Descriptions 17
3.1.3 Identifiers in OAI Messages 18
3.1.4 Required Records 19
3.1.5 The Identify Operation 19
3.1.6 IVOA Supported Sets 20
3.2 Harvesters 21
4 Registering Registries Harvesting 22
Appendix A.1 Web Services Definition Language Document for the Search Interface 23
Appendix A.2 Web Services Definition Language Document for OAI-PHM 23
Appendix A.3 Recommended Descriptions for IVOA Reserved Sets 23
Appendix A.4 Web Services Definition Language Document for the Harvesters Interface 23
Introduction
In the Virtual Observatory (VO), registries provide a means for discovering useful data and services. To make discovery efficient, a registry typically represents to some extent a centralized warehouse of resource descriptions; however, the source of this informationthe resources themselves and the data providers that maintain themare distributed. Furthermore, there need not be a single registry that serves the entire international VO community. Given the inherent distributed nature of the information used for resource discovery, there is clearly a need for common mechanisms for registry communication and interaction.
This document describes the standard interfaces that enable interoperable registries. These interfaces are based in large part on a Web Service definition in the form of a WSDL document HYPERLINK \l "wsdlv1_1" [WSDLv1.1], which is included in this specification. Through these interfaces, registry builders have a common way of sharing resource descriptions with users, applications, and other registries. Client applications can be built according to this specification and be able to discover and retrieve descriptions from any compliant registry.
This specification does not preclude a registry builder from providing additional value-added interfaces and capabilities. In particular, they are free to build interactive, end-user interfaces in any way that best serves their target community. In a similar spirit, this specification does not intend to enforce completely identical behavior of required operations across all compliant implementations. In particular, this specification does not require that identical search queries sent to different compliant registries return identical results. Implementations are free to support different strategies for evaluating an ambiguous query (such as a keyword search) and ordering the results in a way that best serves the target community.
Registry Architecture and Definitions
A registry is first a repository of structured descriptions of resources., In the VO, building on concept of a VO resource is defined by the IVOA Recommendation, Resource Metadata for the Virtual Observatory (RM) HYPERLINK \l "RMref" [Hanisch 2004]:
A resource is a general term referring to a VO element that can be described in terms of who curates or maintains it and which can be given a name and a unique identifier. Just about anything can be a resource: it can be an abstract idea, such as sky coverage or an instrumental setup, or it can be fairly concrete, like an organization or a data collection.
Organizations, data collections, and services can be considered as classes of resources. The most important type of resource to applications is a service that actually does something. What is available at a particular resource is described through the content of metadata, whereas the service metadata describes how to access it. The RM describes a registry, then, as a service for which the response is a structured description of resources HYPERLINK \l "RMref" [Hanisch 2004]. Each resource description it returns is referred to as a resource record.
This specification is based on the general IVOA model for registries HYPERLINK \l "regarch" [Plante et al. 20042003], which builds on the RM model for resources. In the registry model, the VO environment features different types of registries that serve different functions. The primary distinction is between publishing registries and searchable ones. A secondary distinction is full versus local.
A searchable registry is one that allows users and client applications to search for resource records using selection criteria against the metadata contained in the records. The purpose of this type of registry is to aggregate descriptions of many resources distributed across the network. By providing a single place to locate data and services, applications are saved from having to visit many different sites to just to determine which ones are relevant to the scientific problem at hand. A searchable registry gathers its descriptions from across the network through a process called harvesting.
A publishing registry is one that simply exposes its resource descriptions to the VO environment in a way that allows those descriptions to be harvested. The contents of these registries tend to be limited to resources maintained by one or a few providers and thus are local in nature; for example, a data center will run its own publishing registry to expose all the resources it maintains to the VO environment. Since the purpose is simply publishing and not to serve users and applications directly, it is not necessary to support full searching capabilities. This simplifies the requirements for a publishing registry: not only does it not need to support the general search interface, the storage and management of the records can be simpler. While a searchable registry in practice will necessitate the use of a database system, a publishing registry can easily store its records as flat files on disk.
Note that some registries can play both roles; that is, a searchable registry may also publish its own resource descriptions.
A secondary distinction is full versus local. A full registry is one that attempts to contain records of all resources known to the VO. In practice, this attribute is associated only with HYPERLINK \l "searchregistry" searchable registries, as in the so-called full searchable registry. It is expected that there will be several such registries available, perhaps each run by a major VO project; this not only avoids the single point of failure, but allows some specialization to serve the particular needs of the project that maintains it. A local registry, on the other hand, contains only a subset of known resources. In practice, all HYPERLINK \l "pubregistry" publishing registries are local; however, we expect that there may be local searchable registries that specialize in particular types of resources, perhaps oriented toward a scientific topic.
As mentioned above, harvesting is the mechanism by which a registry can collect resource records from other registries. This mechanism is used by full searchable registries to aggregate resource records from many publishing registries. It can also be used to synchronize two registries to ensure that they have the same contents. Harvesting, in this specification, is modeled as a pull operation between two registries. The harvester refers to the registry that wishes to receive records (usually a HYPERLINK \l "searchregistry" searchable registry); it sends its request to the harvestee (usually the HYPERLINK \l "pubregistry" publishing registry), which responds with the records. Harvesting is intended to be a much simpler process than search and retrieval; nevertheless, there are at least two kinds of filtering that a harvestee needs to support:
Filtering by date: this allows the harvester to return to the harvestee periodically to retrieve only new and updated records.
Filtering by ownership: by harvesting only those records that originated with the harvestee (as opposed to those that may have been harvested from other registries) prevents a harvester from receiving duplicate records from multiple registries.
Other kinds of filtering can be useful as well (such as filtering on resource type). Note, however, that filtering is not intended to be an equivalent to arbitrary searching; rather, it is a gross selection that can be easily implemented without having to process the contents of each record.
Specification Summary
The purpose of the registry is to be used by other applications to provide access to various types of resources. At the programmatic level, connectivity of the registry and other applications is ensured through the registry interface as defined by this document. Much of the interface is defined as a SOAP-based Web Service and is described the WSDL documents included in Appendix A.1, while the harvesting interface (section 3) is specifically defined by the Open Archives Initiative standard called the Protocol for Metadata Harvesting (OAI-PMH) [OAI]. The IVOA Registry relies on the Web Service interface version, which defines what arguments are required for harvesting and search of the resources, as well as the messaging mechanism. The IVOATo define the rRegistry interface, this document includes the following definitions:
The meaning and behavior of three types offour required searching operations, one optional search operation, and six required harvesting operations.
The required input arguments for each operation.
The XML Schema used to encode response messages.
The meaning of the output for each operation.
The registry interface is composed of two independent parts. The harvesting interface provides the mechanism for registries to talk to each other and share information. The searching interface is used by clients that want to discover resources to use as part of a VO application. A registry may implement either interface or both, depending on the roles it intends to play.
The IVOA Registry collects the lists of resource descriptions that match specific criteria via the search operation. The IVOA Registrysearching iInterface can return XML descriptions of resources, or resource records, and it consists of fourtwo required search operations, described in more detail in HYPERLINK \l "_Searching" section 2:
Search searches the Registry in order to obtain the VO resourcesreturns resource records that match a specific set of constraints.
KeywordSearch is a helper query based on a set of key wordsreturns resource records containing specified keywords.
GetResource returns a single resource records identified by its unique IVOA identifierlooked up based on an identifier to obtain one and only one VO Resource.
GetIdentity returns a singlethe resource record describing the searchable registry itselfof the type vg:Registry for this registry implementation.
The searching interface also includes an optional, alternative search option based on XQuery.
The harvesting interace, which allows The one registry can to collect resource records from other registries, leverages the OAI-PMH standard [OAI]. Described in more detail in section 3, the OAI-PMH interface is using composed one of the six operations, which support resource harvesting. The operations listed below are described in more detail in 3.1.1. The most important commonly used harvesting operation is the ListRecords, which collects can return the descriptions of the resources based on constraints such as date and time periodof a particular category, or set,.that have been created or updated since a specified date. Normally the harvester will request records from the set that originate from that registry (as opposed to those harvested from another registry). This set is said to be managed by the registry. The ListRecords interface provides for the retrieval of all resources that are managed by its corresponding Registry. plus Rresources of the type Registry are also harvestable by means of the ListRecords interface, The complete list of OAI-PMH harvesting operations is shown below and their implementation follows the OAI standards are:
Identify returns the resource record describing the harvestable registry itself.
ListIdentifiers lists the identifiers of records that have changed since a given date
ListRecords lists the full descriptions of resources that have changed since a given date.
GetRecord returns a single record identified by its identifier.s
ListMetadataFormats lists the available output description formats.
ListSets lists the categories of records that can be requested.
The searching and harvesting operations that return resource descriptions do so using the VOResource XML Schema and any of its legal extensions HYPERLINK \l "voresource" [VOResource].
Searching
The four required operations that make up the searching interface fall into two groups: search and resolve. The search operationsThe required search operationsSearch and, KeywordSearch, GetResource, GetIdentity return a list of one or more resource descriptions held by the registry that matchregistry that matches the input selection criteria. The Search operation supports The fourthree search operations respectively support three types of searching:
cConstraint-based sSearching for resources by means of a query using the Astronomical Data Query Language (ADQL) HYPERLINK \l "adql" [ADQL], KeywordSearch provides
kKeyword-based sSearching for resources whose descriptions contain words in an input string.
The resolve operations---GetResource and GetIdentity---each return one and only one resource description. The GetResource resolves a unique IVOA Identifier [Identifier] to the description of the associated resource. The GetIdentity returns the resource record of the searchable registry itself.Identifier-based Searching for returning one and only one resource based off of aspecified via that resources uniquie identifier.
Self-based Search for returning one and only one resource of type vg:Registry that defines this Registry implementation.
Editors Note:
It is important to note that search operations do not support resource harvesting described in section 3. Normally, an end-user would use search to retrieve resource descriptions, but not to selectively harvest information between registries.These two threefour operations are defined by the WSDL document given in HYPERLINK \l "_Appendix_A.1__Web Services Definiti" Appendix A.1. HYPERLINK \l "searchregistry" Searchable registries must implement all the four operations.
The searchable interface allows additional, optional search operations. Currently, this specification defines only one optional operation. XQuerySearch returns selected information extracted from resource descriptions that match a set of constraints expressed using the XQuery syntax [XQuery].
These operations are implemented to accept input parameters and return output results as SOAP messages in compliance with the WSDL document given in HYPERLINK \l "_Appendix_A.1__Web Services Definiti" Appendix A.1. Compliant searchable registries must return a copy of the WSDL document whenever a client invokes the service endpoint URL with the ?wsdl argument appended to it. The returned WSDL may contain additional operations beyond those specified in this section; however, the original searching operations, their arguments and their outputs must not be altered.
Required Search Operations
The two search operationsSearch and KeywordSearchreturn resource records that match a set of selection criteria.
Output Format
The two search All thee operations share a common output format for the resource records that match the search criteria. The response is a SOAP message in compliance with the WSDL document given in Appendix A.1. This message is defined to have a single part: a SearchResponse element from the HYPERLINK "http://www.ivoa.net/wsdl/RegistrySearch/v1.0" http://www.ivoa.net/wsdl/RegistrySearch/v1.0 namespace. This element in turn wraps a single VOResources element which contains each of the matching records These records are encoded in XML and wrapped in a root element called VOResourcesand conforms to the following XML Schema definition:
VOResources Element Definition.The [required] VOResources attributes allow the results of the query to be paged over several calls which can be controlled via the operation input parameters, from and max. They assume that over some limited amount of time multiple calls to a search operation on a single registry with the same search constraints returns the same results and in the same order.
VOResources AttributesAttributeDefinitionfromValue Type:integerSemantic Meaning:the 1-relative position of the first record returned among the total set of matched elements.numberReturnedValue Type:integerSemantic Meaning:the number of records returned in this response.moreValue Type:booleanSemantic Meaning:If true, additional results are available beginning with a position of from + numberReturned. If false, no more results are available beyond this set. If all records matched by the query are returned in a single response the value of more must be set to false and from must be set to 1.
Example:
...
The contents of the VOResources element depends on the value of the operation input parameter, identifiersOnly. If this parameter is set to true, then the VOResources element must contain a list of identifier elements that contain the IVOA identifiers of resources that match the input query. If identifiersOnly is false, then the VOResources element must contain a list of Resource elements containing the full VOResource descriptions of resources that matches the query. Each The resource records are represented as child Resource elements element is of type Resource from the VOResource XML Schema (having the namespace, HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0" http://www.ivoa.net/xml/VOResource/v0v1.10, hitherto referred to using the vr: prefix), or a legal extension of the vr:Resource type. If the type of the Resource element is actually an extension of the vr:Resource type, then the Resource element MUST specify the specific type using an xsi:type attribute (where the xsi prefix refers to the HYPERLINK "http://www.w3.org/2001/XMLSchema-instance" http://www.w3.org/2001/XMLSchema-instance namespace) in compliance with the XML Schema standard HYPERLINK \l "xmlschema" [Schema].
The search responses must include the xsi:schemaLocation attribute (regardless of the value of identifiersOnly) in compliance with the XML Schema standard HYPERLINK \l "xmlschema"[Schema] to indicate a URL location for the VOResource schema and all of the legal extensions of VOResource that are employed in the response. This xsi:schemaLocation attribute must appear either as an attribute of the VOResources element or as an attribute of each child Resource element (when identifiersOnly is false) or both. When xsi:schemaLocation appears as an attribute of Resource, locations need only be given for the schemas employed within that resource. The URL location for the VOResource core schema ( HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0" http://www.ivoa.net/xml/VOResource/v1.0) must be set to HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0" http://www.ivoa.net/xml/VOResource/v1.0. For those legal extensions that are standard schemas recognized by the IVOA, the location should be set to the standard location in the IVOA Document repository whose URL begins with http://www.ivoa.net/xml/.
Example: This illustrates the use of xsi:type and xsi:schemaLocation attributes in the search output results. the xsi:schemaLocation attribute contains pairs of values where the first value is the schema namespace and the second value is the URL location of that schema. For IVOA standard schemas, the namespace can be used as the URL location.
Example: In this example, the xsi:schemaLocation attribute is attached to each Resource element.
The location of the schema for the vr:Resource must be always included in the output resource record identified in the xs:schemaLocation attribute. View Appendix A.1 for the searching interface WSDL to see the use of the imported VOResource schema placed inside the root element of VOResources.
If a legal search query does not match any resource records, the VOResources element must contain no Resource elements. If the input search query is illegal in its syntax or the operation encounters any other errors that prevents returning the requested records, the operation must return an ErrorResponse fault, represented by a ErrorResponse element:
ErrorResponse Element Definition
A ErrorResponse element must include a human-oriented error message describing the nature of the error.
Editors Note:
This document complies with the current version of the VOResource specifications. When a new VOResource schema evolves, this document should be updated accordingly.The registry interface must implement the threeboth Search operations in order to comply with communication and interaction standards for a Web Service. Searchable registries compliant with the augmented SOAP must return a copy of the WSDL document, with a service element appropriate for the local endpoint URL appended in response to a call to the Web Service URL with the standard ?wsdl argument. Additional operations may be added;, however original search operations and their arguments and outputs must not be altered.
Handling large volume of data
Two of the required search interfaces Search, and KeywordSearch return a list of one or more resource descriptions which can comprise large data volumes depending on the query. These two interface methods can be run with a set of optional parameters that help reduce the amount of data. These are a paginate scheme and an identifier scheme.
A client may wish to use none, all, or a mix of these optional parameters.
The optional parameters:
from starting point of a returned list of Resources. If not specified, the default is 1.
to ending point of a list of Resources. If not specified, the default is then the end of the list of Resources, or the registriesrys own limit implementation(where relevant), which ever comes first.
identifiersOnly Boolean to indicate return only identifiers.
Paginate Scheme
Clients are allowed to provide the parameter showing the starting number of a record from the selected set, as well as to supply an ending record number.
The operation is capable of returning query results incrementally. The client can view the results of an ADQL query or Keyword search starting from a certain record number to a specific record numberin a specified record number range. The output of resource records identifies the starting and the ending record numbers displayed on the page, as welandl as a Boolean attribute showing whether more records/result pages are available further. The search interface with incremental result returns resource records in sets identified by the attributes:
from shows the starting number of the returned resource record shown by the set
numberReturned the total number of returned resource records.
more a Boolean value. True shows that more results are available, false identifies the end of the returned search results.
Example:
...
The client is given an option of choosing the number of records to be returned;, however, the search service allows for the implementer to establish a default setting for the result return. Therefore although the client may not specify values of from and to parameters in the search, the client may get an incremental records output depending on the implementation.
Identifiers scheme
The Search and KeywordSearch interface now supports an option that allows returning only the identifiers of the selected records, twhereby decreasing the search processtime and the output spacevolume. To take advantage of this option the client must supply a true value to the parameter identifiersOnly.
Constraint-based Search Query
The Search method operation allows clients to retrieve a list of resource descriptions that match constraints of values corresponding to specific metadata in from the VOResource schema (and its legal extensions). The operations input message is defined to have a single part, a Search element, which contains four child elements that serve as the four input parameters:
Search Element Definition
Search Parameter ElementsElementDefinitionWhereValue Type: an ADQL/x Where clauseSemantic Meaning:the constraints to use for selecting matched resource recordsOccurances:requiredfromValue Type:integerSemantic Meaning:the minimum position in the complete set of matched records of the range of records to be returnedOccurances:optional; default: 1maxValue Type:integerSemantic Meaning:the maximum number of matched records to return. The service may choose to return fewer.Occurances:optional; default: the maximum that the service can deliveridentifiersOnlyValue Type:booleanSemantic Meaning:If true, return the results as a list of identifiers; if false, return as a list of complete resource descriptions. Occurances:optional; default: false
IVOA HYPERLINK \l "searchregistry" searchable registries must implement the Search interfacemethod, which takesThe one required parameter, thea Where element, is of type whereType from the ADQL XML Schema HYPERLINK \l "adql" [ADQL] (having the namespace, http://www.ivoa.net/xml/ADQL/v0.81.0, hitherto referred to using the adql: prefix; see Appendix A.1) which contains the constraints that specific components of the resource metadata must satisfy. The specific components are named using adql:Column elements subject to the following restrictions:
The Table attribute, which is required by the ADQL Schema, should be set to an empty string and must be ignored by the Search method implementation.
The Name attribute, which is required by the ADQL Schema, may be set to an empty string or to a short name to serve as an alias for the resource metadatum referred to. This value must be ignored by the Search method.
The xpathName attribute must be set to a restricted XPath string, subject to the rules in section 2.21.1. This XPath string identifies the specific VOResource element (or legal extension) within the resource record that is to be constrained.
The Search implementation selects matching active or inactive resources as if the ADQL query were being applied to a single table in which each row is a single HYPERLINK \l "resourcerecord" resource record and the columns include the resource metadata components referred by xpathName XML attributes. Matched resource records are then encoded using the VOResource XML Schema (and its legal extensions) according to the specifications given in the Search WSDL and described in Section 2, and they should include all information available to the registry that is compliant with the VOResources definitions.
Restrictions on the use of XPath in ADQL
The value of the xpathName attribute in any adql:Column element used within the input to the Search method must be a legal XPath HYPERLINK \l "xpath" [XPath] string that is restricted in form by the following rules:
The path points to an element or attribute value within a resource description encoded with the VOResource schema and/or any of its legal extensions.
When the path points to a specific element, that element must be of a simple type as definied by the XML Schema standard HYPERLINK \l "xmlschema" [Schema]
The path is relative and assumes that the HYPERLINK "http://www.w3.org/TR/xpath/" \l "dt-context-node" context node is the element that forms the parent of a single resource description (e.g. a Resource element) and is of type vr:Resource or one of its legal extensions.
The path must be composed only of HYPERLINK "http://www.w3.org/TR/xpath/" \l "section-location-step" location steps with HYPERLINK "http://www.w3.org/TR/xpath/" \l "axes" child axes expressed using the HYPERLINK "http://www.w3.org/TR/xpath/" \l "path-abbrev" abbreviated syntax for child elements and attributes: elements are referred to simply by their name, and attributes are referred to by their name preceded by an @ character. Unabbreviated location stepsi.e., those that require the double colon (::) syntaxare not allowed. All other types of abbreviated axes, including use of double slashes (//), single and double periods (. and ..), and wildcards (*), are not allowed.
The path must not include any predicates (i.e., qualifiers expressed using square brackets, []).
When xsi is used as an attribute prefix, it is implicitly assumed to refer to the HYPERLINK "http://www.w3.org/2001/XMLSchema-instance" http://www.w3.org/2001/XMLSchema-instance namespace.
Note:
Because VOResource schema and its legal extensions set elementFormDefault and attributeFormDefault to both be unqualified, prefixes are not normally required to qualify elements and attributes. xsi:type is an exception because it is technically a global attribute, and attributeFormDefault does not apply; thus, the prefix would be required in a standard XPath, which is why the last rule is needed. An known exception at this time is the case of the Space-Time Coordinates schema (STC, HYPERLINK "http://www.ivoa.net/xml/STC/stc-v1.30.xsd" http://www.ivoa.net/xml/STC/stc-v1.30.xsd) which defines many global elements; thus, technically, these elements would require prefixes, too. This document does not address the problem of querying against these element because it specifies no additional rules for understanding the mapping of other prefixes used in the context of a ADQL query. Because of the complexity of STC, it is not likely that normal ADQL (or XQuery) queries will be particularly useful. Thus, the problems of invoking other prefixes within ADQL and generally querying against STC is left to be solved in a future version of this document.
Because of the standard use of schemas to define elementformdefault=unqualified. No prefixes are needed in the xpath of elements or attributes. With the exception of @xsi:type.
Queries to @xsi:type value does not have to include a prefix, Registry Implementations much account for client queries with no prefix to @xsi:type.
This restricted form of XPath is intended to make it straight forward to transform the ADQL Where clause to a string-based querynamely SQL and XQuerythrough a static mapping from an XPath to an attribute in a local database without parsing the internal content of the path.
Legal Examples:
curation/publisher
the resource publishers name
HYPERLINK "mailto:curation/publisher/@ivo-id" curation/publisher/@ivo-id
the publishers IVOA identifier
@xsi:-type
the specific type of resource
capability/ HYPERLINK "mailto:interface/@xsi-type" interface/@xsi:-type
the specific type of interface
Illegal Examples:
Resource/title
wrong context node
cContent
not an element with a simple type
curation/child::publisher
child:: syntax not allowed
HYPERLINK "mailto:curation//@ivo-id" curation//@ivo-id
// syntax not allowed
capabilityInterface[@xsi-type="vgvs:WebServiceHarvest"]/accessURL
[] syntax not allowed
Note:
Because this specification does not provide any rules for understanding the prefixes that might appear in a XPath used in an ADQL where clause (apart from xsi), it is not obvious how best to query against the values of xsi:type attributes. Here are some recommended techniques doing so, expressed using ADQL/s:
capability/@xsi:type like '%:ConeSearch'
Select services supporting the ConeSearch capability.
@xsi:type like '%:Service'
Select generic Service resources only
@xsi:type like '%Service'
Select any resource with Service in its name, including Service, DataService, and CatalogService.
Editors Note:
A rule regarding the handling of namespaces is needed.
Keyword Search Query
The purpose of the KeywordSearch operation is to provide a simple way to select resources based on the string values in their resource descriptions. The operations input message is defined to have a single part, a KeywordSearch element, which contains five child elements that serve as the five input parameters:
KeywordSearch Element Definition
KeywordSearch Parameter ElementsElementDefinitionkeywordsValue Type: text stringSemantic Meaning:the list of words or phrases to search for within resource descriptionsOccurances:RequiredorValuesValue Type: booleanSemantic Meaning:if true, apply multiple word/phrase constraints with a logical OR; if fase, apply with a logical ANDOccurances:optional; default: true1fromValue Type:integerSemantic Meaning:the minimum position in the complete set of matched records of the range of records to be returnedOccurances:optional; default: 1maxValue Type:integerSemantic Meaning:the maximum number of matched records to return. The service may choose to return fewer.Occurances:optional; default: the maximum that the service can deliveridentifiersOnlyValue Type:booleanSemantic Meaning:If true, return the results as a list of identifiers; if false, return as a list of complete resource descriptions. Occurances:optional; default: falseThe meaning of the last three parameters above and their effect on the output is the same as for the Search operation.
The output of the operation is a set of matched resource descriptions in the same format as from the Search operation and specified in section 2.
IVOA HYPERLINK \l "searchregistry" searchable registries must implement the KeywordSearch(String words, Boolean orValue) method, which has two required parameters:
String words: The first parameter is a parameter of type xs:string that consists of at least one or more words separated by whitespace characters. The characters that qualify as whitespace are the same as in XML: space (x20), tab (x9), line feed (xA), and carriage return (xD).
Boolean orValues: The second parameter is of type xs:boolean which determines the logical operand to be applied. Either an AND or an OR operand can be applied when querying with more than one word. If this parameter has a TRUE value, then any of the words must appear in the resource description in order for the resource to be returned. If the this second parameter is FALSE, then all of the words must appear in the HYPERLINK \l "resourcerecord" resource record in order for the record to be returned.
The keywords parameter is a string that consists of one or more words separated by whitespace characters. The characters that qualify as whitespace are the same as in XML: space (x20), tab (x9), line feed (xA), and carriage return (xD). The KeywordSearch implementation forms a query by, in effect, creating a search constraint for each word in the words parameter. A phrase is a portion of keywords parameter that is enclosed in double quotation marks (e.g. black hole); when the phrase is extracted from the parameter, the quotation marks are removed, and a string normalization is applied that ignores leading and trailing whitespaces and treats consecutive whitespaces as a single space. Non-quoted Wwords are extracted from the keywords parameter after applying the same string normalization that ignores leading and trailing whitespaces and treats consecutive whitespaces as a single space.
The KeywordSearch implementation forms a query by, in effect, creating a search constraint for each word or phrase in this parameter. A phrase can be optionally implemented by the registry for lookups of exact word order by encoding the words with quotation marks e.g. black hole. For each active or inactive HYPERLINK \l "resourcerecord" resource record, each word or phrase is compared against every value for a selected set of resource metadata that includes at minimum the following (drawn from the VOResource schema):
vr:identifier: the resources IVOA identifier
vr:content/ vr:description: the descriptive summary of the resource
vr:title: the resource title
@xsi:type: the specific type of resource specified as an extension of the xs:Resource type
vr:content/ vr:subject: the subject topics associated with the resource
vr:content/type: the general type of resource
The implementer may include What otheradditional metadata values in the comparison as they choose values the word is compared against (which may include non-string values) is a choice of the implementer. It is legal to compare the word with all simple type values in the record. If the word or phrase is contained within one of the selected set of resource metadatum values, the constraint evaluates as TRUE. It is up to the implementer to decide what it means for a word to be considered contained; for example, the implementation may also test for related forms of the word. The implementer may further parse the phrase into words and include comparison constraints on those individual words. The results of all of the constraint tests (one for each word) are combined logically according to the value of orValues: if orValues is TRUE, then the resource record is returned when any of the constraints are TRUE, and if it FALSE, then all constraints must be TRUE in order for the record to be returned.
Matched resource records are then encoded using the VOResource XML Schema (and its legal extensions) and should include all information available to the registry that complies with the definitions of the VOResource standards.
Note:
This specification provides wide latitude in how the KeywordSearch is implemented; thus, different registries may return different results to the same set of input keywords. If precision and consistency in results is important regardless of which registry is queried, users should favor the Search or XQuerySearch operations.
Editors Note:
KeywordSearch Implementations between Registries may give various different results. If exact and consistency is important use Search or optionally XQuerySearch methods to query the registry.
Single Resource Search QueryResolve Operations
The two resolve operationsGetResource and GetIdentityeach select and return a single resource record.
Output Format
The two resolve operations share a common output format for returning a single resource record. The response is a SOAP message in compliance with the WSDL document given in Appendix A.1. This message is defined to have a single part: a ResolveResponse element from the HYPERLINK "http://www.ivoa.net/wsdl/RegistrySearch/v1.0" http://www.ivoa.net/wsdl/RegistrySearch/v1.0 namespace. This element in turn wraps a Resource element of type vr:Resource or one of its legal extensions. As in with the search operations when the type of the Resource element is actually an extension of the vr:Resource type, then the Resource element MUST specify the specific type using an xsi:type attribute.
The Resource element must include a xsi:schemaLocation attribute in compliance with the XML Schema standard HYPERLINK \l "xmlschema"[Schema] to indicate a URL location for the VOResource schema and all of the legal extensions of VOResource that are employed in the response. As with the search operation responses, the URL location for the VOResource core schema ( HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0" http://www.ivoa.net/xml/VOResource/v1.0) must be set to HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0" http://www.ivoa.net/xml/VOResource/v1.0. For those legal extensions that are standard schemas recognized by the IVOA, the location should be set to the standard location in the IVOA Document repository whose URL begins with http://www.ivoa.net/xml/.
Identifier Resolution
The purpose of the GetResource operation is to provide a simple way to resolve a select a single resources based on the string value of its unique resourceIVOA iIdentifier to a full resource description. The input message is defined to have a single part, a GetResource element. This element contains the operations one input parameter, identifier, of type vr:IdentifierURI, encodes an IVOA identifier. TThe output message of the operation iscontains a single VOResource record matched to the resource identifierwhose identifier element matches the input identifier.
If the registry does not have a resource record (or otherwise cannot access one) with an identifier matching the input parameter, the GetResource operation should return a NotFound fault message, represented by a NotFound element:
NotFound Element DefinitionIncluding an error message in the fault response is optional but recommended.
If the operation encounters any error that prevents it from determining whether the identifier can be resolved to a description or otherwise prevents the delivery of that description, the operation must return an ErrorResponse fault as described in section 2.1.1. .
IVOA HYPERLINK \l "searchregistry" searchable registries must implement the GetResource(String identifier) method, which has one parameter of type vr:IdentifierURI that has( the identifier of the HYPERLINK \l "resourcerecord" resource record) in order for the record to be returned.
During the search operation the HYPERLINK \l "resourcerecord" resource record metadata is compared against the value fof the IVOA resource identifier vr:identifier. The result of the single resource search query is the selected resource metadata.
Identity QuerySearch
The purpose of the GetIdentity operation is to providce a simple way to get thea VOResource record of the type vg:Registry that definesscribes the implementingthis registry implementationitself. A client may then inspect this VOResource record to discover various information about the implemented rRegistry (See section 2.7).
The GetIdentity operation takes no parameters.
IVOA searchable registries must implement the GetIdentity() method which has no parameters.
The result is of a single VOResource record whose format conforms to the format described in section 2.2.1; however, with this operation, the Resource element must include an xsi:type attribute set to indicate the Registry resource extension type from the VORegistry extension schema (having the namespace HYPERLINK "http://www.ivoa.net/xml/VORegistry/v1.0" http://www.ivoa.net/xml/VORegistry/v1.0, hitherto referred to using the vg: prefix). The recommended value to express this type is vg:Registry. The VORegistry schema is described in section 4; see Appendix A.3 for the full XML Schema definition.
of type vg:Registry.
XQquery Search
XQuerySearch is an optional operation of the searching interface which allows clients to form constraint-based queries with greater control than the required Search operation. It also allows the client to control the format of the query output; in particular, the client can obtain only the metadata needed The purpose of the XQuerySearch operation is to provide a more convenient way of searching the hierarchal xml schema, and to provide the client with a way of obtaining only the subelement(s) they need (rather than and not the full Resource record) each time. The output of this operation is determined by the XQuery input. The client can determine if a searchable registry supports this operation by consulting the registrys resource description (see HYPERLINK \l "_Registering_Registries" Section 4).
The operations input message is defined to have a single part, an XQuerySearch element. This element contains the operations one input string parameter, xquery. The value of the xquery element is a string that states the query and must conform to the XQuery syntax [XQuery]. The XPath strings [XPath] used in the query must be written as if each resource record is stored as a separate document under a root element called RootResource. The operation implementation may translate the XPath as necessary to reflect the actual storage of the records within the registry.
The operations output message is also defined to have a single part, an XQuerySearchResponse element having the following definition:
XQuerySearch Element DefinitionThe specific XML content of the XQuerySearchResponse must comply with the format requested by the XQuery input query.
If a registry does not support XQuerybased queries, the XQuerySearch operation must be implemented to always return an UnsupportedOperation fault message. This message has a single part in the form of an UnsupportedOperation element:
OperationUnsupported Element DefinitionIncluding an error message in the fault response is optional but recommended.
All other error conditions encountered by the implementation that prevent the return of the query results should be handled by returning an ErrorResponse fault as described in section 2.1.1.
To determine if a registry supports the XQuery interface a client must inspect the WSDL of the searchable registry or the Registry type Resource for the optionalProtocol XQuery; xpath capability/optionalProtocol.
IVOA searchable registries may implement the XQuerySearch(String xquery) method which has one parameter:
String xquery: The first and only parameter is a string that conforms to xquery syntax . S, see information on xquery here: HYPERLINK "http://www.w3.org/XML/Query" http://www.w3.org/XML/Query
//RootResource word may be located in the xquery string parameter to denote the root or top element of a VOResource, and should be translated if necessary to the appropriate root element.
Finding Other Registries
Editors Note:
Would this operation be more useful if it were defined to return only those registries that it harvests from? Simply finding all registries can be accomplished with a simple ADQL query, as shown below.
Using Registry Resource for Specific Searching
A client may wish to interrogate the Registry Resource type @xsi:type=vg:Registry for certain requirements to be used for searching.
Discovery All Registries must implement the GetIdentity interfacebe used for searching.
ce type "d only one VO Resource. which returns the VOResource record of the vg:Registry type for that registry. As Noted in above section 2.4.
XQuery As Noted in the above section 2.6, you can discover if the registry supports XQuery by checking if the optionalProtocol is set to XQuery. Located xpath of capability/optionalProtocol
Full or Not Full a Boolean to indicate if this registry contains all VOResource records. Located xpath of full.
Extensions - Registries are required to return all data from a VOResource record including extensions, but searching on extensions is not required. Check for a Boolean to indicate if a registry can search extensions. Located xpath of allowsExtendedSearch.
The implementation must return the same response as the Search operation (section 2.1) given the following ADQL where clause (expressed here in ADQL/s format HYPERLINK \l "adql" [ADQL]):
@xsi:type=vg:Registry
Harvesting
Harvesting is the mechanism by which a registry can collect resource descriptions from other registries. This mechanism is used by full searchable registries to aggregate resource descriptions from many publishing registries. It can also be used to synchronize two registries to ensure that they have the same contents. This section defines the IVOA Harvesting Interface. Client applications that make use of this interface are referred to as harvesters. Those registries that declare themselves as harvestable (section 3.24) must comply with the specification described in this section. As Noted in the Abstract Registries may become harvestable by implementing the HTTP GET interface of OAI as an alternative to the SOAP Service interface described.
3.1 Harvesting Interface
This specification defines two variants of the harvesting interface, both built The harvesting interface builds on the Web Service version standard of the Open Archives Initiative Protocol for Metadata Harvesting developed by Open Archives Initiative (OAI-PMH) [OAI]. The first variant is one that is fully compliant with the OAI-PMH version 2.0 standard; aIn particular, all IVOA harvestable rRegistries that support the Harvesting Interface must be compliant with the Web Service version of OAI-PMHmust support this variant. Compliance with this base standard allows IVOA registries to be accessed by applications from outside the IVOA community. The second variant, a Web Service version of the OAI interface (in which the input and outputs are transported as SOAP messages), is also defined as an optional alternative.
Editors Note:
OAI does not currently support an official Web Services version of PMH. One of the purposes of the development of this standard is to drive the evolution of the OAI standard which has demonstrated to be a highly effective harvesting protocol across a broad continuum of communities.In addition to basic OAI-PMH compliance, this specification defines an additional set of OAI-PMH- compliant requirements and recommendations which are described in sections 3.1.1 through 3.1..6 below. These apply to both variants of the harvesting interface.
A Summary of the OAI Web Service Interface
The required variant of the interface is defined by The Web Service version of OAI-PMH is defined by:
Tthe OAI-PMH v2.0 specification [OAI], which itself ( HYPERLINK "http://www.openarchives.org/OAI/openarchivesprotocol.html" http://www.openarchives.org/OAI/openarchivesprotocol.html) which defines:
the meaning and behavior of the six harvesting operations, referred to as verbs,
the meaning of the input arguments for each operation, and
the XML Schema used to encode response messages.
The optional Web Service variant of the interface is maps the meaning, behavior, and schema of the OAI-PMH specification into a Web Service Definition Language (WSDL) document (see Appendix A.2); this WSDL which defines:
the six verbs defined as Web Service operations
SOAP encoding of the operation input arguments and response messages, based on the OAI-PMH XML Schema.
In summary, the OAI-PMH standard defines six operations:
Identify: provides a description of the registry
ListIdentifiers: returns a list of identifiers for the resource records held by the registry.
ListRecords: returns all Resource records in the registry. Registries may use the set ivo_managed to get Resource records managed by this particular registry. set of resource descriptions. It returns all resources managed by the corresponding registry, as well as the resources of the Registry type. This operation is intended to be used by other HYPERLINK \l "searchregistry" searchable registries to locate harvestable registries.
GetRecord: returns a single resource description matching a given identifier.
ListMetadataFormats: returns a list of supported formats that the registry can use to encode resource descriptions upon a harvesters request.
ListSets: return a list of category names supported by the registry that harvesters can request in order to get back a subset of the descriptions held by the registry.
The ListRecords and GetRecord operations return the actual resource description records held by the registry. These descriptions are encoded in XML and wrapped in a general-purpose envelope defined by the OAI-PMH XML Schema (with the namespace HYPERLINK "http://www.openarchives.org/OAI/2.0" http://www.openarchives.org/OAI/2.0).
Through the operations arguments, OAI-PMH provides a number of useful features:
Support for multiple return formats. As suggested by the ListMetadataFormats operation, a harvester can request the format resource descriptions are encoded in.
Harvesting by date. The ListIdentifiers and ListRecords operations both support from and until date arguments. The from argument can be used to retrieve records that have changed since the last harvest.
Harvesting by category. The ListIdentifiers and ListRecords operations both support a set argument for retrieving resources that are grouped in a particular category. Resource records may belong to multiple groups.
Marking records as deleted. Registries may mark records as deleted so that harvesters may remove access to them from their applications.
Support for resumption tokens. If a request results in returning a very large number of records, the registry can choose to split the results over several calls; this is done by passing a aa resumption token back to the harvester. The harvester uses it to retrieve the next set of matching results.
Editors Note:
The Web Service version of the OAI-PMH protocol has been designed to match the behavior and functionality of the original HTTP GET-based version as much as possible. One reason for this is to make it as straight-forward as possible to build bridges between implementations of both types and to build off the existing OAI software.
Note:
It is important to note that the OAI-PMH interface is not intended to be a general search interface. The filtering capabilities described above are just enough to support intelligent harvesting between registries. Most end-user applications will use the search interface described in sections 3 and 4 to retrieve resource descriptions. The Web Service or SOAP version of OAI-PMH augments the original specification with a standard Web Service Definition Language (WSDL) document which is listed in Appendix AH.2. Harvestable registries complying to the SOAP version of OAI-PMH must emit a copy of the WSDL document, with a service element appropriate for the local endpoint URL added in, in response to a call to the Web Service URL with the standard ?wsdl argument. All six of the standard operations must be implemented. Additional, non-standard operations may be added; however, the definition of the six standard operations, along with the definition of their inputs and outputs, must not be altered. The interface is recognized as the OAI-PMH standard when the default namespace for the WSDL matches http://www.ivoa.net/wsdl/oai.wsdl exactly.
Editors Note:
The namespace for the WSDL would presumably be changed to something like HYPERLINK "http://www.openarchives.org/OAI-WS/1.0/" http://www.openarchives.org/OAI-WS/1.0/ if and when it is accepted by the OAI community.The subsequent sections below describe how the standard OAI-PMH features are used to support IVOA-specific functionality.
Metadata Formats for Resource Descriptions
All IVOA registries that support the Harvesting Interface must support two standard metadata formats: the OAI Dublin Core format (mandated by the base OAI-PMH standard) and the IVOA VOResource metadata format HYPERLINK \l "voresource" [ http://www.ivoa.net/xml/VOResource/v0.101.0].
The VOResource metadata format will have the metadata prefix name ivo_vor which can be used where ever an OAI-PMH metadata prefix name is supported (see OAI standard, section 3.4, metadataPrefix and Metadata Schema). The format uses the VOResource core XML Schema with the namespace HYPERLINK "http://www.ivoa.net/xml/VOResource/v1.0%20" http://www.ivoa.net/xml/VOResource/v10.0.10 (referred hereto with the namespace prefix vr) along with any legal extension of this schema (including the IVOA standard extensions) to encode the resource descriptions within the OAI-PMH metadata tag from the OAI XML Schema (namespace HYPERLINK "http://www.openarchives.org/OAI/2.0" http://www.openarchives.org/OAI/2.0, hereto referred by the namespace prefix oai). The format is specifically defined as an element called Resource vr: VOResource element as the sole child of the oai:metadata element. In compliance with the VOResource schema and any legal extensions., the child of the vr:VOResource element may be any legal extension of the vr:Resource element (i.e. that is, an element that is in the same substitution group as vr:Resource), except where otherwise restricted by this document. The Resource element must include a xsi:type attribute that assigns the elements type to vr:Resource or one of its legal extensions.
Editors Note:
If and when the VOResource schema evolves to a new version, this standard must be updated accordingly. Thus, this definition is locked to particular version of the VOResource, so saying that a registry is compliant with vX.X of this document implies a specific version of VOResource.
Note:
It is possible that the vr:Resource extension returned is unrecognized by the harvester. See section 3. for details about how a harvester may use setsparticularly the ivo_standard setto guarantee the return of records that can guarantee support forThe harvester must deal with this possible outcome by handling and storing of extensions or by ignoring vr:Resource metadata..
Note:
Use of a vr:Resource extension where a IVOA standard resource extension exists is strongly discouraged for records in the ivo_vor format. Implementers should consider defining a custom metadata format name to encode using non-standard vr:Resource extensions.
Editors Note:
A standard resource extension will be defined as an element type in theof vr:Resource substitution group in a schema that has been approved as an IVOA Recommendation. At this writing, no VOResource schemas have not reached this state, so for the purposes of prototyping, a standard resource extension will refer to any element in the vr:Resource type substitution group from the following schemas:
VOResource: http://www.ivoa.net/xml/VOResource/v0.101.0
VOCommunity: http://www.ivoa.net/xml/VOCommunity/v0.3
VORegistry: http://www.ivoa.net/xml/VORegistry/v0.31.0
VODataService: http://www.ivoa.net/xml/VODataService/v0.51.0
ConeSearch: http://www.ivoa.net/xml/ConeSearch/v1.0
SIA: HYPERLINK "http://www.ivoa.net/xml/SIA/v1.0" http://www.ivoa.net/xml/SIA/v1.0The OAI Dublin Core format, with the metadata prefix of oai_dc, is defined by the OAI-PMH base standard and must be supported by all OAI-PMH compliant registries. This document does not specify how a record in the VOResource format maps into the OAI Dublin Core format; however, the IVOA Registry Working Group may recommend such a mapping based on the IVOA Resource Metadata standard [ref].
Harvestable registries may support other metadata formats. The ListMetadataFormats must list all names for formats supported by the registry; this list must include ivo_vor and oai_dc.
Identifiers in OAI Messages
In accordance with the OAI-PMH standard, an OAI-PMH XML envelope that contains a resource description must include a globally unique URI that identifies that resource record. This identifier must be the IVOA identifier used to identify the resource being described and cited as the value of the vr:identifier resource metadatum.
Note:
This specification does not follow the recommendation of the OAI-PMH standard with regard to record identifiers. OAI-PMH makes a distinction between the resource record containing resource metadata and the resource itself; thus, it recommends that the identifier in the OAI envelope be different from the resource identifier. In particular, the former is the choice of the publishing registry. This allows one to distinguish resource descriptions of the same resource from different registries, which in principle could be different.
In the VO, because it is intended that resource descriptions of the same resource from different registries should not differ (apart from their validationLevel [VOResource]), there is not a strong need to distinguish between the resource and the resource description. By making the resource and resource record identifiers the same, it makes it much easier to retrieve the record for a single resource via GetRecord, regardless of which registry is being queried. Otherwisewhen the registry chooses the record identifiera client will not a priori know the record identifier for a particular resource, and so it is left to call ListRecords and search through the metadata of all the records itself to find the one of interest. In contrast, IVOA identifiers are intended to be a cross-application way of referring to a resource, and thus when a client wants only a single specific resource record, it is very likely that it would know the resource identifier when making a call to the GetRecord operation.Required Records
This section describes the records that a harvestable IVOA Registry must include among those it emits via the OAI-PMH operations.
The harvestable registry must return one record that describes the registry itself as a whole, and the ivo_vor format must be supported for this record. This record is included in the Identify operation response (see section 3.1.5). When encoded using the ivo_vor format, the returned vr:Resource element returned must be of the type be of an extension of vg:Registrysole child of the vr:VOResource element must be a Registry element from the VORegistry schema (namespace HYPERLINK "../../xml/VORegistry/v0.2"http://www.ivoa.net/xml/VORegistry/v1.0; hereto referred by the vg namespace prefix). The record must include a vg:mManagedAuthority for every Authority Identifier [ref IVOA Identifiers] that originated at that registry. The registry may contain other registry records for other registries it knows about; use of a vr:vr:RResource extension type elements other than vg:Registry to describe these other registries is strongly discouraged.
The harvestable registry must return exactly one record in ivo_vor format for each Authority Identifer listed as a vg:mManagedAuthority in the vg:Registry record that describes that registry. When encoded in the ivo_vor format, the sole child of thetype of vr: VOResource element must be an vg:Authority typeelement.
The Identify Operation
The Identify operation describes the harvestable registry as a whole. The response from this operation must include all information required by the OAI-PMH standard. In particular, it must include a oai:baseURL element which must refer to the base URL to the Web Serviceharvesting interface endpoint. When the Identify operation is called through the Web Service variant, the oai:baseURL element value must be the endpoint of the Web Service itself (i.e. the URL used to retrieve the WSDL document via the standard URL suffix, ?wsdl) unless the HTTP-GET is implemented by the Registry see below note..
Note:
A traditional HTTP GET implementation of OAI-PMH that serves as a bridge to Web Service implementation must transform the value of the oai:baseURL element to refer to itself rather than the delegate Web Service. The Identify response must include a oai:description element containing a single vr:Resource element with an xsi:type attribute that sets the elements type to of type vg:Registry element. This element must contain the proper namespace definitions for the record. TThe content of vg:Registry element type must be the registry description of the harvestable registry itself. Other oai:description elements are allowed; however, there may only be one containing the vg:Registry element.
IVOA Supported Sets
Sets, as defined in the OAI-PMH standard, is [are] an optional construct for grouping items for the purpose of selective harvesting (see the OAI-PMH standard, section 2.6). Harvestable IVOA registries are free to define any number of custom sets for categorizing records. The OAI-PMH standard allows a record to be a member of multiple sets. This document specification defines a set ofone reserved set names with a special meaning; future versions of this specification may define additional set namess. These reserved setir names will all start with the characters ivo_; implementers must should not define their own set names that begin with this string. While support for sets is optional to be compliant with the OAI-PMH standard, a harvestable registry must support the set with the Support for two one of the reserved name,sets, ivo_standard and ivo_managed,, to be compliant with this specification.
are is required by this specification; thus, when applied to IVOA-compliant harvestable registries, support for sets is not optional.
This specification implicitly optionally defines a set for each of the IVOA standard extensions to the vr:Resource element as well as the vr:Resource element itself. The set name is formed by prepending ivo_ to the local element name for the resource extension. (For example, a set defined for vg:Registry is named ivo_Registry.) A request for records in such a set will return records whose ivo_vor rendering features the associated resource extension. (For example, requesting the ivo_Registry set will return all records whose ivo_vor form has a vg:Registry element as the child type of the vr:VOResource element.) Requests for the ivo_Resource set (if supported) should return records whose ivo_vor form has a vr:Resource with no type extension hence no xsi:type defined.element as the child of the vr:VOResource element. Harvesting registries should support all sets associated with IVOA standard Resource extensions. Requests for these sets that are not supported should return an error (in accordance with the OAI-PMH standard), even if such records exist.
The ivo_standard optional set refers to all of the IVOA reserved sets that correspond to IVOA standard Resource extensions that are supported by the registry. Harvesters may request this set to guarantee getting back records it can fully parse. Harvesting registries must support this set.
The ivo_managed required set refers to all records that originate from the queried registry. That is, those records that were harvested from other registries are excluded. The IVOA Resource identifiers given in the records must have an Authority Identifier that matches on one of the vg:mManagedAuthority values in the vg:Registry record for that registry. Full searchable registries may use this set to avoid getting duplicate records when harvesting from many registries.
All sets that are supported by the harvestable registry, including the two one required sets, must be listed in the response to the ListSets operation in compliance with the OAI-PMH standard. Appendix A.3 lists the recommended set descriptions which can be returned by the ListSets operation for the IVOA reserved set names.
Harvesters
A registry registry that collects resource descriptions from other registries through the Harvesting Interface defined above in section 3.1 are is referred to as a harvester registry. A HYPERLINK \l "fullregistry" full registry attempts to establish a complete collection of all resource descriptions known to the VO either by replicating the contents of another full registry, ormore commonlyby selectively harvesting from all known publishing registries. Typically in the latter case, the harvester periodically engages the ListRecords operation of each know HYPERLINK \l "pubregistry" publishing registry with the metadataPrefix parameter set to ivo_vor, the set parameter set to ivo_managed, and the from parameter set to the time of the last successful harvest for that publishing registry.
Any registry that claims to be a HYPERLINK \l "fullregistry" full registry (see vg:full metadatum defined in Section 4) must accept all records it harvests that are compliant with the VOResource metadata standard HYPERLINK \l "voresource" [VOResource], even if the resource type is not one that is recognized by the registry. Whenever any registry (full or not) exports a harvested recordthrough either the searching or the harvesting interfaceit must return the complete record in its original format. The only change in the informational content allowed between harvesting and subsequent export is in the addition or removal of vr:validationLevel elements; more specifically, the registry may remove any or all of the vr:validationLevel elements in the record received via harvesting, and it may add vr:validationLevel elements in compliance with VOResource metadata standard and with a validatedBy attribute set to the registrys IVOA Identifier.
Note:
It is not intended that original format to mean a byte-for-byte copy; rather, it means that the descriptions are equivalent (apart from the vr:validationLevel elements) in an XML sense after discarding all ignorable whitespace.
Note:
The vr:validationLevel element provides a mechanism for a registry to rate the quality of a resource description and its adherence to relevant standards. Its usage is covered in the VOResource standard [VOResource].
Note that this document does not specify how a registry obtains the complete list of publishing registries, nor does it specify how a new publishing registry should make itself known to harvesters as both these issues are considered outside the scope of this specification. In the case of registry replication, the harvester can harvest from just the registry it is trying to replicate; the ListRecords operation can be used in much the same way except that the set parameter is not provided in order to get all records from that registry.
Note:
This document does not specify how a registry obtains the complete list of publishing registries, nor does it specify how a new publishing registry should make itself known to harvesters as both these issues are considered outside the scope of this specification.
As of this writing, the IVOA Registry Working Group has established a mechanism for discovering publishing registries in the form of a so-called, Registry of Registries (RofR). Hosted by IVOA, it provides a browser-based interface for registering a publishing registry. The RofR implements the harvesting interface; thus harvesters can regularly consult this registry via OAI-PMH to retrieve the vg:Registry records of available harvestees. Constult IVOA Document Repository for a Note describing the RofR in more detail. Harvesters can determine how to harvest from a registry by consulting its VOResource description. See Appendix A.1Section 4 describes the VOResource extension used to describe a registry and the interfaces it supports along with an example. for sample vg:Registry extension for deterimination of interface URL and method to which to call the registry such as HTTP-GET or SOAP. Harvesters must be able to harvest via SOAP or HTTP-GET interface. If both SOAP and HTTP-GET interfaces are defined in the vg:Registry extension then the harvester has an option of which interface to call.
A registry that operates in this mode should implement the Harvester Interface which provides a way for harvestable registries to request to be harvested from (e.g. because updates have recently occurred). A registry that conforms to the Harvesteris interface should indicate thisso within its registry description using the metadata provided in the VORegistry schema (namespace, HYPERLINK "http://www.ivoa.net/xml/VORegistry/v0.X"http://www.ivoa.net/xml/VORegistry/v0.3). A harvester registry that does not support this interface is understood to behas supporting some other mechanism for deciding which registries to harvest from and when to harvest.
The Harvester Interface is defined by the single operation WSDL listed in Appendix A.4. The operation called harvest is called to request that the harvestable registry referred to in the inputs be harvested from at the next earliest convenience of the harvester. The harvester, upon receipt of this request, has several options regarding when the harvesting will begin; it may choose:
to harvest immediately,
to postpone harvesting to a later time (e.g. to synchronize with its own update cycle), or
not to not harvest at all (e.g. because the inputs do not meet its criteria for harvesting).
The operations input arguments have the following meaning:
ivo-id: the IVOA Identifier for the harvestable registry requesting a harvest.
harvestingType: This indicates whether the harvesting registry supports the Web Serivce or the traditional HTTP Get version of the OAI protocol.
baseURL: the base URL for the service. Whether this is to be interpreted as a Web Service endpoint or the base URL in the sense of the traditional HTTP GET version of OAI-PMH depends on the value of harvestingType.
lastUpdate: the date of the last update made to any of the records held by the caller (optional)The discovery of new and/or updated registries is defined by the IVOA Registry more property known as Registry of Registries (RofR)..
Note:
It is recommended that a harvester registry limit how frequently it re-harvests from a harvestable registry; that is, if the harvester has harvested from a registry before, it should choose option (2) above. This will prevent multiple calls to the harvest operation in quick succession from triggering multiple, unnecessary harvesting processes. Instead, it should queue the request and ignore subsequent requests until the initial harvesting is complete.The Registry of Registries is hosted by IVOA for the discovery of other Registry types vg:Registry records. The Registry of Registries known as RofR only stores vg:Registry records and implements the Harvesting interface only. Full Registries should harvest RofR for discovery of new and/or updated Registries. See IVOA Note section on more detailed description of RofR.Registering Registries Harvesting
This specification defines a VOResource extension schema called VORegistry that can be used to specifically describe a registry and its support for the registry interface described in this document. These descriptions can be stored as resource records in registries. The schema is also used to register a naming authoritya publisher who claims ownership of an authority identifier from which IVOA identifiers may be created [Identifiers]. A publishing registry is said to exclusively manage a naming authority on behalf of the owning publisher; this means that only that registry may publish records with IVOA identifiers using that authority identifier.
The full VORegistry syntax definition expressed in XML Schema is listed in Appendix A.3.
The Schema Namespace and Location
The VORegistry schema namespace is " HYPERLINK "http://www.ivoa.net/xml/VORegistry/v1.0" http://www.ivoa.net/xml/VORegistry/v1.0". As with the core VOResource Schema, the namespace URI has been chosen to allow it to be resolved as a URL to the XML Schema document that defines the VORegistry schema. Applications may assume that the namespace URI is so resolvable. In particular, it is recommended the namespace URI be given as the location for the VORegistry schema within the xsi:schemaLocation attribute.
The namespace prefix, vg, is used by convention to represent the VORegistry schema. Registries and other applications are encouraged to follow this convention.
The Authority Resource Extension and the Publishing Process
The vg:Authority type extends the core vr:Resource type to specifically describe the ownership of an authority identifier [Identifiers] by a publishing organisation.
vg:Authority Type Schema DefinitionThe IVOA identifier of an vg:Authority record provided via the vr:identifier element must have an empty resource key component [Identifiers]. The authority identifier component of the records identifier is the one that is the subject of the record itself.
The vg:Authority type adds only one required item beyond the core VOResource metadata:
vg:Registry Extension ElementsElementDefinitionmanagingOrgValue Type:string with optional ID attribute: vr:ResourceNameSemantic Meaning:the organisation that owns or manages this authority identifierOccurances: requiredComments:This is almost always the organisation listed as the publisher of this Authority.The meaning of an vg:Authority record is that the organisation referenced in the vg:managingOrg element has the sole right to create, in collaboration with a publishing registry, and register resource descriptions using the authority identifier given by the vr:identifier element.
Before a publisher can create resource descriptions using a new authority identifier, it must first register its claim to the authority identifier by creating an vg:Authority record. Before the publishing registry commits the record for export, it must first search a full registry to determine if an vg:Authority with this identifier already exists; if it does, the publishing of the new vg:Authority record must fail. When a registry creates an vg:Authority record, it is said that the registry manages the associated authority identifier (on behalf of the owning publisher) because only that registry may create records with identifiers using that authority identifier.
Describing Registries with the Registry Resource Extension
The vg:Registry type extends the core vr:Service type to specifically describe registries that are compliant with this standard.
vg:Registry Type Schema Definition
vg:Registry Extension Metadata ElementsElementDefinitionfullValue Type: booleanSemantic Meaning:If true, this registry attempts to collect all resource records known to the IVOAOccurances:requiredmanagedAuthorityValue Type:an authority identifier: vr:AuthorityIDSemantic Meaning:an authority identifier that is managed by the registry Occurances:optional; multiple occurances allowedIf the vg:full element is set to true, the registry is obligated to accept all valid resource records it harvests from other registries in accordance with Section 4 of this specification.
The vg:managedAuthority element applies specifically to registries in their role as publishers of records. When a HYPERLINK \l "pubregistry" publishing registry claims to manage an authority identifier [Identifiers], it has created an vg:Authority resource record for that authority identifier (see HYPERLINK \l "_The_Authority_Resource_Extension an" section 4.2).
As a subclass of vr:Service, the vg:Registry type uses vr:capability elements to describe its support for the interfaces described in this specification. In particular, the VORegistry schema defines two extensions of the VOResources vr:Capability typeone to describe the support for the searching interface and one to describe the harvesting interfaceaccording to the recommendations for extension in the VOResource standard [ HYPERLINK \l "voresource" VOResource, section 2.3.2]. Both extension types extension types extend from an intermediate restriction on vr:Capability called vg:RegCapRestriction to force the value of the standardID attribute to be ivo://ivoa.net/std/Registry:
vg:RegCapRestriction Type Schema DefinitionAs an abstract type, the vg:RegCapRestriction type cannot be used directly on its own within a resource description; one of the non-abstract extensions of this intermediate type must be used instead.
The vr:Capability extension types are invoked by applying the xsi:type attribute to the vr:capability element [ HYPERLINK \l "voresource" VOResource, section 2.2.2]. If a registry supports both the searching and harvesting interfaces, the vg:Registry record should contain at least two vr:capability elements, one for each interface.
The Searching Capability
A registry declares itself to be a searchable registry by including a vr:capability element with an xsi:type attribute set to vg:Search.
vg:Search Type Schema Definition
vg:Search Capability Metadata ElementsElementDefinitionmaxRecordsValue Type: integer: xsd:intSemantic Meaning:The largest number of records that the registry search method will return. A value of zero or less indicates that there is no explicit limit.Occurances:requiredextensionSearchSupportValue Type:String with controlled vocabularySemantic Meaning:the level of support provided for searching against metadata defined in a legal VOResource extension schema.Occurances:requiredAllowed Values:core
Only searches against the core VOResource metadata are supported.
partial
Searches against some VOResource extension metadata are supported but not necessarily all that exist in the registry.
full
Searches against all VOResource extension metadata contained in the registry are supported.
optionalProtocolValue Type:string with controlled vocabularySemantic Meaning:the name of an optional advanced search protocol supported.Occurances:optionalAllowed Values:XQuery
the XQuery protocol as defined in section 2.3
A vr:capability element of type vg:Search must include at least one vr:interface element with an xsi:type attribute set to vg:WebService and the role attribute set to std. If the vr:capability element is used to simultaneously describe support for other versions of this Registry Interface standard, then the vr:interface element describing support for this version must include the version attribute set to 1.0. The vr:accessURL element must be set to the endpoint URL for the Web Service interface that complies with section 2 of this specification.
Note:
The requirement that a vg:WebService interface appear within a vg:Registry record not enforced by the XML Schema document. This requirement necessitates additional validation as described in the preface to the VOResource standard.
The Harvesting Capability
A registry declares itself to be a harvestable registry by including a vr:capability element with an xsi:type attribute set to vg:Harvest.
vg:HarvestSearch Type Schema Definition
vg:Harvest Capability Metadata ElementsElementDefinitionmaxRecordsValue Type: integer: xsd:intSemantic Meaning:The largest number of records that the registry search method will returned. A value greater than one implies that an OAI continuation token will be provided when the limit is reached. A value of zero or less indicates that there is no explicit limit and thus, continuation tokens are not supported.Occurances:RequiredThe VORegistry schema defines two special extensions of the vr:Interface type that are used to indicate support for the OAI-PMH interface:
vr:Interface Extension Types for OAI-PMH: Schema DefinitionA vr:capability element of type vg:Harvest must include at least one vr:interface element with an xsi:type attribute set to vg:OAIHTTP and the role attribute set to std. If the vr:capability element is used to simultaneously describe support for other versions of this Registry Interface standard, then the vr:interface element describing support for this version must include the version attribute set to 1.0. The vr:accessURL element must be set to the base URL for the OAI-PMH interface that complies with section 3 of this specification.
If the SOAP web service variant of OAI-PMH is supported, the record should include an additional vr:interface element with its type set to vg:OAISOAP and the role attribute set to std:SOAP. If other versions of the SOAP harvesting interface are described in this same URL, the version attribute for OAI-SOAP interface must b set to 1.0.
]
Registry Sample Instance DocumentIVOA Registry of Registries sample entryRofRivo://ivoa/registry
IVOA
Ray Plantehttp://www.ivoa.net/
2006-08-08Ray Planterplante@ncsa.uiuc.eduregistry repositories
This registry provides information regarding other registries.
http://www.ivoa.netRegistryResearch http://www.ivoa.net/cgi-bin/rofr/oai.pl http://www.ivoa.net/rofr/RegistryHarvest 100falseivoaivoa.netIVOA Registry of Registries sample entryRofRivo://ivoa/registry
IVOA
Ray Plantehttp://www.ivoa.net/
2006-08-08Ray Planterplante@ncsa.uiuc.eduregistry repositories
This registry provides information regarding other registries.
http://www.ivoa.netRegistryResearch http://www.ivoa.net/cgi-bin/rofr/oai.pl http://www.ivoa.net/rofr/RegistryHarvest 100falseivoaivoa.net
Appendix A.1 Web Services Definition Language Document for the Search InterfaceSample extension of vg:Registry
IVOA Registry of Registries sample entryRofRivo://ivoa/registry
IVOA
Ray Plantehttp://www.ivoa.net/
2006-08-08Ray Planterplante@ncsa.uiuc.eduregistry repositories
This registry provides information regarding other registries.
http://www.ivoa.netRegistryResearch http://www.ivoa.net/cgi-bin/rofr/oai.pl http://www.ivoa.net/rofr/RegistryHarvest 100falseivoaivoa.net
Appendix A.12 Web Services Definition Language Document for OAI-PHMSearch Interface
Currently
RegistrySearch Interface WSDL
See: http://www.ivoa.net/twiki/bin/view/IVOA/RegistryInterface
Appendix A.23 Recommended Descriptions for IVOA Reserved Sets
Appendix A.4 Web Services Definition Language Document for the Harvesters Harvesting Interface
RegistryHarvest Interface WSDL
Appendix A.3 VORegistry: the VOResource Extension Schema for Registering Registries
VORegistry Extension Schema
a service that provides access to descriptions of resources.
A registry is considered a publishing registry if it
contains a capability element with xsi:type="vg:Harvest".
It is considered a searchable registry if it contains a
capability element with xsi:type="vg:Search".
If true, this registry attempts to collect all
resource records known to the IVOA.
A registry typically collects everything by
harvesting from all registries listed in the
IVOA Registry of Registries.
an authority identifier managed by the registry.
Typically, this means the AuthorityIDs that
originated (i.e. were first published by) this
registry. Currently, only one registry can lay
claim to an AuthorityID via this element at a
time.
an abstract capability that fixes the standardID to the
IVOA ID for the Registry standard.
See vr:Capability for documentation on inherited children.
The capabilities of the Registry Harvest implementation.
The largest number of records that the registry
search method will return. A value greater
than one implies that an OAI continuation token
will be provided when the limit is reached. A
value of zero or less indicates that there is
no explicit limit and thus, continuation tokens
are not supported.
The capabilities of the Registry Search implementation.
The largest number of records that the registry
search method will return. A value of zero or
less indicates that there is no explicit limit.
the level of support provided for searching
against metadata defined in a legal VOResource
extension schema.
A legal VOResource extension schema is one that
imports and extends the VOResource core schema
in compliance with the VOResource standard.
the name of an optional advanced search
protocol supported.
Only one optional protocol is currently allowed
(XQuery). It is assumed that the required
protocols (simple keyword search and ADQL) are
supported.
Only searches against the core VOResource metadata are
supported.
Searches against some VOResource extension metadata
are supported but not necessarily all that exist in
the registry.
Searches against all VOResource extension metadata
contained in the registry are supported.
the XQuery (http://www.w3.org/TR/xquery/) protocol as
defined in the VO Registry Interface standard.
a description of the standard OAI PMH interface using HTTP
(GET or POST) queries.
the accessURL child element is the base URL for the OAI
service as defined in section 3.1.1 of the OAI PMH
standard.
a description of the standard OAI PMH interface using a SOAP
Web Service interface.
the accessURL child element is the service port location URL
for the OAI SOAP Web Service.
a naming authority; an assertion of control over a
namespace represented by an authority identifier.
the organization that manages or owns this
authority.
In most cases, this will be the same as the
Publisher.
Currently See: http://www.ivoa.net/twiki/bin/view/IVOA/RegistryInterface
References
[WSDLv1.1] Christensen, E., Curbera, F., Meredith, G., & Weerawarana, S. 2001, HYPERLINK "http://www.w3.org/TR/wsdl/" Web Services Description Language v1.1, W3C Note 15 March 2001, HYPERLINK "http://www.w3.org/TR/wsdl/" http://www.w3.org/TR/wsdl/
[Hanisch 2004] Hanisch, R. (ed.) et al. 2004, HYPERLINK "http://www.ivoa.net/Documents/latest/RM.html" Resource Metadata for the Virtual Observatory, IVOA Recommendation, HYPERLINK "http://www.ivoa.net/Documents/latest/RM.html" http://www.ivoa.net/Documents/latest/RM.html
[Plante 2003] Plante, R., Greene, G., Hanisch, R., McGlynn, T., O'Mullane, W., & Williamson, R. 2003, in ASP Conf. Ser., Vol. 314 Astronomical Data Analysis Software and Systems XIII, eds. F. Ochsenbein, M. Allen, & D. Egret (San Francisco: ASP), 585, HYPERLINK "http://www.ivoa.net/Documents/latest/RM.html" http://www.adass.org/adass/proceedings/adass03/O7-1
[VOResource] Plante, R. et al. 2006, VOResource: an XML Encoding Schema for Resource Metadata, v1.00, IVOA Working Draft, HYPERLINK "http://www.ivoa.net/Documents/WD/ReR/VOResource-20060530.html" http://www.ivoa.net/Documents/WD/ReR/VOResource-20060530.html
[ADQL] Ohishi, M. et al. 2004, HYPERLINK "http://www.ivoa.net/internal/IVOA/IvoaVOQL/WD_ADQL-0.9.pdf" Astronomical Dataset Query Language, IVOA Working Draft (internal), HYPERLINK "http://www.ivoa.net/internal/IVOA/IvoaVOQL/WD_ADQL-0.9.pdf" http://www.ivoa.net/internal/IVOA/IvoaVOQL/WD_ADQL-0.9.pdf
[XPath] Clark, J. and DeRose, S. 2001, HYPERLINK "http://www.w3.org/TR/xpath/" XML Path Language (XPath) Version 1.0, W3C Recommendation 16 November 1999, HYPERLINK "http://www.w3.org/TR/xpath/" http://www.w3.org/TR/xpath/
[Schema] Fallside, D, and Walmsley, P. 2004, HYPERLINK "http://www.w3.org/TR/xmlschema-0/" XML Schema Part 0: Primer Second Edition, W3C Recommendation 28 October 2004, HYPERLINK "http://www.w3.org/TR/xmlschema-0/" http://www.w3.org/TR/xmlschema-0/
[OAI] HYPERLINK "http://www.openarchives.org/OAI/openarchivesprotocol.html" http://www.openarchives.org/OAI/openarchivesprotocol.html
PAGE
PAGE 1
Is this still true? We need to see the WSDL. I recommend that the first two share a common output that supports multiple records, and the 2nd two share a common output that allows only one record.
What is the format for this? How is this handled in the WSDL? This needs further explanation.
Break out?
If we make this token, normalization rules would apply automatitcally.
If we make this token, normalization rules would apply automatitcally.
If we make this token, normalization rules would apply automatitcally.
This standard should not mention the registry of registries apart from the context of a Note box. RofR is not a part of this spec. Should mention that the discovery of other registries is not covered in this document as well as how one harvests from other known registries to maintain a full listing of known records. Should describe requirements for support for unrecognized schemas.
" , - . 5 6 7 8 9 Q \ ] ^ _ ˺˺˺˺ߕ}sbP #h6 B*CJ OJ QJ ^J aJ ph !h6 5B*OJ QJ \^J ph H htfhR0 H h;fhq H hzʗ&h6 h6
h6 KH$ h6 CJ aJ h6 6B*]^J ph h6 B*^J ph !h6 6B*
CJ ]^J aJ ph Z 'h6 56B*
CJ \]^J aJ ph Z h6 B*OJ QJ ^J ph $j h6 B*OJ QJ U^J ph - 7 8 9 R ` 3 G ^ ) ( I kdL3 $$If 0 ^ ^6 3 4 a $If $If X &X [ 1 2 3 G H ųųq[q[A 2j3 h6 B*CJ OJ QJ U^J aJ ph *h6 0J 6B*CJ OJ QJ ^J aJ ph 3j h6 0J 6B*CJ OJ QJ U^J aJ ph ,j h6 B*CJ OJ QJ U^J aJ ph !h6 5B*OJ QJ \^J ph #h6 B*CJ OJ QJ ^J aJ ph B h6 hV;* B*CJ OJ QJ ^J aJ cH dh dh dh;fph 0H h;fhV;* B*CJ OJ QJ ^J aJ ph G y P a u $If $a$ $a$ * ^ ,
-
.
=
>
@
A
1 2 3 > ? A B ǭǓy_ 2j6 h6 B*CJ OJ QJ U^J aJ ph 2j5 h6 B*CJ OJ QJ U^J aJ ph 2j-5 h6 B*CJ OJ QJ U^J aJ ph 2jj4 h6 B*CJ OJ QJ U^J aJ ph #h6 B*CJ OJ QJ ^J aJ ph ,j h6 B*CJ OJ QJ U^J aJ ph h6 0J CJ OJ QJ ^J aJ ! # $ % 2 3 5 6 u v w ϿϭϭϿϭϭyϿϭϭ_Ͽϭϭ 2j9 h6 B*CJ OJ QJ U^J aJ ph 2j8 h6 B*CJ OJ QJ U^J aJ ph 2j%8 h6 B*CJ OJ QJ U^J aJ ph #h6 B*CJ OJ QJ ^J aJ ph h6 0J CJ OJ QJ ^J aJ ,j h6 B*CJ OJ QJ U^J aJ ph 2jl7 h6 B*CJ OJ QJ U^J aJ ph m w | ϿϦ~z~j~j~j~L7~z (H hhR1 B*OJ QJ ^J ph : h6 hR1 B*OJ QJ ^J cH dh dh dhph h6 6B*OJ QJ ^J ph h6 h6 B*OJ QJ ^J ph j
; h6 U#h6 B*CJ OJ QJ ^J aJ ph 0H h˗&h6 B*CJ OJ QJ ^J aJ ph h6 0J CJ OJ QJ ^J aJ ,j h6 B*CJ OJ QJ U^J aJ ph 2jV: h6 B*CJ OJ QJ U^J aJ ph C D P \ h u v y 涐hE9 h6 0J B*]ph E h6 h] B*^J cH cH cH dh˗&dhdh+FmH nH ph uN H h˗&h6 h] B*^J cH cH dh dh˗&dh+FmH nH ph u J H hqh2{ hu B*^J cH dh dh dhufmH nH ph u +H hufhu B*^J mH nH ph uh6 0J ^J "j; h6 B*U^J ph j h6 B*U^J ph h6 B*^J ph N O P a U V z { | ٹ굨}ucuQ "j= h6 B*U^J ph "j4= h6 B*U^J ph h6 0J ^J "j<