==================== VODataService: A VOResource Schema Extension for Describing Collections and Services ==================== Official bibliographic entry for published version :cite:p:`2021ivoa.spec.1102D`. :Status: VODataService 1.3 WD 2024-11-13 .. role:: raw-latex(raw) :format: latex .. .. _`VODataService:acknowledgments`: Acknowledgments =============== Versions 1.0 and 1.1 of this document have been developed with support from the National Science Foundation’s Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), from the European Commission’s (EC) Sixth Framework Programme via the Optical Infrared Coordination Network (OPTICON), and from EC’s Seventh Framework Programme via its eInfrastructure Science Repositories initiative. Version 1.2 of this document was developed in part with support from the German federal ministry for research and education’s e-inf-astro project (BMBF FKZ 05A17VH2). .. _`VODataService:conformance-related-definitions`: 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 RFC2119 :cite:p:`std:RFC2119`. 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 `International Virtual Observatory Alliance (IVOA) `__ is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. .. _`VODataService:syntax-notation-using-xml-schema`: Syntax Notation Using XML Schema ================================ The eXtensible Markup Language, or XML, is a document syntax for marking textual information with named tags and is defined by :cite:t:`std:XML`. The set of XML tag names and the syntax rules for their use is referred to as the document schema. One way to formally define a schema for XML documents is using the W3C standard known as XML Schema :cite:p:`std:XSD`. The XML Schemas of VODataService as well as VOResource and its other extensions are available from the IVOA schema repository [1]_ at any time. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity. Where the content of the pieces of schema embedded in this text diverges from the schema document in the IVOA document repository, the version in the schema repository is authoritative. References to specific elements and types defined in the VOResource schema include the namespace prefix :raw-latex:`\xmlel{vr}` as in :raw-latex:`\xmlel{vr:Resource}` (a type defined in the VOResource schema). .. _`VODataService:introduction`: 1 Introduction ============== The VOResource standard :cite:p:`2018ivoa.spec.0625P` provides a means of encoding resource metadata as defined by DataCite :cite:p:`std:DataCite40` and the VO-specific IVOA Resource Metadata :cite:p:`2007ivoa.spec.0302H` in XML. VOResource uses XML Schema :cite:p:`std:XSD` to define most of the XML syntax rules (while a few of the syntax rules are outside the scope of Schema). VOResource also describes mechanisms for creating extensions to the core VOResource metadata. This allows for the standardization of new metadata for describing specialized kinds of resources in a modular way without deprecating the core schema or other extensions. This document defines one such extension referred to as VODataService. It provides types to define data services, their underlying tabular structures, their service interfaces, and the location of the data served in space, time, and energy. The remainder of the document introduces the use cases addressed by this specification, then provides a high-level overview over the concepts and usage patterns in sect. :ref:`VODataService:sect:model` and finally discusses the concrete classes in sect. :ref:`VODataService:sect:metadata`. .. _`VODataService:the-role-in-the-ivoa-architecture`: 1.1 The Role in the IVOA Architecture ------------------------------------- .. container:: float :name: VODataService:fig:archdiag .. raw:: latex \centering |image1| Fig. :ref:`VODataService:fig:archdiag` shows the role VODataService plays within the IVOA Architecture :cite:p:`2021ivoa.spec.1101D`. VODataService directly depends on the following other VO standards (unless specified otherwise, the dependency is on the major version of the cited standard rather than on the exact version): VOResource, v1.1 :cite:p:`2018ivoa.spec.0625P` VOResource gives the fundamental types and structures extended here. STC, v1.33 :cite:p:`2007ivoa.spec.1030R` The deprecated mechanism for declaring coverage through STCResourceProfile still uses concepts from version 1 of the IVOA data model for Space-Time Coordinates. The updated mechanism has no such dependence any more. VODataService is closely related to the following other VO standards: VOSI, v1.1 :cite:p:`2017ivoa.spec.0524G` VODataService defines the schema for the responses on the table metadata endpoint. It also defines the ParamHTTP interface type currently used in the capabilities of most standard protocols. RegTAP, v1.1 :cite:p:`2019ivoa.spec.1011D` RegTAP maps the concepts defined here into a relational structure. In that sense it is the user interface to what is specified here. RegTAP will need an update to support the space-time constraints added here. MOC, v2.0 :cite:p:`2019ivoa.spec.1007F` Multi-Order coverage maps are used by VODataService to communicate spatial coverage. .. _`VODataService:purpose`: 1.2 Purpose ----------- The purpose of this extension is to define common XML Schema types – in particular new resource types – that are useful for describing data collections and services that access data. One aspect of such a description is the resource’s *coverage*: the parts of the sky with which the data is associated and the time and frequency ranges that were observed or modeled to create the data. Another important aspect is the detailed metadata for tables underlying the resource, including names, types, UCDs :cite:p:`2023ivoa.spec.0125C`, units, and textual descriptions for the columns making them up. Resource records using VODataService types are commonly used to register services that support standard IVOA data access layer protocols such as Simple Image Access :cite:p:`2015ivoa.spec.1223D` and Simple Cone Search :doc:`ref <../ConeSearch/ConeSearch>`. As of October 2018, there are more than 20000 resources of type :raw-latex:`\xmlel{vs:CatalogService}` in the VO Registry. While other VOResource extensions define the protocol-specific metadata (encapsulated as a standard *capability* from VOResource), the general service resource description shares the common data concepts such as coverage and tabular data. Note, however, that a service described using the VODataService schema need not support any standard protocols. With the VODataService extension schema plus the core VOResource schema, it is possible to describe a custom service interface that accesses data. As a legal extension of VOResource, the use of VODataService is subject to the rules and recommendations for XML :cite:p:`std:XML`, XML Schema :cite:p:`std:XSD`, and VOResource itself. .. _`VODataService:additional-use-cases-for-version-1.2`: 1.3 Additional Use Cases for Version 1.2 ---------------------------------------- In the following, we collect use cases that guided the development of VODataService to its version 1.2. We do not formally derive requirements from them but briefly note which new features enable or facilitate the specific use case. A few of the changes in version 1.2 are necessary for consistency with other standards such as TAP (extendedType interpretation, requirement to use ADQL delimited identifier literals in names where appropriate) or VOTable (arraysize interpretation). These were obviously not guided by specific use cases. .. _`VODataService:what-services-have-data-for-the-crab-nebula-covering-the-hboldsymbolalpha-line-taken-in-the-second-half-of-2015`: What services have data for the Crab nebula covering the H\ :math:`\boldsymbol\alpha` line taken in the second half of 2015? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In version 1.1, this use case would have been covered by the :raw-latex:`\xmlel{stc:STCResourceProfile}` type, which, however, was never properly standardised or widely adopted. In the current version, the :raw-latex:`\xmlel{spatial}`, :raw-latex:`\xmlel{spectral}`, and :raw-latex:`\xmlel{temporal}` children of :raw-latex:`\xmlel{coverage}` enable discovery by coverage on the various axes. It is worth noting that the spectral coverage is for the solar system barycenter, so this use case does *not* immediately enable the discovery of, say, H\ :math:`\alpha` images of remote galaxies. Redshift correction has to be applied by the client based on knowledge about the object(s) investigated. At the time of writing, coverage also does not directly address non-celestial reference systems, although in particular planetary surfaces are considered in scope, and the coverage element’s :raw-latex:`\xmlel{@frame}` attribute is defined to ensure non-ICRS coverages can safely be declared as the need arises. .. _`VODataService:find-all-obscore-services-publishing-data-taken-at-the-telescope-x.`: Find all ObsCore services publishing data taken at the Telescope X. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This use case could be satisfied in version 1.1 through the use of :raw-latex:`\xmlel{vs:DataCollection}` records and relationships to the respective TAP services. However, this scheme led to error-prone query patterns, and few such data collections were actually registered; see the IVOA Note on discovering data collections :cite:p:`2019ivoa.spec.0520D` for details. To better support the scheme proposed there, version 1.2 adds the :raw-latex:`\xmlel{vs:DataResource}` and :raw-latex:`\xmlel{vs:CatalogResource}` types that identify a resource as data-like but permits the addition of various capabilities to the record (which :raw-latex:`\xmlel{vs:DataCollection}` did not). An analogous use case would be “Find all TAP services publishing tables from Gaia DR2”. .. _`VODataService:find-a-large-scale-survey-of-sources-between-20-and-40-ghz.`: Find a large-scale survey of sources between 20 and 40 GHz. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While the spectral constraint is easily satisfied by the new coverage children, the “large-scale” part is much harder to operationalize. However, the plain table size often is a useful proxy in such discovery problems. The new :raw-latex:`\xmlel{nrows}` child of :raw-latex:`\xmlel{vs:Table}` communicates it. .. _`VODataService:additional-use-case-for-version-1.3`: 1.4 Additional Use Case for Version 1.3 --------------------------------------- .. _`VODataService:find-services-serving-time-series.`: Find services serving time series. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the previous registry model, searches for a certain kind of data product were linked to searches for certain kinds of services. For instance, clients looking for spectra were querying the registry for SSAP services. This model was severely outdated after ObsTAP services offered – say – spectra, too. Also SSAP services increasingly served time series as well. Thus, when the IVOA product type vocabulary [2]_ became available, its adoption by VODataService was natural. It is now used to let data collections and services explicitly declare which sort of data they contain or serve. .. _`VODataService:additional-use-cases-for-future-versions`: 1.5 Additional Use Cases for Future Versions -------------------------------------------- The following use cases were originally envisioned for VODataService 1.2, but were postponed because building multiply implemented solutions for them seemed likely to unnecessarily delay the standardisation of, in particular, the STC part of the present document. They will likely be addressed by future versions of VODataService. .. _`VODataService:find-a-resource-that-has-sources-in-m51-down-to-27-mag-in-v.`: Find a resource that has sources in M51 down to 27 mag in V. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The constraint about finding a resource that has V magnitudes for M51 is expressible using spatial coverage and the column’s UCDs. To express something like “down to :math:`27^{\rm m}`” one would at least need VOTable-style :raw-latex:`\xmlel{VALUES}` children for columns; however, metadata sufficient to address the next use case would certainly be sufficient here as well. .. _`VODataService:plan-a-cross-service-query.`: Plan a cross-service query. ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Systems like OGSA-DAI :cite:p:`2011ASPC..442..579H` perform orchestration of SQL-like queries between multiple services automatically, in particular cross-service JOINs. In order to work efficiently, such services need column statistics like histograms and the percentage of NULL values. .. _`VODataService:facilitate-discovery-of-full-dali-services.`: Facilitate discovery of full DALI services. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The issue here is that DALI forsees synchronous and asynchronous endpoints as the standard case for many protocols – it already is standard for TAP. Also, several auxiliary endpoints (mostly defined in VOSI) are declared as separate capabilities and need to be matched with the functional endpoints. This matching is becoming a problem when multiple authentication schemes or mirror sites necessitate multiple sync/async pairs. A longer treatment of this problem has been published while this document was in WD :cite:p:`note:caproles`, but at the time of writing the process of finding consensus has just begun, so again a normative solution has to be deferred to a later version of this standard. .. _`VODataService:sect:model`: 2 The VODataService Data Model ============================== The VODataService extension in general enables the description of two types of resources: Services that access data on the one side, and data being accessed through services on the other. For simple services just publishing a simple resource – still a fairly common pattern – the metadata of the data published can be folded into the service record. Here is an example of such a record (abbreviated for the purposes of illustration) that describes a service from the NASA Extragalactic Database (NED) that provides measured redshifts for a given object. .. code:: xml :number-lines: The NASA/IPAC Extragalactic Database NED_redshift ivo://ned.ipac/Redshift_By_Object_Name The NASA/IPAC Extragalactic Database Olga Pevunova contact@datacenter.edu redshift galaxies NED is built around a master list of extragalactic objects for which cross-identifications of names have been established, accurate positions and redshifts entered to the extent possible, and some basic data collected. This service will return recorded redshifts for a given object. http://nedwww.ipac.caltech.edu/help/data_help.html#zdat BasicData Research http://nedwww.ipac.caltech.edu/cgi-bin/nph-datasearch?search_type=Redshifts& GET application/xml+votable objname Name of object string of Output format parameter, must be "xml_main" for VOTable output. string 0/0-11 33282 100000 4e-28 3e-23 2.4e-19 5e-19 Radio Optical default default No. A sequential data-point number applicable to this list only. meta.number int Name in Publication The object's name in NED's standard format, of the object to which the data apply. meta.id char Published Velocity The radial velocity , derived from derived from the shift of some spectral feature, in km/sec km/sec spect.dopplerVeloc int
This example illustrates some of the features of the VODataService extension: #. The specific type of resource indicated by the value of the :raw-latex:`\xmlel{xsi:type}` attribute; in this case :raw-latex:`\xmlel{vs:CatalogService}` indicates that this is describing a service that accesses tabular data (line 1). #. The extra namespace declaration for VODataService metadata with the canonical prefix (line 5). #. The location of the VOResource-related schema documents used by this description (line 7ff.) #. The core VOResource metadata (line 12ff.) #. An interface described by the VODataService type :raw-latex:`\xmlel{vs:ParamHTTP}`; this type can indicate input arguments the service supports (line 40ff.) #. A description of the coverage, including quantitative coverage plus waveband keywords (line 62ff.) #. A description of the table that is returned by the service (line 73ff.) .. _`VODataService:the-schema-namespace-and-location`: 2.1 The Schema Namespace and Location ------------------------------------- The namespace associated with VODataService extensions is .. math:: \mbox{\texttt{http://www.ivoa.net/xml/VODataService/v1.1}}. As required by the IVOA schema versioning policies :cite:p:`2018ivoa.spec.0529H`, this namespace is identical to the one associated with version 1.1 of this document. It is regrettable that a misleading minor version is present in the namespace URI, but dropping it would break existing software for creating and processing VODataService instance documents. Hence, the namespace URI ending in ``1.1`` is also used for schema versions 1.2, 1.3, and so forth. Resolving the VODataService namespace URI will redirect to a schema document having the actual version number (for the schema associated with this document version, this will end in VODataService-1.3.xsd). Following the schema versioning policies, the minor version will be declared in the :raw-latex:`\xmlel{version}` attribute of this file’s root element. This information should not in general be used in production software; all versions with the above schema URI are compatible with each other in the sense defined in the IVOA schema versioning policies. Authors of VOResource instance documents may choose to provide a location for the VOResource XML Schema document and its extensions using the :raw-latex:`\xmlel{xsi:schema\-Location}` attribute. While authors are free to choose a location (as long as it resolves to the schema document), this specification recommends using the VODataService namespace URI as its location URL (as illustrated in the example above), as in :: xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1 http://www.ivoa.net/xml/VODataService/v1.1" The canonical prefix for VODataService is :raw-latex:`\xmlel{vs}`; this means, in particular, that in non-XML contexts (e.g., relational mappings like RegTAP) the VODataService types *must* be qualified with vs:. As recommended by the VOResource standard, the VODataService schema sets :raw-latex:`\xmlel{element\-Form\-Default}` to *unqualified*. This means that element names defined in this schema may not be used with a namespace prefix. The only place the namespace prefix must be used is the type names given as the value of an :raw-latex:`\xmlel{xsi:type}` attribute. .. _`VODataService:sect:summ`: 2.2 Summary of Metadata Concepts -------------------------------- VODataService defines several resource types and some auxiliary classes necessary to describe resources of these new types. .. _`VODataService:auxiliary-classes`: 2.2.1 Auxiliary Classes ~~~~~~~~~~~~~~~~~~~~~~~ The VODataService type :raw-latex:`\xmlel{vs:Coverage}` allows the declaration of the physical coverage of a resource on the sky (or on spherical bodies), in time, and in the energy of the messenger particle. In addition, the element should contain a rough indication of the messenger type (e.g., “Optical”), and it can contain a link to a footprint endpoint and an indication of the spatial resolution within a service. VODataService has several classes for the declaration of the tabular structure underlying a service; this can be the tables in a TAP-accessible resource, or it can relate to the data structure returned by the service. This metadata is held in :raw-latex:`\xmlel{vs:TableSet}`-typed elements consisting of one or more (possibly anonymous) :raw-latex:`\xmlel{vs:TableSchema}` instances. These have some very basic metadata (name, title, description, utype) and otherwise contain :raw-latex:`\xmlel{vs:Table}` instances. These in turn have simple metadata, but mainly give column metadata (including UCDs and units) in :raw-latex:`\xmlel{vs:TableParam}`-typed children. These are the basis for enabling discovery queries like “find all resources having redshifts and far infrared fluxes”. Note that table and schema metadata is deliberately shallow. If the main resource metadata is not enough to discover the table – as is fairly typical when a TAP service contains multiple unrelated tables –, data providers should define separate records for them as described in sect. :ref:`VODataService:sect:discoverdata`. VODataService further defines a specialized interface type called :raw-latex:`\xmlel{vs:ParamHTTP}`. It inherits from :raw-latex:`\xmlel{vr:Interface}`. This type is used to describe straightforward HTTP interfaces directly operating on arguments encoded as *name=value* pairs. Such interface declarations can enumerate a service’s input arguments, which enables clients to generate simple user interfaces from VOSI capabilities responses. To be able to express the types of table columns and service arguments alike, VODataService defines several type systems. All of these are basically just enumerations of type names, possibly with some additional metadata like VOTable-style array sizes. In new resource records, only :raw-latex:`\xmlel{vs:SimpleDataType}` (for ParamHTTP parameters on non-DALI interfaces) and :raw-latex:`\xmlel{vs:VOTableType}` (for table columns) should be used. .. _`VODataService:sect:rescls`: 2.2.2 VODataService Resource Classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: float :name: VODataService:fig:rescls :raw-latex:`\tikzfigure{resclasses}` While no common VO service discovery pattern relies on the XSD type of the resource, [3]_ resource record authors should nevertheless choose appropriate types for their resources. At the very least, this helps Registry maintenance. VODataService provides four major resource classes; their derivation tree is shown in Fig. :ref:`VODataService:fig:rescls`. The vertical distinction in that figure reflects whether a resource has an associated tableset (DataX vs. CatalogX); you would typically use the DataX types when a resource does not naturally admit a relational structure. The classical example for this would be a collection of files on an FTP server. CatalogX, on the other hand, has an associated tableset. That does not mean that it is limited to what is conventionally thought of as a “catalogue”, i.e., a table of data on astronomical objects. On the contrary, CatalogX should also be used for collections of images, spectra, time series, etc, as long as their metadata is sufficiently structured. That a data collection is published through the standard IVOA discovery protocols (ObsCore, SIAP, SSAP) certainly is a strong indication that this requirement is satisfied. The horizontal distinction (XResource vs. XService) is somewhat more subtle and will be discussed in sect. :ref:`VODataService:sect:discoverdata`. Two further resource classes defined VODataService 1.1, :raw-latex:`\xmlel{vs:DataCollection}` and :raw-latex:`\xmlel{vs:StandardSTC}`, are deprecated in version 1.2. Resource record authors are requested to migrate or discard resource records using these deprecated types. If all such records have disappeared from the VO by version 1.4 of this specification, their type declarations may be removed from the schema. .. _`VODataService:sect:discoverdata`: 2.2.3 Discovering Data Within Other Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The content models of CatalogResource and CatalogService are identical. To understand why the two classes are present nevertheless, a short historical excursion is in order. A full treatment of this is found in the IVOA Endorsed Note on discovering data collections within services :cite:p:`2019ivoa.spec.0520D`, hereafter referred to as DDC. In the early VO, there was almost throughout a :math:`1:1` relationship between data collections and services. For instance, a catalogue of variable stars had a single cone search interface, and the spectra from a given spectrograph had a single SSA interface. This is the model reflected by the CatalogService class, and it was, by and large, sufficient for IVOA’s “simple” protocols (SCS, SIAP, SSAP, SLAP), although even these protocols have facilities for multi-collection services. With the advent of services very naturally publishing what clearly are multiple different resources – TAP, with its multiple tables, and Obscore building on top of it are the prime examples –, this model proved inadequate; furthermore, publishers increasingly offered data through multiple interfaces: An object catalogue now quite typically is published as both a cone search service and within a TAP service; an image collection could have both SIAP and Obscore interfaces. Thus, the relationship between data collections and services gradually became :math:`n:m`. With this came the realisation that two classes of discovery need to be supported; for all-VO queries, validation, and the like, an enumeration of all *services* (“give me all SSAP services…”) needs to be performed. For data discovery (“Where are images from instrument X of object Y?”), a selection over all *collections* needs to be made. The solution eventually adopted for these problems is auxiliary capabilities as introduced in DDC. They provide stubs merely identifying an access protocol – at the same time identifying the capability as an auxiliary one – and access URLs, delegating all further service metadata to a separate record, linked to the original resource through an *isServedBy* relationship. Thus, CatalogService-typed records should be used - when a service serves a single data collection, in which case the metadata on the record describes the data collection (e.g., “These are observations of…”). - for a service serving multiple data collections, in which case the metadata on the record describes the service (e.g., “This is the TAP service of…”’). CatalogResource-typed records should be used for resources that only have auxiliary capabilities. Here is a sketch of a resource record of a table within a TAP service:: .. code:: xml Sample Table ivo://example/sample ... ... IsServedBy Example TAP service http://example.org/svcs/tap ... someschema someschema.sample... ...
A complete example can be found in DDC. Note that it is legal to add auxiliary capabilities to CatalogService records as well. The classical example could be a cone search service serving a single catalogue that is also queriable within a larger TAP service. Analogous considerations would apply to DataResource versus DataService, although at this point no obvious use cases have been identified; DataResource was included mainly for symmetry with CatalogResource. .. _`VODataService:sect:metadata`: 3 The VODataService Metadata ============================ This section enumerates the types and elements defined in the VODataService extension schema and describes their meaning. .. _`VODataService:sect:resext`: 3.1 VODataService Resource Types -------------------------------- Sect. :ref:`VODataService:sect:rescls` already gave a general overview of the systematics of the following resource types. .. _`VODataService:sect:DataResource`: 3.1.1 DataResource ~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:DataResource}` resource type is used to describe a resource containing generic astronomical data without a dominating tabular structure. An example might be a largely unstructured archive of various observations. Resources that have structured metadata tables (like most VO services) or are tabular in nature (like usual astronomical catalogues) should use :raw-latex:`\xmlel{vs:CatalogResource}`. The type is derived from :raw-latex:`\xmlel{vr:Service}`, which means that instances can have capabilities. For :raw-latex:`\xmlel{vs:DataResource}`, only auxiliary capabilities (e.g., DataServices serving multiple DataResources) or plain capabilities with :raw-latex:`\xmlel{vr:WebBrowser}` interfaces should be given. Resources with a primary access mode dedicated to the resource’s data content should use :raw-latex:`\xmlel{vs:DataService}`-typed resources. In addition to :raw-latex:`\xmlel{vr:Service}`’s content, DataResource adds elements for declaring the observing facilities and/or instruments used to obtain the data, and it supports the declaration of the physical coverage of data via the :raw-latex:`\xmlel{coverage}` element. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Documentation} \noindent{\small A resource publishing astronomical data. \par} \noindent{\small This resource type should only be used if the resource has no common underlying tabular schema (e.g., an inhomogeneous archive). Use CatalogResource otherwise. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:DataResource} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{facility}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] The observatory or facility used to collect the data contained or managed by this resource. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{instrument}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] The instrument used to collect the data contain or managed by a resource. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{coverage}] \begin{description} \item[Type] composite: \xmlel{vs:Coverage} \item[Meaning] Extent of the content of the resource over space, time, and frequency. \item[Occurrence] optional \end{description} \item[Element \xmlel{productTypeServed}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] Collections of data products (e.g., images or spectra) or services serving them define the type of products they contain or serve here. This information is intended to enable global product discovery. Hence, services failing to define their product type(s) may be skipped by clients in global discovery. Product type names must be taken from the IVOA vocabulary http://www.ivoa.net/rdf/product-type. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VODataService:dataservice`: 3.1.2 DataService ~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:DataService}` resource type has the same content model as :raw-latex:`\xmlel{vs:DataResource}`. It should be used instead of :raw-latex:`\xmlel{vs:DataResource}` when the resource’s capabilities give access to (essentially) only the resource’s data, as for instance “ftp service for the XY instrument”, or for a service giving access to multiple resources; in this latter case, the resource-level metadata should pertain to the service itself rather than any specific data collection served by it. As with :raw-latex:`\xmlel{vs:CatalogResource}`, instances SHOULD declare the metadata of the table(s) underlying the service or delivered by it in a :raw-latex:`\xmlel{tableset}` element. Whenever the service operates on clearly definable tabular data, the resource should use the :raw-latex:`\xmlel{vs:CatalogService}` resource type in preference to :raw-latex:`\xmlel{vs:DataService}`, and that tabular structure should be given in a table set. DataService’s content model is exactly the one of :raw-latex:`\xmlel{vs:DataResource}`; please refer to sect. :ref:`VODataService:sect:DataResource` for the motivation of this duplication. .. _`VODataService:sect:CatalogResource`: 3.1.3 CatalogResource ~~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:CatalogResource}` resource type is used to describe a resource containing astronomical data or metadata in a set of one or more tables. It extends :raw-latex:`\xmlel{vs:DataResource}` and thus has metadata on coverage as well as the facilities and instruments that produced the resource. Additionally, :raw-latex:`\xmlel{vs:CatalogResource}` instances SHOULD declare of the metadata of the table(s) making up the data :raw-latex:`\xmlel{tableset}` element. As with :raw-latex:`\xmlel{vs:DataResource}`, this type should only be used if all capabilities declared in the resource are either auxiliary or nonstandard. This is typically the case for catalogues or data collections within larger TAP, ObsTAP, or perhaps SIAP services. When a service only publishes a single resource, use the :raw-latex:`\xmlel{vs:CatalogService}` type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Documentation} \noindent{\small A resource giving astronomical data in tabular form. \par} \noindent{\small While this includes classical astronomical catalogues, this resource is also appropriate for collections of observations or simulation results provided their metadata are available in a sufficiently structured form (e.g., Obscore, SSAP, etc). \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:CatalogResource} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{tableset}] \begin{description} \item[Type] composite: \xmlel{vs:TableSet} \item[Meaning] A description of the tables that are accessible through this service. \item[Occurrence] optional \item[Comment] Each schema name must be unique within a tableset. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VODataService:catalogservice`: 3.1.4 CatalogService ~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:CatalogService}` resource type is used to describe a service publishing astronomical data or metadata based on tabular representations. Its relationship to :raw-latex:`\xmlel{vs:CatalogResource}` is as between :raw-latex:`\xmlel{vs:DataResource}` and :raw-latex:`\xmlel{vs:DataService}`: Use :raw-latex:`\xmlel{vs:CatalogService}` when either the resource’s capabilities are exclusive to the resource described by the resource-level metadata (“SSAP service for the XY instrument”) or if the service publishes multiple other CatalogResources; in that latter case, again, the resource-level metadata should not refer to any specific data collection contained. This is the type that should be used for one-resource VO services. CatalogService’s content model is exactly the one of :raw-latex:`\xmlel{vs:CatalogResource}`; please refer to sect. :ref:`VODataService:sect:CatalogResource` for the motivation of this duplication. .. _`VODataService:sect:datacollection`: 3.1.5 DataCollection ~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:DataCollection}` type is deprecated and should no longer be used in new resource records. It was used in version 1.1 to define simple collections of data, much like :raw-latex:`\xmlel{vs:CatalogResource}` in the current version. It did not admit capabilities, though, and since the addition of capabilities would essentially have created a CatalogService clone with a different child sequence, it was decided to abandon rather than repair it. Existing :raw-latex:`\xmlel{vs:DataCollection}`-typed records should be migrated to records of type :raw-latex:`\xmlel{vs:DataResource}` or :raw-latex:`\xmlel{vs:CatalogResource}` as appropriate. If :raw-latex:`\xmlel{accessURL}` children are present in the :raw-latex:`\xmlel{vs:DataCollection}`s, they can be replaced with a plain capability with a :raw-latex:`\xmlel{vr:WebBrowser}`-typed interface. This type may be removed from the schema when all resource records using it have vanished from the VO Registry. .. _`VODataService:standardstc`: 3.1.6 StandardSTC ~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:StandardSTC}` type is deprecated and should no longer be used in new resource records. Since the XML serialisation of the STC 1 data model was never promoted to an IVOA recommendation, there also is no properly standardised way of creating such records. Since no such records ever existed in the Registry, this type will probably be removed from the schema in version 1.4 of this specification. .. _`VODataService:sect:cover`: 3.2 Coverage in Space, Time, and Spectrum ----------------------------------------- The :raw-latex:`\xmlel{vs:Coverage}` type summarily describes how the data served is distributed on the sky, in energy, and in time. In addition, there is the :raw-latex:`\xmlel{waveband}` element that originally contained a qualitative indication of the location of the resource’s coverage on the electromagnetic spectrum. As more resources cover non-elec:raw-latex:`\-`tromagnetic messengers, the element’s meaning has somewhat shifted, and it now admits values from an extendable vocabulary of messengers [4]_ that, for instance, includes Neutrinos. Historically, the quantitative footprints were expected to be given in the element of type :raw-latex:`\xmlel{stc:STCResourceProfile}` [5]_. As discussed in :cite:t:`note:regstc`, this expectation turned out to be erroneous, and the underlying standard, STC-X :cite:p:`note:stcx`, never proceeded to become a recommendation. Hence, this version of VODataService deprecates the use of :raw-latex:`\xmlel{STCResourceProfile}`. Instead, resource record authors are strongly encouraged to provide coverage information in the :raw-latex:`\xmlel{spatial}`, :raw-latex:`\xmlel{spectral}`, and :raw-latex:`\xmlel{temporal}` children of :raw-latex:`\xmlel{coverage}`. Spatial coverage is conveyed as a MOC. To enable easy embedding into resource records written in VOResource (i.e., XML), VODataService uses the string serialisation defined in section 2.3.2 of :cite:t:`2019ivoa.spec.1007F`. By default, the MOCs are to be interpreted in the ICRS. Future extensions to non-celestial frames (e.g., on planet surfaces) will use the :raw-latex:`\xmlel{frame}` attribute. However, the only celestial reference system allowed is ICRS. If a resource’s native coordinates are given for another frame (e.g., Galactic or FK4 for some equinox), it is the resource record author’s responsibility to convert the spatial coverage into the ICRS. An important characteristic of MOCs is the order of the smallest scale (the “MOC resolution”). Higher orders yield more faithful representations of the actual coverage, but also lead to a possibly significant increase of the size of the serialized MOC. We suggest a “typical resolution” of the Registry of about a degree (i.e., MOC order 6), but resources are free to choose a higher maximum orders if appropriate and the resource record size remains reasonable. Resources that need to communicate high-resolution spatial coverage, perhaps for some non-discovery use case, can use the :raw-latex:`\xmlel{footprint}` element with its :raw-latex:`\xmlel{ivo-id}` attribute set to ``ivo://ivoa.net/std/moc`` to declare a URL giving a footprint in one of the approved MOC serialisations and of arbitrary level and size. Time and spectral coverage are modeled as unions of simple intervals over real numbers; the serialisation here is a space-separated pair of floating point numbers as governed by the DALI *interval* xtype. Times are given in Barycentric Dynamical Time (TDB) at the solar system barycenter. They must be specified as Modified Julian Dates. Since discovery use cases in which high-precision times are required are not forseen, resource record authors are encouraged to pad their actual temporal coverage such that differences in time scales (of the order of 10s of seconds) or reference positions (of the order of minutes between ground-based observatories and the barycenter) do not matter. In other words, the temporal resolution of the Registry at this point should be assumed to be of order 10 minutes. Deviating from common VO practice (which currently fairly consistently uses wavelengths of electromagnetic waves in vacuum), spectral limits are given in Joules of messenger energy. This is intended to allow seamless integration of non-elec:raw-latex:`\-`tromagnetic messengers. The reference position for the spectral axis is the solar system barycenter. Again, discovery use cases on a level where the difference between reference frames of ground-based observatories versus the solar system barycenter matters are not forseen, and resource record authors are advised to pad their intervals on that level. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:Coverage} Type Schema Documentation} \noindent{\small A description of how a resource's contents or behavior maps to the sky, to time, and to frequency space, including coverage and resolution. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:Coverage} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Coverage} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{stc:STCResourceProfile}] An STC 1.0 description of the location of the resource's data on the sky, in time, and in frequency space, including resolution. This is deprecated in favour of the separate spatial, temporal, and spectral elements. This element is imported from another schema. See there for details.\item[Element \xmlel{spatial}] \begin{description} \item[Type] a string with optional attributes \item[Meaning] An ASCII-serialized MOC defining the spatial coverage of the resource. \item[Occurrence] optional \item[Comment] The MOC is to be understood in the ICRS reference frame unless a frame attribute is given. Resources should give the coverage at least to order 6 (a resolution of about one degree). The order should be chosen so as to keep the resulting MOC smaller than a few dozens of kB. If desired, a more precise MOC can be provided on a dedicated endpoint declared in the footprint element. \end{description} \item[Element \xmlel{temporal}] \begin{description} \item[Type] string of the form: \emph{[+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)? [+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)?} \item[Meaning] A pair of lower, upper limits of a time interval for which the resource offers data. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This is written as for VOTable tabledata (i.e., whitespace-separated C-style floating point literals), as in “47847.2 51370.2”. The limits must be given as MJD. While they are not intended to be precise, they are to be understood in TDB for the solar system barycenter. The total coverage of the resource is the union of all such intervals. \end{description} \item[Element \xmlel{spectral}] \begin{description} \item[Type] string of the form: \emph{[+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)? [+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)?} \item[Meaning] A pair of lower, upper limits of a spectral interval for which the resource offers data. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This is written as for VOTable tabledata (i.e., whitespace-separated C-style floating point literals). The limits must be given in Joules of particle energies. While the limits are not intended to be precise, they are to be understood for the solar system barycenter. \item[Comment] For instance, the Johnson V waveband (480 .. 730 nm) would be specified as “2.72e-19 4.14e-19” \end{description} \item[Element \xmlel{footprint}] \begin{description} \item[Type] a URI with optional attributes \item[Meaning] A reference to a footprint service for retrieving precise and up-to-date description of coverage. \item[Occurrence] optional \item[Comment] The ivo-id attribute here refers to the standard in which the footprint is given. The only value defined by VODataService at this point is ivo://ivoa.net/std/moc, which indicates that retrieving the footprint URL will return a MOC (any IVOA-approved serialisation is legal). Note that the ivo-id attribute was intended to have a different function in VODataService 1.1. The current meaning is what implementors actually adopted. \end{description} \item[Element \xmlel{waveband}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A name of a messenger that the resource is relevant for (e.g., was used in the measurements). Terms must be taken from the vocabulary at http://www.ivoa.net/rdf/messenger. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] It is a bit unfortunate that the element is still called waveband when it is now also covers non-electromagnetic messengers. It was deemed that this slight notional sloppiness is preferable to introducing new and deprecating old elements. \end{description} \item[Element \xmlel{regionOfRegard}] \begin{description} \item[Type] floating-point number: \xmlel{xs:float} \item[Meaning] A single numeric value representing the angle, given in decimal degrees, by which a positional query against this resource should be “blurred” in order to get an appropriate match. \item[Occurrence] optional \item[Comment] In the case of image repositories, it might refer to a typical field-of-view size, or the primary beam size for radio aperture synthesis data. In the case of object catalogues RoR should normally be the largest of the typical size of the objects, the astrometric errors in the positions, or the resolution of the data. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} In order to avoid future ambiguity in the spatial coverage, we already add a :raw-latex:`\xmlel{frame}` attribute to the :raw-latex:`\xmlel{spatial}` element. In its absence, the MOC contained is for ICRS coordinates. Any value indicates non-celestial coordinates, where actual, interoperable values are not defined here. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Type Schema Documentation} \noindent{\small A coverage on a sphere. By default, this refers to the celestial sphere in the ICRS frame. Non-celestial frames are indicated by non-NULL values of the frame attribute. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Attributes} \begingroup\small\begin{bigdescription} \item[frame] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] When present, the MOC is written in a non-celestial (e.g., planetary) frame. Note that for celestial coverages, ICRS must be used. \item[Occurrence] optional \item[Comment] VODataService 1.2 does not prescribe a vocabulary for what values are allowed here. As long as no such vocabulary is agreed upon, the frame attribute should not be set. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Coverage declaration makes use of three types, :raw-latex:`\xmlel{vs:FloatInterval}`, :raw-latex:`\xmlel{vs:Service\-Reference}`, and :raw-latex:`\xmlel{vs:SpatialCoverage}`, defined as follows: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:FloatInterval} Type Schema Documentation} \noindent{\small An interval of floating point numbers. \par} \noindent{\small This uses VOTable TABLEDATA serialisation, i.e., simply a pair of XSD floating point numbers separated by whitespace; note that software utilising non-XSD aware parsers has to perform whitespace normalisation itself here (in particular, for the internal whitespace). \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:FloatInterval} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ServiceReference} Type Schema Documentation} \noindent{\small The service URL for a potentially registered service. That is, if an IVOA identifier is also provided, then the service is described in a registry. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:ServiceReference} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:ServiceReference} Attributes} \begingroup\small\begin{bigdescription} \item[ivo-id] \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] The URI form of the IVOA identifier for the service describing the capability refered to by this element. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VODataService:sect:table`: 3.3 Tabular Data ---------------- The :raw-latex:`\xmlel{vs:TableSet}` type should be used to describe the set of tables that are part of a single resource. While there is no expectation that the table set directly corresponds to the responses of tabular services, services should not include metadata for purely internal tables. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSet} Type Schema Documentation} \noindent{\small The set of tables hosted by a resource. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSet} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableSet} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{schema}] \begin{description} \item[Type] composite: \xmlel{vs:TableSchema} \item[Meaning] A named description of a group of logically related tables. \item[Occurrence] required; multiple occurrences allowed. \item[Comment] The name given by the “name” child element must be unique within this TableSet instance. If there is only one schema in this set and/or there is no locally appropriate name to provide, the name can be set to “default”. \item[Comment] This aggregation does not need to map to an actual database, catalogue, or schema, though the publisher may choose to aggregate along such designations. Particular service protocols may require stricter patterns. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The :raw-latex:`\xmlel{vs:TableSchema}` type groups tables that are logically related. For example, a single resource may provide access to several major astronomical catalogues (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance cross-correlations between them. Each catalogue can be described in a separate :raw-latex:`\xmlel{schema}` element, using the elements from the :raw-latex:`\xmlel{vs:TableSchema}` type. The order in which :raw-latex:`\xmlel{schema}` elements are given within a tableset is significant. Publishers should put schemas they consider more important or interesting lexically before less salient ones. For TAP services, this order should be consistent with the one implied by TAP_SCHEMA’s ``schema_index``. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Documentation} \noindent{\small A detailed description of a logically related group of tables. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableSchema} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A name for the group of tables. \item[Occurrence] required \item[Comment] This is used to uniquely identify the group of tables among several groups. If no title is given, this name can be used for display purposes. \item[Comment] If there is no appropriate logical name associated with this group, the name should be explicitly set to “default”. \end{description} \item[Element \xmlel{title}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A descriptive, human-interpretable name for the group of tables. \item[Occurrence] optional \item[Comment] This is used for display purposes. There is no requirement regarding uniqueness. It is useful when there are multiple schemas in the context (e.g., within a tableset; otherwise, the resource title could be used instead). \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A free text description of the group of tables that should explain in general how all of the tables in the group are related. \item[Occurrence] optional \end{description} \item[Element \xmlel{utype}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] An identifier for a concept in a data model that the data in this schema as a whole represent. \item[Occurrence] optional \item[Comment] The form of the utype string depends on the data model; common forms are sequences of dotted identifiers (e.g., in SSA) or URIs (e.g., in RegTAP). \end{description} \item[Element \xmlel{table}] \begin{description} \item[Type] composite: \xmlel{vs:Table} \item[Meaning] A description of one table. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Each table in a schema is described in detail using the :raw-latex:`\xmlel{vs:Table}` type. As with :raw-latex:`\xmlel{schema}`, the order of the :raw-latex:`\xmlel{table}` elements is significant, with more salient tables listed further up within a schema element. For TAP services, this order should be consistent with the one implied by TAP_SCHEMA’s ``table_index``. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vs:Table} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Table} Attributes} \begingroup\small\begin{bigdescription} \item[type] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] A name for the role this table plays. Recognized values include “output”, indicating this table is output from a query; “base\_table”, indicating a table whose records represent the main subjects of its schema; and “view”, indicating that the table represents a useful combination or subset of other tables. Other values are allowed. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Table} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The fully qualified name of the table. This name should include all catalogue or schema prefixes needed to sufficiently uniquely distinguish it in a query. \item[Occurrence] required \item[Comment] In general, the format of the qualified name may depend on the context; however, when the table is intended to be queryable via ADQL, then the catalogue and schema qualifiers are delimited from the table name with dots (.). \end{description} \item[Element \xmlel{title}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A descriptive, human-interpretable name for the table. \item[Occurrence] optional \item[Comment] This is used for display purposes. There is no requirement regarding uniqueness. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A free-text description of the table's contents \item[Occurrence] optional \end{description} \item[Element \xmlel{utype}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] An identifier for a concept in a data model that the data in this table represent. \item[Occurrence] optional \item[Comment] The form of the utype string depends on the data model; common forms are sequences of dotted identifiers (e.g., in SSA) or URIs (e.g., in RegTAP). \end{description} \item[Element \xmlel{nrows}] \begin{description} \item[Type] \xmlel{xs:nonNegativeInteger} \item[Meaning] The approximate size of the table in rows. \item[Occurrence] optional \item[Comment] This is not expected to be exact. For instance, the estimates on table sizes databases keep for query planning purposes are suitable for this field. \end{description} \item[Element \xmlel{column}] \begin{description} \item[Type] composite: \xmlel{vs:TableParam} \item[Meaning] A description of a table column. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{foreignKey}] \begin{description} \item[Type] composite: \xmlel{vs:ForeignKey} \item[Meaning] A description of a foreign keys, one or more columns from the current table that can be used to join with another table. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Each column in a table can be described using the :raw-latex:`\xmlel{vs:TableParam}` type which is described in section :ref:`VODataService:sect:param`. The foreign keys in the table that can be used to join it with another table can be described with the :raw-latex:`\xmlel{vs:ForeignKey}` type (section :ref:`VODataService:sect:fkey`). A foreign key description should only refer to tables described within the current table set. When the table set describes a set of TAP-accessible tables, the value of a :raw-latex:`\xmlel{table}`’s :raw-latex:`\xmlel{name}` child must be in a form immediately usable for use in ADQL or SQL queries. This corresponds to the analogous requirement for TAP_SCHE:raw-latex:`\-`MA. This means that all qualifications (schema, catalogue) must be present, but also that when delimited identifiers are used as table names on the relational side, the quotes must be part of :raw-latex:`\xmlel{name}`’s value, and the capitalisation used in the DDL must be preserved. The :raw-latex:`\xmlel{vs:Table}` also provides an attribute for indicating the role a table plays in the schema. .. _`VODataService:sect:unique`: 3.3.1 Unique Names for Tables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The definitions of the :raw-latex:`\xmlel{tableset}` elements used in the :raw-latex:`\xmlel{vs:DataCollection}` and :raw-latex:`\xmlel{vs:Cat\-alog\-Ser\-vice}` types constrain certain names to be unique. In particular, all schema names within a :raw-latex:`\xmlel{tableset}` element must be unique, and all table names within a :raw-latex:`\xmlel{schema}` element must be unique. A schema and table may share a common name, such as “default”. These constraints make it possible to uniquely locate the description of a schema or table within a VOResource description. .. _`VODataService:sect:fkey`: 3.3.2 Foreign Keys ~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:ForeignKey}` type is used to describe foreign keys in a table that allow it to be joined efficiently with another table. A foreign key is a set of columns that map to a corresponding set of columns in another table. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Documentation} \noindent{\small A description of the mapping a foreign key -- a set of columns from one table -- to columns in another table. \par} \noindent{\small When foreign keys are declared in this way, clients can expect that joins constrained with the foreign keys are preformed efficiently (e.g., using an index). \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:ForeignKey} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{targetTable}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The fully qualified name (including catalogue and schema, as applicable) of the table that can be joined with the table containing this foreign key. \item[Occurrence] required \end{description} \item[Element \xmlel{fkColumn}] \begin{description} \item[Type] composite: \xmlel{vs:FKColumn} \item[Meaning] A pair of column names, one from this table and one from the target table that should be used to join the tables in a query. \item[Occurrence] required; multiple occurrences allowed. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A free-text description of what this key points to and what the relationship means. \item[Occurrence] optional \end{description} \item[Element \xmlel{utype}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] An identifier for a concept in a data model that the association enabled by this key represents. \item[Occurrence] optional \item[Comment] The form of the utype string depends on the data model; common forms are sequences of dotted identifiers (e.g., in SSA) or URIs (e.g., in RegTAP). \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} In this model, the source of the foreign key is the current table being described (i.e., represented by the :raw-latex:`\xmlel{table}` element that contains the :raw-latex:`\xmlel{vs:ForeignKey}` description, and thus does not need to be named explicitly). The key that is described points to the table given by the :raw-latex:`\xmlel{targetTable}` child element. Each child :raw-latex:`\xmlel{fkColumn}` element then gives a pair of columns, one from the source table and one from the target table, that can be constrained to be equal in a query that joins the two tables. .. _`VODataService:sect:tblext`: 3.3.3 Extending Table Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is envisioned that it may be useful in the future to provide richer metadata for describing tables within a VOResource description than what are defined in this document. This document recommends the use of the following extension mechanisms when richer descriptions are desired: #. Use extended types by applying the :raw-latex:`\xmlel{xsi:type}` attribute to the :raw-latex:`\xmlel{tableset}`, :raw-latex:`\xmlel{schema}`, :raw-latex:`\xmlel{table}`, :raw-latex:`\xmlel{column}` and/or :raw-latex:`\xmlel{dataType}` elements. The values provided in the attributes must refer to an XML type legally extended from the types associated with these elements according to the rules of XML Schema :cite:p:`std:XSD` and the VOResource specification. #. Apply a globally-defined attribute from a schema other than VODataService (i.e. from a namespace other than `http://www.ivoa.net/xml/VODataSer\\-vice/v1.1 `__) to any of the :raw-latex:`\xmlel{tableset}`, :raw-latex:`\xmlel{schema}`, :raw-latex:`\xmlel{table}`, and/or :raw-latex:`\xmlel{column}` elements. #. When the extended metadata is specific to how the table data is accessed via a particular service protocol, then the new metadata can be incorporated into a specific capability extension (as described in the VOResource specification). This extension may make use of the various names within the :raw-latex:`\xmlel{tableset}` to indicate where the extension metadata apply. #. Use the :raw-latex:`\xmlel{extendedType}` attribute of the :raw-latex:`\xmlel{dataType}` element (see section :ref:`VODataService:sect:tbldatatypes`) to indicate a more specific data type then those defined by the :raw-latex:`\xmlel{vs:TableParam}` type. .. _`VODataService:sect:paramif`: 3.4 Interface Type Extension: ParamHTTP --------------------------------------- The :raw-latex:`\xmlel{vs:ParamHTTP}` type is a specialized service interface description that extends the VOResource :raw-latex:`\xmlel{vr:Interface}` type (as recommended by VOResource 1.1, section 2.2). It describes a service interface that is invoked over HTTP via a GET or a POST in which the inputs are parameters encoded in multipart/form-data or application/x-www-form-urlencoded containers. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Documentation} \noindent{\small A service invoked via an HTTP Query (either Get or Post) with a set of arguments consisting of keyword name-value pairs. \par} \noindent{\small Note that the URL for help with this service can be put into the service/referenceURL element. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{queryType}] \begin{description} \item[Type] string with controlled vocabulary \item[Meaning] The type of HTTP request, either GET or POST. \item[Occurrence] optional; up to 2 occurrences allowed. \item[Terms]\hfil \begin{longtermsdescription} \item[GET] \item[POST] \end{longtermsdescription} \item[Comment] The service may indicate support for both GET and POST by providing 2 queryType elements, one with GET and one with POST. Since the IVOA standard DALI requires standard services to support both GET and POST, this piece of metadata is not useful in the description of standard DAL services and does not need to be given for those. \end{description} \item[Element \xmlel{resultType}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The MIME media type of a document returned in the HTTP response. \item[Occurrence] optional \end{description} \item[Element \xmlel{param}] \begin{description} \item[Type] composite: \xmlel{vs:InputParam} \item[Meaning] A description of a input parameter that can be provided as a name=value argument to the service. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{testQuery}] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] An ampersand-delimited list of arguments that can be used to test this service interface; when provided as the input to this interface, it will produce a legal, non-null response. \item[Occurrence] optional \item[Comment] When the interface supports GET, then the full query URL is formed by the concatenation of the base URL (given by the accessURL) and the value given by this testQuery element. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The extension metadata defined in the schema definition above are all optional. Nevertheless, even when an :raw-latex:`\xmlel{interface}` instance does not include any of these extended child elements, the use of ``xsi:type="vs:ParamHTTP"`` indicates that the interface accessed via the URL given by the :raw-latex:`\xmlel{accessURL}` element complies with the general parameter-based protocol described in this section. An important intended use of the :raw-latex:`\xmlel{vs:ParamHTTP}` type is describing the interface of an IVOA standard service protocol of the “simple” variety, such as the Simple Image Access Protocol :cite:p:`2015ivoa.spec.1223D`. In particular, it is recommended that specifications that define how a standard service is registered in a registry *require* the use of the :raw-latex:`\xmlel{vs:ParamHTTP}` interface type when it is applicable. Normally, a VOResource description indicates its support for a standard protocol with a :raw-latex:`\xmlel{capability}` element having a :raw-latex:`\xmlel{standardID}` attribute set to specific URI representing the standard. The standard will usually spell out the HTTP query type, the returned media type, and input parameters required for compliance; therefore, it is not necessary that the :raw-latex:`\xmlel{vs:ParamHTTP}` description provide any of the optional extended metadata, as they are already implied by the :raw-latex:`\xmlel{standardID}`. The description need only reflect the optional or locally unique features of the interface. In particular, description may include - a :raw-latex:`\xmlel{queryType}` element for a type that is not required by the standard (as long as the required query type is supported as well), - :raw-latex:`\xmlel{param}` elements for any optional parameters or local extended parameters (when allowed by the standard). Listing required parameters is allowed, even when describing a standard interface, as long as these are consistent with the service specification and the corresponding :raw-latex:`\xmlel{param}` elements include the attribute ``std="true"`` (see section :ref:`VODataService:sect:inputparam`). The :raw-latex:`\xmlel{param}` elements for custom parameters that are not part of the standard (but are rather local customizations) should include the attribute ``std="false"``. .. _`VODataService:sect:param`: 3.5 Data Parameters ------------------- The VODataService schema provides several element types for describing different kinds of data parameters used in datasets and services, including service input parameters and table columns. The parameter types describe a parameter in terms of elementary metadata including name, data type, and meaning. All the VODataService parameter types derive from the base type :raw-latex:`\xmlel{vs:BaseParam}` which defines all the common parameter metadata except the data type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Documentation} \noindent{\small A description of a parameter that places no restriction on the parameter's data type. \par} \noindent{\small As the parameter's data type is usually important, schemas normally employ a sub-class of this type rather than this type directly. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:BaseParam} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The name of the parameter or column. \item[Occurrence] optional \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A free-text description of a parameter's or column's contents. \item[Occurrence] optional \end{description} \item[Element \xmlel{unit}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The unit associated with the values in the parameter or column. \item[Occurrence] optional \end{description} \item[Element \xmlel{ucd}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The name of a unified content descriptor that describes the scientific content of the parameter. \item[Occurrence] optional \item[Comment] There are no requirements for compliance with any particular UCD standard. \end{description} \item[Element \xmlel{utype}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] An identifier for a concept in a data model that the data in this schema represent. \item[Occurrence] optional \item[Comment] The form of the utype string depends on the data model; common forms are sequences of dotted identifiers (e.g., in SSA) or URIs (e.g., in RegTAP). \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Leaving the data type metadatum out of :raw-latex:`\xmlel{vs:BaseParam}` allows the different kinds of parameters derived from :raw-latex:`\xmlel{vs:BaseParam}` to restrict the allowed data types to specific sets. The subsections below describe the different data types associated with input parameters (:raw-latex:`\xmlel{vs:InputParam}`) and table columns (:raw-latex:`\xmlel{vs:TableParam}`). The XML types associated with their :raw-latex:`\xmlel{dataType}` elements derive from a common parent, :raw-latex:`\xmlel{vs:DataType}`. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Documentation} \noindent{\small A type (in the computer language sense) associated with a parameter with an arbitrary name \par} \noindent{\small This XML type is used as a parent for defining data types with a restricted set of names. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:DataType} Attributes} \begingroup\small\begin{bigdescription} \item[arraysize] \begin{description} \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]} \item[Meaning] The shape of the array that constitutes the value. \item[Occurrence] optional \item[Comment] Leave arraysize empty for scalar values. In version 1.1, this defaulted to 1, which was intended to indicate a scalar. This is now deprecated; an arraysize of 1 should be avoided now, the future interpretation, in accord with VOTable, will be “array of size 1”. \end{description} \item[delim] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] A string that is used to delimit elements of an array value in InputParams. \item[Occurrence] optional \item[Comment] Unless specifically disallowed by the context, applications should allow optional spaces to appear in an actual data value before and after the delimiter (e.g., “1, 5” when delim=“,”). \item[Comment] This should not be used for VOTable types; there, VOTable (typcially TABLEDATA) conventions for writing arrays are binding. \end{description} \item[extendedType] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] The data value represented by this type can be interpreted as of a custom type identified by the value of this attribute. \item[Occurrence] optional \item[Comment] If an application does not recognize this extendedType, it should attempt to handle the value assuming the type given by the element's value. string is a recommended default type. \item[Comment] This element may make use of the extendedSchema attribute to refine the identification of the type. extendedTypes without an extendedSchema mean VOTable xtypes as defined by DALI. \end{description} \item[extendedSchema] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] An identifier for the schema that the value given by the extended attribute is drawn from. \item[Occurrence] optional \item[Comment] This attribute is normally ignored if the extendedType attribute is not present. A missing extendedSchema indicates that extendedType is a VOTable xtype. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The content of an element of type :raw-latex:`\xmlel{vs:DataType}` is the name of the data type for the current parameter. When the element is explicitly a :raw-latex:`\xmlel{vs:DataType}` (as opposed to one of its derived types), there are no restrictions on the names that may be included. A data type description can be augmented via a common set of :raw-latex:`\xmlel{vs:DataType}` attributes. The :raw-latex:`\xmlel{arraysize}` attribute indicates the parameter is an array of values of the named type. Its value describes the shape of the array. When there is no natural serialisation defined through the type system, the :raw-latex:`\xmlel{delim}` attribute may be used to indicate a delimiter that should appear between elements of an array value. This attribute must not be combined with VOTableDataType, which always uses VOTable serialisation rules. More descriptive information about the type can be provided via :raw-latex:`\xmlel{extendedType}` and :raw-latex:`\xmlel{extendedSchema}`, which provide an alternate data type name. The name given in the type’s element content, then, represents a commonly understood “fallback” type. For instance, in VOTable, timestamps are serialised into strings, which implies a VOTableType of char with arraysize ``*``, as supported by all VOTable readers. VOTable readers interpreting the timestamp xtype, however, can turn this string into a timestamp value native to its clients. Such readers will interpret a VOTable :raw-latex:`\xmlel{FIELD}`’s :raw-latex:`\xmlel{xtype}` attribute. Such information is reflected in :raw-latex:`\xmlel{extendedType}`. Arbitrary information can also be provided via any prefix-qualified, globally defined attribute drawn from an XML Schema other than VODataService (by virtue of the :raw-latex:`\xmlel{xs:anyAttribute}` specification present on :raw-latex:`\xmlel{vs:DataType}`). Note that in the derived parameter description types described below, the :raw-latex:`\xmlel{dataType}` element is optional. Its absence from the parameter description does *not* mean that the parameter can support any data type; rather, it means that the data type simply has not been provided (which may limit what an application can do with the parameter). If a parameter can truly support any data type, the :raw-latex:`\xmlel{vs:BaseParam}` type can be used directly when the context permits. .. _`VODataService:sect:inputparam`: 3.5.1 Input Parameters ~~~~~~~~~~~~~~~~~~~~~~ Actual parameters are normally described with types derived from :raw-latex:`\xmlel{vs:BaseParam}`. The :raw-latex:`\xmlel{vs:InputParam}` is intended for describing an input parameter to a service or function. In previous versions of VODataService, input parameters were restricted to be defined in terms of simple data types, which are intended to be sufficient for describing an input parameter to a simple REST-like service or a function in a weakly-typed language. They are defined in :raw-latex:`\xmlel{vs:SimpleDataType}`: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Documentation} \noindent{\small A data type restricted to a small set of names which is imprecise as to the format of the individual values. \par} \noindent{\small This set is intended for describing simple input parameters to a service or function. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Attributes} \begingroup\small\begin{bigdescription} \item[arraysize] \begin{description} \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \item[delim] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] See vs:DataType. \item[Occurrence] optional \item[Default] a space character \end{description} \item[extendedType] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \item[extendedSchema] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Since VODataService 1.2, input parameters can use any type system, where non-DALI-compliant services SHOULD use :raw-latex:`\xmlel{vs:SimpleDataType}` and DALI-compliant services SHOULD use :raw-latex:`\xmlel{vs:VOTableType}`. To ensure schema validation catches mistakes, resource record authors are advised to declare the type system intended using :raw-latex:`\xmlel{xsi:type}`; for instance, a service accepting a DALI point might declare: .. code:: xml pos ICRS position of target object double The :raw-latex:`\xmlel{vs:InputParam}` class then is a :raw-latex:`\xmlel{vs:BaseParam}` furnished with additional metadata defining how to use the parameter and whether or not it is defined in the standard governing the capability the interface is in (if any): .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Documentation} \noindent{\small A description of a service or function parameter having a fixed data type. \par} \noindent{\small DALI-compliant services should use VOTableType here, others should use SimpleDataType. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:InputParam} Attributes} \begingroup\small\begin{bigdescription} \item[use] \begin{description} \item[Type] string with controlled vocabulary \item[Meaning] An indication of whether this parameter is required to be provided for the application or service to work properly. \item[Occurrence] optional \item[Terms]\hfil \begin{longtermsdescription} \item[required] The parameter is required for the application or service to work properly. \item[optional] The parameter is optional but supported by the application or service. \item[ignored] The parameter is not supported and thus is ignored by the application or service. \end{longtermsdescription} \item[Default] optional \end{description} \item[std] \begin{description} \item[Type] boolean (true/false): xs:boolean \item[Meaning] If true, the meaning and behavior of this parameter is reserved and defined by a standard interface. If false, it represents an implementation-specific parameter that effectively extends the behavior of the service or application. \item[Occurrence] optional \item[Default] true \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vs:InputParam} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}] \begin{description} \item[Type] a string with optional attributes \item[Meaning] A type of data contained in the parameter. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Here is an example for a description of an input parameter that might appear inside an :raw-latex:`\xmlel{vs:ParamHTTP}` interface description. As noted in section :ref:`VODataService:sect:paramif`, a :raw-latex:`\xmlel{param}` element uses the :raw-latex:`\xmlel{vs:InputParam}` type to describe itself: .. code:: xml radius search radius; returned objects are restricted to fall within this angular distance of the search position. phys.angSize real .. _`VODataService:sect:columns`: 3.5.2 Table Columns ~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vs:TableParam}` is also derived from :raw-latex:`\xmlel{vs:BaseParam}`, and is designed for describing a column of a table. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Documentation} \noindent{\small A description of a table parameter having a fixed data type. \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableParam} Attributes} \begingroup\small\begin{bigdescription} \item[std] \begin{description} \item[Type] boolean (true/false): xs:boolean \item[Meaning] If true, the meaning and use of this parameter is reserved and defined by a standard model. If false, it represents a parameter specific to the data described If not provided, then the value is unknown. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableParam} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}] \begin{description} \item[Type] \xmlel{vs:DataType} with optional attributes \item[Meaning] A type of data contained in the column \item[Occurrence] optional \end{description} \item[Element \xmlel{flag}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A keyword representing traits of the column. Recognized values include “indexed”, “primary”, and “nullable”. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] While other values are allowed, the following semantics is defined by this specification: indexed – The column has an index on it for faster search against its values; primary – The values column in the column represent in total or in part a primary key for its table; nullable – the column may contain null or empty values. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} A table column’s data type is indicated with the :raw-latex:`\xmlel{dataType}` element with a name drawn from a standard set of names. Because :raw-latex:`\xmlel{dataType}`’s XML type, :raw-latex:`\xmlel{vs:TableDataType}`, is abstract, the element MUST include an :raw-latex:`\xmlel{xsi:type}` attribute. As discussed in sect. :ref:`VODataService:sect:tbldatatypes`, this SHOULD be :raw-latex:`\xmlel{vs:VOTableType}` for VODataService 1.2 table columns. When the tableset describes a set of TAP-accessible tables, the value of a :raw-latex:`\xmlel{tableColumn}`’s :raw-latex:`\xmlel{name}` child must be in a form immediately usable for use in ADQL or SQL queries. This corresponds to the analogous requirement for TAP_SCHE:raw-latex:`\-`MA and is usually only a problem when delimited identifiers are used for column names on the relational side. In that case, the quotes must be part of :raw-latex:`\xmlel{name}`’s value, and the capitalisation used in the DDL must be preserved. As examples, here are declarations of a column called “Dec” containing a double-valued declination, of the (deprecated) ``size`` column from TAP 1.0 which requires quotes because it otherwise clashes with a SQL reserved name, and a SIAP 1.0-compatible ``wcs_cdmatrix`` column that shows how multidimensional arrays are declared; note that in the last case, the content of :raw-latex:`\xmlel{unit}` pertains to *elements* of the array, not the array as a whole. .. code:: xml Dec the J2000 declination of the object pos.eq.dec double "size" Length of variable length datatypes int nullable wcs_cdmatrix World coordinates at WCS reference pixel deg VOX:WCS_CoordRefValue double nullable .. _`VODataService:sect:tbldatatypes`: 3.5.3 Table Column Data Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The VODataService schema defines two type systems that derive from :raw-latex:`\xmlel{vs:TableDa\-taType}`: :raw-latex:`\xmlel{vs:VOTableType}` and :raw-latex:`\xmlel{vs:TAPType}`. Following the move to VOTable-compatible type descriptions in TAP 1.1 :doc:`ref <../TAP/TAP>`, this version of VODataService deprecates the use of :raw-latex:`\xmlel{vs:TAPType}`. New software should only generate :raw-latex:`\xmlel{vs:VOTableType}`s in :raw-latex:`\xmlel{tableset}`s. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Documentation} \noindent{\small A data type supported explicitly by the VOTable format \par} \vspace{1ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vs:VOTableType} Attributes} \begingroup\small\begin{bigdescription} \item[arraysize] \begin{description} \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \item[delim] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] See vs:DataType. \item[Occurrence] optional \item[Default] a space character \end{description} \item[extendedType] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \item[extendedSchema] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] See vs:DataType. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} When the actual column type is not well matched to a VOTable data type, authors are encouraged to use the :raw-latex:`\xmlel{extendedType}` attribute to refer to a more specific type. This will usually be a VOTable :raw-latex:`\xmlel{xtype}` as defined by DALI :doc:`ref <../DALI/DALI>`. Using different extended type schemes is possible by setting :raw-latex:`\xmlel{extendedSchema}` to a non-empty value; data providers using this extension mechanism should explain their schema in an IVOA Note. Appendices ========== .. _`VODataService:changes-from-previous-versions`: A Changes from previous versions ================================ .. _`VODataService:changes-since-rec-1.2`: A.1 Changes since REC-1.2 ------------------------- - Adding a :raw-latex:`\xmlel{productTypeServed}` child to :raw-latex:`\xmlel{DataService}`; this is intended to replace the previous practice of choosing product types by service types. - Postponing the drop of StandardSTC and DataCollection to version 1.4. - Clarifying that the order of schema and table elements in a tableset is significant. .. _`VODataService:changes-since-pr-20210223`: A.2 Changes since PR-20210223 ----------------------------- - Numerous editorial changes after RFC comments without impact on the normative content. - Schema: Minor style fixes (e.g., removing gratuitous maxOccurs) without impact on document validity. .. _`VODataService:changes-since-pr-20190715`: A.3 Changes since PR-20190715 ----------------------------- - Sect. :ref:`VODataService:sect:resext` and schema: dropped ``vs:Waveband`` and changed waveband to being controlled by a vocabulary that initially grows a generic Photon and a Neutrino concept over what the previous Waveband had. - Sect. :ref:`VODataService:sect:table` and schema: table/@nrows is now constrained to be non-negative. - Sect. :ref:`VODataService:sect:inputparam` and schema: Now allowing any vs:DataType element to define vs:InputParams. In order to still ensure schema validation of type names, now advising to have an explicit xsi:type in param’s dataTypes. .. _`VODataService:changes-since-wd-20181026`: A.4 Changes since WD-20181026 ----------------------------- - Sect. :ref:`VODataService:sect:discoverdata`: Added a summary of the discovering data collections EN. - Sect. :ref:`VODataService:sect:cover` and schema: Spatial coverage now has a frame attribute. - Sect. :ref:`VODataService:sect:CatalogResource`: Added a SHOULD requirement on CatalogResources to have a tableset. - Sect. :ref:`VODataService:sect:paramif` and schema: Restricted interface/@testQuery to zero or one occurrences (this is because there is no clear semantics to having multiple of those). - Sect. :ref:`VODataService:sect:cover`: Sanctioning the use of footprint/@ivo-id to indicate the footprint standard used (which, of course, totally goes against the semantics of ServiceReference underlying footprint). .. _`VODataService:changes-since-rec-1.1`: A.5 Changes since REC-1.1 ------------------------- - Sect. :ref:`VODataService:sect:cover` and schema: Deprecated STCResourceProfile and replaced it with :raw-latex:`\xmlel{spatial}`, :raw-latex:`\xmlel{temporal}`, and :raw-latex:`\xmlel{spectral}` elements. - Sect. :ref:`VODataService:sect:resext` and schema: Introduced new DataResource and CatalogResource resource types and wove them into the inheritance hierarchy to CatalogService; these are to be used for “dependent” resources. - Sect. :ref:`VODataService:sect:cover`: Deprecated DataCollection and StandardSTC (which are no longer needed). - Sect. :ref:`VODataService:sect:table` and schema: Added an nrows element to :raw-latex:`\xmlel{vs:Table}`. - Sect. :ref:`VODataService:sect:table`: Required inclusion of quotes for delimited identifiers in a SQL context. - Sect. :ref:`VODataService:sect:param` and schema: DataType/@arraysize no longer defaults to 1, and the interpretation of arraysize=1 as a scalar is withdrawn. Use empty arraysize for scalars now. - Sect. :ref:`VODataService:sect:param` and schema: DataType’s delim attribute no longer defaults to blank. That would be very unfortunate with VOTable, where other conventions are in place (e.g., for string arrays). Now discouraging the use of delim outside of InputParams. - Sect. :ref:`VODataService:sect:tbldatatypes`: Deprecated TAPType. - Sect. :ref:`VODataService:sect:tbldatatypes`: extendedType is now defined to correspond to VOTable xtypes in the absence of extendedSchema. - Sect. :ref:`VODataService:sect:table`: No longer requiring unique table names within a tableset; uniquness is now required within a schema (actually, many services have been in violation of the old unique-within-tableset rule for a long time without operational difficulties); but then that’s largely a moot point because for the main uses of tableset, fully qualified names are now required. - Ported source to :raw-latex:`\ivoatex`. .. _`VODataService:changes-since-pr-20100916`: A.6 Changes since PR-20100916 ----------------------------- - updated status for elevation to Recommendation. - cleaned-up mis-labeled and mis-ordered change history. .. _`VODataService:changes-since-pr-20100914`: A.7 Changes since PR-20100914 ----------------------------- - added change history for PR-20100412. - added Note about STC mark-up in :ref:`VODataService:sect:cover` - reworded sentence describing content of :raw-latex:`\xmlel{vs:DataType}` in section :ref:`VODataService:sect:param`. .. _`VODataService:changes-since-pr-20100412`: A.8 Changes since PR-20100412 ----------------------------- - fix numerous typos discovered in TCG review - added section 1.1 to describe role of standard in the VO architecture, including diagram. - corrected frequency range for the UV waveband - corrected links to reference documents .. _`VODataService:changes-since-pr-20090903`: A.9 Changes since PR-20090903 ----------------------------- - added :raw-latex:`\xmlel{testQuery}` to :raw-latex:`\xmlel{vs:ParamHTTP}` - in text, added explanation of :raw-latex:`\xmlel{vs:Format}` - grammatical clean-up .. _`VODataService:changes-since-wd-20090508-v1.10`: A.10 Changes since WD-20090508 (v1.10) -------------------------------------- - corrected errors in example in Introduction - added :raw-latex:`\xmlel{description}` and :raw-latex:`\xmlel{utype}` elements to the :raw-latex:`\xmlel{vs:ForeignKey}` type for consistency with TAP. - changed type names :raw-latex:`\xmlel{vs:TAP}` to :raw-latex:`\xmlel{vs:TAPType}` and :raw-latex:`\xmlel{vs:VOTable}` :raw-latex:`\xmlel{vs:VOTableType}`. .. [1] http://www.ivoa.net/xml .. [2] http://www.g-vo.org/rdf/product-type .. [3] Of course, in non-service discovery (e.g., authorities or standards), resource types are important. .. [4] http://www.ivoa.net/rdf/messenger .. [5] Defined in http://www.ivoa.net/xml/STC/stc-v1.30.xsd .. |image1| image:: role_diagram.pdf :width: 90.0%