# Diff of /trunk/projects/registry/RegistryInterface/RegistryInterface.tex

revision 3048 by volute@g-vo.org, Mon Aug 24 08:16:31 2015 UTC revision 3049 by dower, Sat Aug 29 14:45:08 2015 UTC
# Line 769  Line 769
769
770  \label{sect:rofr}  \label{sect:rofr}
771
772  To facilitate discovery and automated harvesting of registries containing VOResource records, a registry serving as a master list of IVOA registries exists as part of the IVOA web infrastructure, hosted at \nolinkurl{http://rofr.ivoa.net/}. It is referred to as the Registry of Registries, or RofR. As the Registry of Registries is itself a registry, an OAI-PMH interface is provided which conforms to this document. The OAI-PMH interface is always available at \nolinkurl{http://rofr.ivoa.net/cgi-bin/oai.pl}.\todo{Do we want to put this here? It doesn't really change, I'm just always wary of hardcoded URLs in long-term documentation. --Theresa}  To facilitate discovery and automated harvesting of registries containing VOResource records, a registry serving as a master list of IVOA registries exists as part of the IVOA web infrastructure, hosted at \nolinkurl{http://rofr.ivoa.net/}. It is referred to as the Registry of Registries, or RofR. As the Registry of Registries is itself a registry, an OAI-PMH interface is provided which conforms to this document. The OAI-PMH interface is always available at \nolinkurl{http://rofr.ivoa.net/cgi-bin/oai.pl}.
773
774  The Registry of Registries includes the VOResource records directly representing each currently active registry of IVOA resources, be they fully searchable or providing only an OAI-PMH harvesting interface. These resources are of type \xmlel{vg:Registry} as defined in section \ref{sect:resext}. As a prerequisite of inclusion in the list, each registry has its standard interfaces and VOResource contents automatically validated against this document and the VOResource standard once; updates post-inclusion are not necessarily automatically validated. The Registry of Registries also contains the canonical VOResource descriptions of the most recent versions of VOResource standards and extensions themselves, which are of type \xmlel{vstd:Standard}.  The Registry of Registries includes the VOResource records directly representing each currently active registry of IVOA resources, be they fully searchable or providing only an OAI-PMH harvesting interface. These resources are of type \xmlel{vg:Registry} as defined in section \ref{sect:resext}. The Registry of Registries also contains the canonical VOResource descriptions of the most recent versions of VOResource standards and extensions themselves, which are of type \xmlel{vstd:Standard}.
775
776    \subsection{Inclusion in the Registry of Registries listing}
777    \label{sect:publishrofr}
778
779    To be considered an IVOA registry, the curator of a publishing registry containing VO resources must validate their registry's contents using the RofR web form at \nolinkurl{http://rofr.ivoa.net/regvalidate/regvalidate.html}. The automated validation process includes testing the registry's standard interfaces against this document and the OAI-PMH 2.0 standard, schema-validating each included resource against the VOResource standard, and checking the referential integrity of its Authority and Registry records.
780
781    Upon successful validation, the publishing registry will be automatically included in the RofR listing, both in the website and the RofR's standard interfaces.  After initial inclusion in the RofR listing, updates to the registry which are not re-run against the validation service are not necessarily automatically validated, and updates to the Registry record itself are not automatically reflected in the RofR contents.
782
783  \subsection{Harvesting the Registry of Registries}  \subsection{Harvesting the Registry of Registries}
784
# Line 779  Line 786
786
787  Given the Registry of Registries contains records for all other currently active and validated IVOA registries, a client wishing to harvest the contents of all registries should begin at the RofR. Fully searchable registries wishing to include records from the other IVOA registries count among these potential clients. To harvest the entire contents of IVOA registries, it is recommended to first harvest the Registry of Registries via its OAI-PMH interface.  Given the Registry of Registries contains records for all other currently active and validated IVOA registries, a client wishing to harvest the contents of all registries should begin at the RofR. Fully searchable registries wishing to include records from the other IVOA registries count among these potential clients. To harvest the entire contents of IVOA registries, it is recommended to first harvest the Registry of Registries via its OAI-PMH interface.
788
789  The next step in harvesting the entire distributed IVOA registry contents is to iterate over the \xmlel{accessURL} of each \xmlel{vg:Registry} record's \xmlel{vr:capability} of type \xmlel{vg:Harvest}, and use the url for each of those OAI-PMH interfaces to harvest the individual registries. This filtering of RofR contents can be done by adding the \texttt{set} parameter to an OAI query to the RofR: registries in the RofR comprise the supported set \texttt{ivo\_publishers}. Then when harvesting each registry in turn, to avoid harvesting duplicate records from the fully searchable registries, it is recommended to add the \texttt{set} parameter to that OAI query: records specifically published by a registry which also has a search interface comprise that registry's supported set \texttt{ivo\_managed}.  The next step in harvesting the entire distributed IVOA registry contents is to iterate over the \xmlel{accessURL} of each \xmlel{vg:Registry} record's \xmlel{vr:capability} of type \xmlel{vg:Harvest}, and use the url for each of those OAI-PMH interfaces to harvest the individual registries. This filtering of RofR contents can be done by adding the \texttt{set} parameter to an OAI query to the RofR: registries in the RofR comprise the supported set \texttt{ivo\_publishers}. The following query to the RofR OAI-PMH interface will return only the records for the publishing registries in the RofR: \nolinkurl{http://rofr.ivoa.net/cgi-bin/oai.pl?verb=ListRecords&metadataPrefix=ivo_vor&set=ivo_publishers}
790
791
792    For the next step of harvesting each registry in turn, to avoid harvesting duplicate records from the fully searchable registries, it is recommended to add the \texttt{set} parameter to the OAI query for each individual publishing registry: records specifically published by a registry which also has a search interface comprise that registry's supported set \texttt{ivo\_managed}.
793
794
795
\todo{example queries here? -- Theresa}
796
797  \section{Searching the Registry}  \section{Searching the Registry}
798
# Line 842  Line 853
853
854  \begin{itemize}  \begin{itemize}
855
856  \item Added requirement for OAI-PMH interface to support seconds granularity, optional in the OAI-PMH 2.0 standard itself. {}  \item Added requirement for OAI-PMH interface of IVOA Registries to support seconds granularity, optional in the OAI-PMH 2.0 standard itself. {}
857
858  \item Removed requirement for VOResource version number changes to force an update of this document. {}  \item Removed requirement for version number changes to the VOResource standard to force an update of this document. {}
859
860  \item Removed the entire section 2, specifically the SOAP-based services  \item Removed the entire section 2, specifically the SOAP-based services
861  based on ADQL 1.0'' and XQuery.{}  based on ADQL 1.0'' and XQuery.{}

Legend:
 Removed from v.3048 changed lines Added in v.3049