This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress".
A list of current IVOA Recommendations and other technical documents can be found in the IVOA document repository.
The VOTable format is an XML standard for the interchange of data represented as a set of tables. In this context, a table is an unordered set of rows, each of a uniform structure, as specified in the table description (the table metadata). Each row in a table is a sequence of table cells, and each of these contains either a primitive data type, or an array of such primitives. VOTable is derived from the Astrores format (Accomazzi and Albrecht et al., 2001), itself modeled on the FITS Table format (Hanisch and Farris et al., 2001); VOTable was designed to be close to the FITS Binary Table format.
Astronomers have always been at the forefront of developments in information technology, and funding agencies across the world have recognized this by supporting the Virtual Observatory movement, in the hopes that other sciences and business can follow their lead in making online data both interoperable and scalable.
VOTable is designed as a flexible storage and exchange format for tabular data, with particular emphasis on astronomical tables.
Interoperability is encouraged through the use of standards (XML). The XML fabric allows applications to easily validate an input document, as well as facilitating transformations through XSLT (eXtensible Style Language Transformation) engines.
VOTable has built-in features for big-data and Grid computing. It allows metadata and data to be stored separately, with the remote data linked. Processes can then use metadata to `get ready' for their input data, or to organize third-party or parallel transfers of the data. Remote data allow the metadata to be sent in email and referenced in documents without pulling the whole dataset with it: just as we are used to the idea of sending a pointer to a document (URL) in place of the document, so we can now send metadata-rich pointers to data tables in place of the tables themselves. The remote data is referenced with the URL syntax protocol://location, meaning that arbitrarily complex protocols are allowed.
When we are working with very large tables in a distributed-computing environment ("the Grid"), the data stream between processors, with flows being filtered, joined, and cached in different geographic locations. It would be very difficult if the number of rows of the table were required in the header - we would need to stream in the whole table into a cache, compute the number of rows, then stream it again for the computation. In the Grid-data environment, the component in short supply is not the computers, but rather these very large caches. Furthermore, these remote data streams may be created dynamically by another process or cached in temporary storage: for this reason VOTable can express that remote data may not be available after a certain time (expires). Data on the net may require authentication for access, so VOTable allows expression of password or other identity information (the `rights' attribute).
The data part in a VOTable may be represented using one of four different formats: TABLEDATA, FITS, BINARY and BINARY2. TABLEDATA is a pure XML format so that small tables can be easily handled in their entirety by XML tools. The FITS binary table format is well-known to astronomers, and VOTable can be used either to encapsulate such a file, or to re-encode the metadata; unfortunately it is difficult to stream FITS, since the dataset size is required in the header (NAXIS2 keyword), and FITS requires a specification up front of the maximum size of its variable-length arrays. The BINARY and BINARY2 formats are supported for efficiency and ease of programming: no FITS library is required, and the streaming paradigm is supported.
VOTable can be used in different ways, as a data storage and transport format, and also as a way to store metadata alone (table structure only). In the latter case, a VOTable structure can be sent to a server, which can then open a high-bandwidth connection to receive the actual data, using the previously-digested structure as a way to interpret the stream of bytes from the data socket.
VOTable can be used for small numbers of small records (pure XML tables), or for large numbers of simple records (streaming data), or it can be used for small numbers of larger objects. In the latter case, there will be software to spread large data blocks among multiple processors on the Grid. Currently the most complex structure that can be in a VOTable Cell is a multidimensional array.
VOTable is constructed with XML (extensible Markup Language), a powerful standard for structured data throughout the Internet industries. It derives from SGML, a standard used in the publishing industry and for technical documentation for many years. XML consists of elements and payload, where an element consists of a start tag (the part in angle brackets), the payload, and an end tag (with angle brackets and a slash). Elements can contain other elements. Elements can also bear attributes (keyword-value combinations).
The payload may be in two forms: parsed or unparsed character data. Examples are:
<text>François</text> <text><![CDATA[ a & (b <= c) ]]></text>
In the first example, the sequence ç is interpreted as a character entity reference for the Unicode code point U+00E7 and translates to an accented character, so that the text is "François". The second example uses the special CDATA sequence so that the characters <, >, and & can be used without interpretation; in this case, any characters are allowed except the terminating sequence ]]>. For more information, see any book on XML.
Following the general XML rule, element and attribute names are case-sensitive and have to be used with the specified capitalisation. For VOTable, we have adopted the convention that element names are spelled in uppercase and attribute names in lowercase (with an exception for the ID attribute). Element and attribute names are further distinguished in this paper by being typed with a red fixed-width font, and the values of the attributes by being "coloured".
VOTable is a core IVOA standard. Figure 1 shows the role this document plays within the IVOA architecture.
Wherever tabular data is transferred between Virtual Observatory components, VOTable provides the preferred serialization format. Since tables are used to list available resources as well as to represent science data which is itself tabular, this means that VOTable is used pervasively in the definitions of the Data Access protocols (e.g. SCS, SIA, SSA, TAP), and hence for exchange of data and metadata between user layer applications and data-providing services. VOTable is also used as a serialization format for some of the IVOA Data Models.
In order to represent semantically rich metadata, VOTable relies on the other IVOA standards UCD, Utype, VOUnits, and DALI. This document explains how information structured according to those standards are managed within the VOTable framework.
In this section we define the data model of a VOTable, and in the next sections its syntax when expressed as XML. The data model of VOTable can be expressed as:
| VOTable | = | hierarchy of Metadata + associated TableData, arranged as a set of Tables | |||||||
| Metadata | = | Parameters + Infos + Descriptions + Links + Fields + Groups | |||||||
| Table | = | list of Fields + TableData | |||||||
| TableData | = | stream of Rows | |||||||
| Row | = | list of Cells | |||||||
| Cell | = | {
| |||||||
| Primitive | = | integer, character, float, floatComplex, etc (see Table 1 below). |
A parameter (PARAM) is similar to a FIELD, except that it has a value attribute. Parameters can be seen as "constant columns", containing for instance FITS keywords or any other information pertaining to the table itself or its environment, such as the Telescope parameter in the example of section 3.1.
An informative parameter (INFO) (see section 4.8) is a restricted form of the PARAM - it is always understood as a string (i.e. datatype="char" and arraysize="*" are implied).
The ordered list of Fields at the top of the table thus provides a template for a Row object (also called a record). The template allows interpretation of the data in the Row. The record is a set of Cells, with the number and order of Cells the same for each Row, and the same as the number of Fields defined in the Metadata.
In VOTable, there is generally no advance specification of the number of rows in the table: this is to allow streaming of large tables, as discussed above. However, if the number of rows is known, it may be specified in a dedicated nrows attribute.
From Version 1.1, columns may be logically grouped, so that it is possible to define table substructures made of column associations. Such an association is declared as a GROUP, which typically contains column references (FIELDref) and associated parameters (PARAM).
| datatype | Meaning | FITS | Bytes | Notes |
| "boolean" | Logical | "L" | 1 | |
| "bit" | Bit | "X" | * | |
| "unsignedByte" | Byte (0 to 255) | "B" | 1 | |
| "short" | Short Integer | "I" | 2 | |
| "int" | Integer | "J" | 4 | |
| "long" | Long integer | "K" | 8 | |
| "char" | UTF-8 byte | "A" | 1 | |
| "unicodeChar" | UTF-16 code unit | 2 | deprecated | |
| "float" | Floating point | "E" | 4 | |
| "double" | Double | "D" | 8 | |
| "floatComplex" | Float Complex | "C" | 8 | |
| "doubleComplex" | Double Complex | "M" | 16 |
Each Cell is composed from Primitives, each of which is a datatype of fixed-length binary representation, as listed in Table 1. Cells may consist of a single Primitive (this is the default), or of an array (which may be multidimensional) of Primitives (see section 2.2).
Except for the Bit type, each primitive has the fixed length in bytes given in Table 1. Bit scalars and arrays are stored in the minimum number of bytes feasible (so that b bits take the integer part of (b+7)/8 bytes). These primitives are described in more detail in section 6.
Character and string data should be encoded using the "char" type, which from VOTable 1.6 supports Unicode. Note that the primitive size of one byte refers to a single UTF-8-encoded byte, not to a single character. Since UTF-8 is a variable-width encoding, a character may require multiple bytes, and for arrays the string length (length in characters) and primitive count (length in bytes) will in general differ. 7-bit ASCII characters are however all encoded as a single byte in UTF-8, so in the case of ASCII characters, which were required for this datatype in earlier VOTable versions, the primitive and character count are equal. This means that a single (non-array) "char" is capable of storing a 7-bit ASCII character only. Strings must not be truncated mid-character, so truncation of a string to fit a fixed-length char array may result in unused bytes at the end of the array. The character count as distinct from the primitive count may optionally be recorded by the width attribute, see section 4.2.
For historical reasons the "unicodeChar" type can also be used for character storage, but from VOTable 1.6 this type is deprecated. For this type the primitive size of two bytes corresponds to a 2-byte UTF-16 code unit. Only characters in the Unicode Basic Multilingual Plane, which all have 2-byte representations, are permitted for this datatype, so that the primitive count matches the character count. This is identical to the obsolete UCS-2 encoding, which was the description used in earlier VOTable versions.
Note that strings are not a primitive type: strings are represented in VOTable as an array of character storage units (usually UTF-8 bytes).
A table cell can contain an array of a given primitive type, with a fixed or variable number of elements; the array may even be multidimensional. For instance, the position of a point in a 3D space can be defined by the following:
<FIELD ID="point_3D" datatype="double" arraysize="3"/>
and each cell corresponding to that definition must contain exactly 3 numbers. An asterisk (*) may be appended to indicate a variable number of elements in the array, as in:
<FIELD ID="values" datatype="int" arraysize="100*"/>
where it is specified that each cell corresponding to that definition contains 0 to 100 integer numbers. The number may be omitted to specify an unbounded array (in practice up to ≅ 2×109 elements).
A table cell can also contain a multidimensional array of a given primitive type. This is specified by a sequence of dimensions separated by the x character, with the first dimension changing fastest; as in the case of a simple array, the last dimension may be variable in length. As an example, the following definition declares a table cell which may contain a set of up to 10 images, each of 64x64 bytes:
<FIELD ID="thumbs" datatype="unsignedByte" arraysize="64x64x10*"/>
Strings, which are defined as a sequence of characters, can therefore be represented in VOTable as a fixed- or variable-length array of character elements:
<FIELD name="unboundedString" datatype="char" arraysize="*"/>
Note that the arraysize for a datatype="char" array corresponds to the storage length, that is the number of UTF-8 bytes required to store string values, and not necessarily the number of characters in the string. So a FIELD with datatype="char" and arraysize="4" could store the value "LCDM" but not "ΛCDM", since the character Λ (Lambda) is encoded in two bytes (0xCE, 0x9B) by UTF-8 while the ASCII characters L, C, D, M are encoded in one byte. As explained in section 4.2 the number of characters MAY be reported by the width attribute.
A 1D array of strings can be represented as a 2D array of characters, but given the logic above, it is possible to define a variable-length array of fixed-storage-length strings, but not a fixed-length array of variable-storage-length strings. To encode or decode a multi-dimensional char array it is necessary first to represent it as a sequence of UTF-8 bytes in order to determine the byte sequence representing each fixed-storage-length string.
Note: arraysize should be present if, and only if, each table cell for the FIELD is intended to be treated as an array. arraysize="1" should not be used, as it is interpreted differently by different clients at this point. If a future VOTable specification re-encourages its use, arraysize="1" will mean "array of length 1".
VOTable is closely compatible with the FITS Binary Table format. Henceforth, we shall abbreviate "FITS Binary Table and its Conventions" simply by the word "FITS". Given a FITS file that represents a binary table, the header may be converted to VOTable, with a pointer to the original file, or with the original file included directly in VOTable. Since the original file is still present, it is clear that no data has been lost. A PARAM element can be used to hold any FITS keyword with its value and comment string.
We might ask two more significant questions, about how much of the FITS header and data can be represented in VOTable. The answer is that there is considerable overlap.
For instance, the recommended formatting of the data for an edition of the data is expressed by the non-mandatory TDISP keyword: for example F12.4 means 12 characters are to be used, and 4 decimal places. This has been converted in VOTable as the attributes width and precision which, connected with datatype, are semantically identical to the TDISP keyword.
FITS has complex semantics, with many conventions (see e.g. the Registry of FITS Conventions1) which have been developed mainly to be able to cope with the increasing complexity of astronomical instrumentation. In the frame of the Virtual Observatory the complexity is described by means of data models, and from its version 1.1, VOTable can refer to these data models by means of the utype attribute described in section 4.6.
VOTable supports separating of data from metadata and the streaming of tables, and other ideas from modern distributed computing. It bridges two ways to express structured data: XML and FITS. It uses UCDs - see section 4.5) to formally express the semantic content of a parameter or field. It has the hierarchy and flexibility of XML: using GROUP elements introduced in version 1.1, columns in a VOTable can be grouped in arbitrarily complex hierarchies; and the ID attribute can be used in XML to enable what are essentially pointers. FITS does not handle Unicode (extended alphabet) characters.
The overall VOTable document structure is described and controlled by its XML Schema (Thompson and Beech et al., 2004). The schema for VOTable version 1.6 is given in appendix B of this document. It can also be retrieved from http://www.ivoa.net/xml/VOTable/votable-1.6.xsd.
A VOTable document consists of a single all-containing element called VOTABLE, which contains descriptive elements and global definitions (DESCRIPTION, GROUP, PARAM, INFO), followed by one or more RESOURCE elements. Each Resource element contains zero or more TABLE elements, and possibly other RESOURCE elements.
The TABLE element, the actual heart of VOTable, contains a description of the columns and parameters (described in section 4) followed by the data values (described in section 5).
As the root element, VOTABLE has attributes which specify the VOTable version number and XML namespaces used in the document. For VOTable 1.6, the VOTABLE element MUST define version="1.6". All VOTable 1.6 elements come from the namespace http://www.ivoa.net/xml/VOTable/v1.3. It is recommended to bind the empty namespace prefix to this URI, as in
|
Note that starting with VOTable 1.3, the namespace URI for VOTable will remain fixed at http://www.ivoa.net/xml/VOTable/v1.3 until the next major version as discussed in Harrison and Demleitner et al. (2018). As per IVOA recommendations, this namespace URI will always redirect to the latest recommended schema for VOTable version 1.x.
VOTable consumers doing schema validation are free to use either this latest recommended schema or the version-specific schema relevant to the VOTable version. So, while instance documents may include the schemaLocation attribute, consumers are not required to honor it.
Documents claiming to represent VOTables must validate against the relevant version of the VOTable schema without error. Notice that the validation is a necessary, but not sufficient, condition for correctness.
This simple example of a VOTable document lists 3 galaxies with their position, velocity and error, and their estimated distance.
<?xml version="1.0" encoding="UTF-8"?> <VOTABLE version="1.6" xmlns="http://www.ivoa.net/xml/VOTable/v1.3"> <RESOURCE name="myFavouriteGalaxies"> <COOSYS ID="sys" equinox="J2000" epoch="J2000" system="FK5"/> <TABLE name="results"> <DESCRIPTION>Velocities and Distance estimations</DESCRIPTION> <PARAM name="Telescope" datatype="float" ucd="phys.size;instr.tel" unit="m" value="3.6"/> <FIELD name="RA" ID="col1" ucd="pos.eq.ra;meta.main" datatype="float" width="6" precision="2" unit="deg" ref="sys"/> <FIELD name="Dec" ID="col2" ucd="pos.eq.dec;meta.main" datatype="float" width="6" precision="2" unit="deg" ref="sys"/> <FIELD name="Name" ID="col3" ucd="meta.id;meta.main" datatype="char" arraysize="8*"/> <FIELD name="RVel" ID="col4" ucd="spect.dopplerVeloc" datatype="int" width="5" unit="km/s"/> <FIELD name="e_RVel" ID="col5" ucd="stat.error;spect.dopplerVeloc" datatype="int" width="3" unit="km/s"/> <FIELD name="R" ID="col6" ucd="pos.distance;pos.heliocentric" datatype="float" width="4" precision="1" unit="Mpc"> <DESCRIPTION>Distance of Galaxy, assuming H=75km/s/Mpc</DESCRIPTION> </FIELD> <DATA> <TABLEDATA> <TR> <TD>010.68</TD><TD>+41.27</TD><TD>N 224</TD><TD>-297</TD><TD>5</TD><TD>0.7</TD> </TR> <TR> <TD>287.43</TD><TD>-63.85</TD><TD>N 6744</TD><TD>839</TD><TD>6</TD><TD>10.4</TD> </TR> <TR> <TD>023.48</TD><TD>+30.66</TD><TD>N 598</TD><TD>-182</TD><TD>3</TD><TD>0.7</TD> </TR> </TABLEDATA> </DATA> </TABLE> </RESOURCE> </VOTABLE>
This simple VOTABLE document shows a single RESOURCE made of a single TABLE; the table is made of 6 columns, each described by a FIELD, and has one additional PARAM parameter (the Telescope). The actual rows are listed in the DATA part of the table, here in XML format (introduced by TABLEDATA); each cell is marked by the TD element, and follow the same order as their FIELD description: RA, Dec, Name, RVel, e_RVel, R.
Most of the elements defined by VOTable may have or have to have names, like a RESOURCE, a TABLE, a PARAM or a FIELD. The content of the name attribute is defined as a token XML type, that is a string of characters where the blanks and spaces are not meaningful (no leading or trailing spaces, no multiple spaces): name="NVSS flux(1.4GHz)" represents therefore a valid name.
The ID and ref attributes are defined as XML types ID and IDREF respectively. This means that the contents of ID is an identifier which must be unique throughout a VOTable document, and that the contents of the ref attribute represents a reference to an identifier which must exist in the VOTable document. In other terms, if ref="myStar" is found in one element, there must exist an element in the same document with the ID="myStar" attribute. The XML standard moreover specifies that an ID type is a string beginning with a letter or underscore (_), followed by a sequence of Unicode letters, digits, or any of the punctuation characters . (dot), - (dash) or _ (underscore). The : (colon) is reserved for namespace use and should be avoided. Therefore ID="1" is not valid, but ID="_1" or ID="ref.1" are both valid.
The ID attribute is therefore required in the elements which have to be referenced, but the elements having an ID attribute do not need to be referenced.
The relative position of an ID and its corresponding reference(s) may have an impact on the performance or functionality of streaming parsers. For this reason, earlier versions of VOTable recommended placing the ID attribute before any references to it, but there may be cases where the opposite is more appropriate. In practical terms, no requirement has ever been placed on the ordering of an ID and its references, so VOTable creators are free to use either order and parsers/consumers should handle either order.
While the ID attribute has to be unique in a VOTable document, the name attribute need not. It is however recommended, as a good practice, to assign unique names within a TABLE element. This recommendation means that, between a <TABLE> and its corresponding closing </TABLE> tag, name attributes of FIELD, PARAM and optional GROUP elements should be all different.
The VOTABLE element may contain definitions consisting of a DESCRIPTION, followed by any mixture of parameters and informative notes eventually structured in groups. These elements represent values which are meaningful over all tables included in a VOTABLE document - definitions specific to a RESOURCE (section 3.6) or a TABLE (section 3.8) are better placed within their most appropriate element.
Note that version 1.0 of VOTable required the usage of a DEFINITIONS element holding the VOTable global definitions - this usage is deprecated since version 1.1.
The COOSYS element defines a celestial coordinate system, to which the components of a position on the celestial sphere refer. It has the following attributes, all of them (syntactically) optional:
As that vocabulary can be extended at any time, clients should fail gracefully when they encounter unknown reference frames. Up through VOTable 1.4, these identifiers were defined in the VOTable schema, and some systems had different identifiers. These legacy identifiers are still in the vocabulary, but they are deprecated. Clients should use the vocabulary (see sect. 3 of Demleitner and Gray et al. (2023) for how to do that without RDF tooling) to map the legacy identifiers to current identifiers.
Also note that COOSYS may be deprecated in the future in favor of a more generic way of describing the conventions used to define the positions of the objects studied in the enclosed tables.
A COOSYS element referenced via a ref attribute SHOULD appear before the element that references it.
The TIMESYS element (introduced in VOTable 1.4) defines metadata for temporal coordinates. To reference the time system defined by a TIMESYS element, FIELDs (and possibly PARAMs) MUST reference the TIMESYS using the VOTable ref attribute.
If a FIELD or PARAM represents a time-like quantity but does not reference a TIMESYS element, then no assertion is made about its time system. A TIMESYS element referenced via a ref attribute MUST appear before the element that references it.
TIMESYS has the following attributes:
This attribute is mandatory.
This attribute is mandatory.
The example below shows a VOTable in which each row would have an observation time, a flux, and a magnitude. The observation time values are given in days since Julian Date 2455197.5 (the time origin for the Gaia observatory) in the Barycentric Coordinate Time (TCB) time scale, with the reference position being the barycenter of the solar system.
In the example, the TIMESYS element describes that time system. The TIMESYS ID value needs to be unique within the document so that it can be referenced by FIELDs or PARAMs. Then the obs_time FIELD indicates that its values should be interpreted in that time system by referring back to the TIMESYS element using ref="time_frame".
Similarly, the COOSYS element defines the coordinate system, and is referred to by the ra and dec PARAM elements. Note that since the sky position is defined by PARAMs instead of FIELDs, the same sky position applies to each row of the TABLE without the values appearing in TD elements.
Further (non-normative) information on best practices and usage patterns for TIMESYS can be found in Demleitner and Nebot et al. (2018).
<VOTABLE version="1.5" xmlns="http://www.ivoa.net/xml/VOTable/v1.3"> <RESOURCE> <COOSYS ID="system" epoch="J2015.5" system="ICRS" refposition="BARYCENTER"/> <TIMESYS ID="time_frame" refposition="BARYCENTER" timeorigin="2455197.5" timescale="TCB"/> <TABLE name="ts_data"> <FIELD datatype="double" name="obs_time" ucd="time.epoch" unit="d" ref="time_frame"/> <FIELD datatype="float" name="flux" ucd="phot.flux;em.opt.V" unit="s**-1"/> <FIELD datatype="float" name="mag" ucd="phot.mag;em.opt.V" unit="mag"/> <FIELD datatype="float" name="flux_error" ucd="stat.error;phot.flux;em.opt.V" unit="s**-1"/> <PARAM datatype="double" name="ra" ucd="pos.eq.ra" unit="deg" value="45.7164887146879" ref="system"/> <PARAM datatype="double" name="dec" ucd="pos.eq.dec" unit="deg" value="1.18583048057467" ref="system"/> <DATA> <TABLEDATA> <TR> <TD>1821.2846388435</TD> <TD>168.358</TD> <TD>20.12281560517953</TD> <TD>8.71437</TD> </TR> </TABLEDATA> </DATA> </TABLE> </RESOURCE> </VOTABLE>
A VOTable document contains one or more RESOURCE elements, each of these providing a description and the data values of some logically independent data structure.
Each RESOURCE may include the descriptive element DESCRIPTION, followed by a mixture of INFO, GROUP and PARAM elements; it may also contain LINK elements to provide URL-type pointers that give further information.
The main component of a RESOURCE is typically one or more TABLE elements - in other words a RESOURCE is basically a set of related tables. The RESOURCE is recursive (it can contain other RESOURCE elements), which means that the set of tables making up a RESOURCE may become a tree structure.
A RESOURCE may have one or both of the name or ID attributes (see section 3.2); it may also be qualified by type="meta", meaning that the resource is descriptive only, i.e. does not contain any actual data: no DATA element should exist in any of its sub-elements. A RESOURCE without this attribute may however have no DATA sub-element.
For example, a RESOURCE qualified by type="meta" can be used to transmit MIVOT (Model Instances in VOTables) annotations (Michel and Cresitello-Dittmar et al., 2023). MIVOT defines a syntax to map VOTable contents to any model serizalized in VO-DML (Lemson and Laurino et al., 2018). It operates as a bridge between models and data that associates VOTable metadata to data model entities, possibly adding advanced metadata not representable in plain VOTable. MIVOT annotations have their own XMLnamespace. The VOTable schema allows MIVOT, and any elements from a foreign namespace, in a RESOURCE.
Finally, the RESOURCE element may have a utype attribute to link the element to some external data model (introduced in version 1.1, see section 4.6).
The role of the LINK element is to provide pointers to external resources through a URI. In VOTable, the LINK element may be part of a RESOURCE, TABLE, GROUP, FIELD or PARAM element.
The linked URI is given by the href attribute, and the nature of the link is indicated by the content-role attribute. The URI should ideally be dereferenceable, but this is not an absolute requirement, and appropriate use of the URI depends on the content-role. This document defines two values for the content-role attribute:
<LINK content-role="type" href="https://www.ivoa.net/rdf/uat#parallax"/>
A content-role should be provided for all LINK elements, but if it is absent, a doc-like role may be assumed. Other values of the content-role attribute may be defined as appropriate outside of this VOTable specification, for instance by the Semantics Working Group or as part of other standards that make use of VOTable.
In addition the LINK element may announce the RFC 2046 media type of the data it references with a content-type attribute (e.g. content-type="image/fits"). Although this might be overridden by metadata received during the retrieval operation (e.g. the HTTP Content-Type header) it can serve as a hint to the application about what to expect.
In the Astrores format, from which VOTable is derived, there are additional semantics for the LINK element; the href attribute is used as a template for creating URLs. This behavior is explained in appendix A.1, and it represents a possible extension of VOTable.
The TABLE element represents the basic data structure in VOTable; it comprises a description of the table structure (the metadata) essentially in the form of PARAM and FIELD elements (detailed in section 4), followed by the values of the described fields in a DATA element (detailed in section 5).
The TABLE element is always contained in a RESOURCE element: in other words any TABLE element has a single parent made of the RESOURCE element in which the table is embedded.
The TABLE element contains a DESCRIPTION element for descriptive remarks, followed by a mixed collection of PARAM, FIELD or GROUP elements which describe a parameter (constant column), a field (column) or a group of columns respectively. PARAM and FIELD elements are detailed in section 4, and the GROUP element is presented in section 4.9.
Furthermore the TABLE element may contain LINK elements that provide URL-type pointers, exactly like the LINK elements existing within a RESOURCE element (see section 3.7).
The last element included in a TABLE is the optional DATA element (see section 5): a table without any actual data is quite valid, and is typically used to supply a complete description of an existing resource e.g. for query purposes.
The TABLE element may have the naming attributes name and/or ID (see section 3.2). A TABLE may also have a ref attribute referencing the ID of another table previously described, which is interpreted as defining a table having a structure identical to the one referenced: this facility avoids a repetition of the definition of tables which may be present many times in a VOTable document. It is recommended that the ref attribute references an empty table (i.e. a table without a DATA part), which avoids any ambiguity about the referencing.
Finally, the TABLE element may have a utype and ucd attribute to specify the table semantics, similarly to the FIELD and PARAM elements (see section 4.1).
The atoms of the table structure are represented by FIELD and PARAM elements, where FIELD represents the description of an actual table column, while PARAM supplies a value attached to the table, like the Telescope in the example of section 3.1. A PARAM may be viewed as a FIELD which keeps a constant value over all the rows of a table, and the only difference in the set of attributes of the two elements is the existence of a value attribute in a PARAM which does not exist in a FIELD.
The FIELD elements describe the actual columns of the table; the order in which the FIELDs are declared is important, as this order must be the same one as the order of the columns in section 5.
A FIELD or PARAM element may have several sub-elements, including the informational DESCRIPTION and LINK elements (several descriptions and titles are possible, see appendix A.7); it may also include a VALUES element that can express limits and ranges of the values that the corresponding cell can contain, such as minimum (MIN), maximum (MAX), or enumeration of possible values (OPTION).
In addition, in the PARAM element only:
The VOTable format is meant for transferring, storing, and processing tabular data, and is not intended for presentation purposes: therefore (in contrast to Astrores) we generally avoid giving rules on presentation, such as formatting. Inevitably however at least some of the data will be presented - either as actual tables, or in forms or graphs, etc. Two attributes were retained for this purpose:
When used with datatype="char" arrays the width attribute is interpreted as an upper bound for the array length in characters, i.e. Unicode code points. This value is distinct from the arraysize attribute which gives the array length in UTF-8-encoded bytes. VOTable producers are not required to supply the width attribute for such columns, but if known the string length can be useful to clients for e.g. resource allocation. In the case of multi-dimensional char arrays the value refers to the number of characters in each string element.
The xtype attribute expands the basic datatype primitives (in Table 1) representing the storage units which are valid in any of the VOTable serializations, and corresponds therefore exactly to the FITS definitions. It fills the gap between the datatypes known by FITS and those required to express queries (Astronomical Data Query Language or ADQL, Mantelet and Morris et al. (2023)) and their results in tabular form (Table Access Protocol or TAP, Dowler and Rixon et al. (2010)).
As an example, setting xtype="timestamp" instructs VOTable parsers to interpret a string as a timestamp (an instant in an absolute time frame), materialized by a UTC date/time string following the ISO-8601 standard (YYYY-MM-DDThh:mm:ss eventually followed by a decimal point and fractions of seconds). Supporting parsers might then expose the corresponding values in whatever way appropriate for such timestamps in the host language. VOTables software does not need to interpret xtypes, but it should preserve them when doing round-trips.
The IVOA recommendation Data Access Layer Interface DALI (Dowler and Demleitner et al., 2017) defines the common values of xtype and the literals of conforming column values.
The quantities in a column of the table may be expressed in some physical unit, which is specified by the unit attribute of the FIELD. The syntax of the unit string SHOULD conform to the VOUnits specification, Gray and Cecconi et al. (2023); this requires a string without blanks or spaces where multiplication is indicated by the symbol ".", division by the symbol "/" and exponentiation by the symbol "**". Examples are unit="m**2" for m2, unit="cm**-2.s**-1.keV**-1" for cm−2s−1keV−1, or unit="m/s" for m s−1.
The Unified Content Descriptors (UCD) can be viewed as a hierarchical glossary of the scientific meanings of the data contained in the astronomical tables. Two versions of UCDs have been developed: the initial version (UCD1) created at CDS, which uses atomic words separated by underscores (e.g. POS_EQ_RA_MAIN); and a more flexible one, UCD1+ (Cecconi and Louys et al., 2023), developed in the frame of the IVOA Semantics Working Group, which uses a reduced vocabulary of dot-separated atoms which can be combined with semi-colons (e.g. pos.eq.ra;meta.main). UCD1+ usage is recommended, but applications using the older vocabulary are still acceptable in this version of VOTable.
A few typical examples of UCD1+ definitions are:
| "phot.mag;em.opt.B" | Blue magnitude |
| "src.orbital.eccentricity" | Orbital eccentricity |
| "time.period;stat.median" | Median Value of the Period |
| "instr.det.qe" | Detector's Quantum Efficiency |
Note that the utype attribute is not an XML QName. This means that even when utypes are written with colons (e.g., adhoc:service), whatever is in front of the colon has no relationship to XML namespace URIs. In other words, utypes are opaque strings (except, where defined that way by standards using them, for case-folding).
The VALUES element of the FIELD is designed to hold subsidiary information about the domain of the data. For instance, in the example (section 3.1) we could rewrite the RA field definition as:
<FIELD name="RA" ID="col1" ucd="pos.eq.ra;meta.main" datatype="float" width="6" precision="2" unit="deg"> <VALUES ID="RAdomain"> <MIN value="0"/> <MAX value="360" inclusive="no"/> </VALUES> </FIELD>
The scope of the domain described by the VALUES element (and by its MIN, MAX and OPTION sub-elements) can be qualified by type="actual", if it is valid only for the data enclosed in the parent TABLE; the default type="legal" qualification specifies the generic domain of valid values, as in the RAdomain in the example above where the interval [0,360[ is specified.
The VALUES element may contain MIN and MAX elements, and it may contain OPTION elements; the latter may itself contain more OPTION elements, so that a hierarchy of keyword-values pairs can be associated with each field. Note that only a single pair MIN / MAX is possible, whereas many OPTION elements may be used to qualify the domain described by the VALUES element. The domain may therefore be defined as a single interval, or as a set of individual values. Although the schema does not forbid all three MIN, MAX and OPTION sub-elements simultaneously, such usage is considered as bad practice and is discouraged.
All three MIN, MAX and OPTION sub-elements store their value corresponding to the minimum, maximum, or "special value" in a value attribute. MIN and MAX elements can have an inclusive attribute to specify whether the value quoted belongs to the domain or not, and the OPTION element can have a name attribute to describe the "special" quoted value.
Unless a FIELD has a nonempty xtype, the value of the value attribute always is a single TABLEDATA literal of the datatype and gives a global limit for all cells of the array; arrays are conceptually homogeneous in VOTable. When the parent of a VALUES element does have an xtype, special rules apply; clients should only try to parse limits of xtyped fields when they know the xtype. For instance, with:
<FIELD name="flux" datatype="float" unit="Jy"> <VALUES><MIN value="0"/><MAX value="1e-4"/></VALUES> </FIELD> <FIELD name="fluxes" datatype="float" arraysize="30" unit="Jy"> <VALUES><MIN value="0"/><MAX value="1e-4"/></VALUES> </FIELD> <FIELD name="CIRCLE" datatype="float" arraysize="3" xtype="circle"> <VALUES><MAX value="312.5 -41 2"/></VALUES> </FIELD>
both the single value of flux and all items in the fluxes array are declared as being between 0 and 10−4, and clients could, for instance, raise warnings if they are not. In the last example, CIRCLE, clients not familiar with xtype="circle" would ignore the MAX declaration. Clients familiar with this xtype's particular interpretation of MAX would learn about a spatial coverage of a spherical circle with radius two degrees around the point (312.5°,−41°); see the SODA specification (Bonnarel and Dowler et al., 2017) for the context of this particular example.
The VALUES element may also have a null attribute to define a non-standard value that is used to specify "non-existent data" - for example null="-32768". When this value is found in the corresponding data, it is assumed that no data exists for that table cell; the parser may also choose to use this when unparsable data is found, and the null value will be substituted instead. The value of the null attribute must follow the same rules as the TABLEDATA serialization for the appropriate datatype described in section 6, and may never contain an array value. This mechanism is only intended for use with integer types; it should not be used for floating point types, which can use NaN instead.
This mechanism for representing null values is required for integer columns in the BINARY serialization. Since VOTable 1.3 however other mechanisms are available for representing null values in the TABLEDATA and BINARY2 serializations. Representation of nulls using the VALUES element and otherwise is discussed further in section 5.5.
Finally the ref attribute of a VALUES element can be used to avoid a repetition of the domain definition, by referring to a previously defined VALUES element having the referenced ID attribute. When specified, the ref attribute completely defines the domain without any other element or attribute, e.g. <VALUES ref="RAdomain"/>.
INFO is meant to convey informative details about the generation of the VOTABLE document. It may be present at the beginning or end of VOTABLE or RESOURCE elements, or at the end of a TABLE. Typical uses of INFO include error reports, or explanations about choices made by the data processing system which generates the VOTable document.
The GROUP element is used to group together a set of FIELDs and PARAMs which are logically connected, like a value and its error. The FIELDs are always defined outside any group, and the GROUP designates its member fields via FIELDref elements.
A simple example of a group made of the velocity and its error, based on the example of section 3.1, can be the following:
<GROUP name="Velocity"> <DESCRIPTION>Velocity and its error</DESCRIPTION> <FIELDref ref="col4"/> <FIELDref ref="col5"/> </GROUP>
The GROUP element can have the name, ID, ucd, utype and ref attributes. It can include a DESCRIPTION, and any mixture of FIELDreferences, PARAMeters, PARAMreferences and other GROUPs. PARAMref is a logical definition of a parameter that refers to a PARAM element defined elsewhere in the parent TABLE or RESOURCE; similarly the FIELDref element defined by referring to a FIELD element defined elsewhere in the parent TABLE. The recursivity of the GROUP element enables a definition of arbitrarily complex structures.
The possibility of adding PARAMeters in groups also introduces a possibility of associating parameter(s) to accurately describe the context of the data stored in the table. For instance, it is possible to associate the actual frequency of a radio survey with a table of flux measurements using the following declaration:
<FIELD name="Flux" ID="col4" ucd="phot.flux;em.radio.200-400MHz" datatype="float" width="6" precision="1" unit="mJy"/> <FIELD name="e_Flux" ID="col5" datatype="float" width="4" precision="1" ucd="stat.error;phot.flux;em.radio.200-400MHz" unit="mJy"/> <GROUP name="FluxGroup" ucd="phot.flux;em.radio.200-400MHz"> <DESCRIPTION>Flux measured at 352MHz</DESCRIPTION> <PARAM name="Freq" ucd="em.freq" unit="MHz" datatype="float" value="352"/> <FIELDref ref="col4"/> <FIELDref ref="col5"/> </GROUP>
Similarly, GROUP can be used to associate several parameters to one or several FIELDs. For example, a filter may be characterized by the central wavelength and the FWHM of its transmission curve, or several parameters of an instrument setup may be described.
With a simple naming convention, the GROUP element may also specify some properties of the tables included in a VOTable document when a TABLE is viewed as a relation (part of a a relational database):
Similar conventions could be added for the existence of indexes, unique values, etc.
While the bulk of the metadata of a VOTable document is in the FIELD elements, the data content of the table is in a single DATA element. The data is organized in "reading" order, so that the content of each row appears in the same order as the order of the FIELD definitions.
Each DATA part of the VOTable document can be viewed as a stream coming out of a pipeline. The abstract table is first serialized by one of several methods, then it may be encoded for compression or other reasons. The result may be embedded in the XML file (local data), or it may be remote data.
Figure 2 shows how the abstract table is rendered into the VOTable document. First the data is serialized, either as XML, a FITS binary table, or the VOTable Binary format. This data stream may then be encoded, perhaps for compression or to convert binary to text. Finally, the data stream may be put in a remote file with a URL-type pointer in the VOTable document; or the table data may be embedded in the VOTable.
The serialization elements and their attributes are described in the next sections.
The TABLEDATA element is a way to build the table in pure XML, and has the advantage that XML tools can manipulate and present the table data directly. The TABLEDATA element contains TR elements, which in turn contain TD elements - i.e. the same conventions as in HTML. The number of TD elements in each TR element must be equal to the number of FIELD elements declaring the table. An example is contained in section 3.1, surrounded by the <TABLEDATA> and </TABLEDATA> delimiters.
Each item in the TD tag contains a value which must be compatible with the datatype attribute of the corresponding FIELD definition. If the value is the same as the null value for that field (see section 4.7) then the item is assumed to contain no data. Valid representations of values in a cell, depending on their datatype, are detailed in section 6. If the TD element is empty (<TD/> or <TD></TD>) the cell is considered to contain no data, i.e. to be null.
If a cell contains an array of numbers or a complex number, it should be encoded as multiple numbers separated by whitespace. However in the case of character strings (declared in the corresponding FIELD as an array of char or unicodeChar datatype), no separator should exist. Here is an example of a two-row table that has arrays in the table cells:
<TABLE> <FIELD name="aString" datatype="char" arraysize="10"/> <FIELD name="aShort" datatype="short"/> <FIELD name="varInts" datatype="int" arraysize="*"/> <FIELD name="Floats" datatype="float" arraysize="3"/> <DATA><TABLEDATA> <TR> <TD>Apple</TD> <TD/> <TD>1 2 4 8 16</TD> <TD>1.62 4.56 3.44</TD> </TR> <TR> <TD>Orange</TD> <TD>15</TD> <TD>23 -11 9</TD> <TD>2.33 4.66 9.53</TD> </TR> </TABLEDATA></DATA> </TABLE>
The first entry is a fixed-length array of 10 UTF-8 bytes; since the value being presented (Apple) is encoded in 5 bytes, this is padded with trailing blanks. The second cell is a short integer but has a null value, as indicated by the empty TD element. The third cell contains a variable-length array of integers. The last cell contains a fixed-length array of three floats.
A special notice should be mentioned about the significance of white space in a table cell (the term white space designates the characters space [U+0020], tab [U+0009], newline [U+000A], carriage-return [U+000D]): while for numeric data types the amount of white spaces does not matter (the elements of an array of numbers may for instance be written on several lines), the white space is significant for "char" or "unicodeChar" datatypes, and for instance <TD>Apple</TD> and <TD> Apple</TD> are not identical.
The FITS format for binary tables (Hanisch and Farris et al., 2001) is in widespread use in astronomy, and its structure has had a major influence on the VOTable specification. Metadata is stored in a header section, followed by the data. The metadata is essentially equivalent to the metadata of the VOTable format. One important difference is that VOTable does not require specification of the number of rows in the table, an important advantage if the table is being created dynamically from a stream.
The VOTable specification does not define the behavior of parsers with respect to this doubling of the metadata. A parser may ignore the FITS metadata, or it may compare it with the VOTable metadata for consistency, or other possibilities.
The following code shows a fragment that might have been created by a FITS-to-VOTable converter. Each FITS keyword has been converted to a PARAM, and the data itself is remotely stored and gzipped at an FTP site:
<RESOURCE>
<INFO name="HISTORY" value="Virtual Telescope observation made in 2002"/>
<PARAM name="EPOCH" datatype="float" value="1999.987">
<DESCRIPTION> Original Epoch of the coordinates</DESCRIPTION>
</PARAM>
<PARAM name="TELESCOP" datatype="char" arraysize="*" value="VTel" />
<TABLE>
<FIELD (insert field metadata here) />
<DATA><FITS extnum="2">
<STREAM encoding="gzip" href="ftp://archive.cacr.caltech.edu/myfile.fit.gz"/>
</FITS></DATA>
</TABLE>
</RESOURCE>
The FITS file may contain many data objects (known as extensions, numbered from 1 up, the main header being numbered 0), and the extnum attribute allows the VOTable to point to one of these.
The binary format is intended to be easy to read by parsers, so that additional libraries are not required. It is just a sequence of bytes with the length of each sequence corresponding to the datatype and arraysize attributes of the FIELD elements in the metadata. The binary format consists of a sequence of records with no header bytes, no alignment considerations, and no block sizes. The order of the bytes in multi-byte primitives (e.g. integers, floating-point numbers) is Most Significant Byte first, i.e., it follows the FITS convention.
Table cells may contain arrays of primitive types, each of which may be of fixed or variable length. In the former case, the number of bytes is the same for each instance of the item, as specified by the arraysize attribute of the FIELD. If all the fields have a fixed arraysize, then each record of the binary format has the same length (the sum of arraysize times the length in bytes of the corresponding datatype).
Variable-length arrays of primitives are preceded by a 4-byte integer containing the number of items of the array. The parser can then compute the number of bytes taken by the variable-length array by multiplying the size and number of the primitives.
The way the stream of bytes is arranged for the data of the example in section 5.1 is illustrated in Figure 3. In this case the second column must be declared like this:
<FIELD name="aShort" datatype="short"> <VALUES null="99"/> </FIELD>to indicate a magic value representing nulls, since no equivalent of the empty TD element is available for the BINARY serialization (see section 5.5).
The BINARY serialization has been available in all versions of VOTable. From VOTable 1.3 however, the alternative BINARY2 serialization is an alternative, providing more straightforward null-flagging capabilities. In VOTable 1.3 and above BINARY remains a legal serialization, but for most purposes VOTable producers are advised to use BINARY2 instead.
The BINARY2 format, introduced at VOTable 1.3, is the same as BINARY, but with null entries flagged explicitly rather than identified by their values. The byte stream contains one additional bit for each table cell indicating whether that cell's value is to be considered null or not.
The byte content for each row consists of zero or more bytes containing a null value flag for each cell in the row, followed by the bytes for the BINARY serialization as described in the previous subsection. The null flags are stored as exactly one bit per table column, and the number of flag bytes is the smallest required for this purpose; the number of flag bytes per row for an N-column table will therefore be the integer part of (N+7)/8. The most significant bit of the first flag byte corresponds to the first column, the second most significant bit of the first flag byte to the second column, the most significant bit of the second flag byte to the ninth column, and so on. A set (1) bit indicates that the corresponding cell is null, and an unset (0) bit indicates that its value is not null. Unused bits will be at the less-significant end of the final flag byte, and shall be unset (0).
It is recommended, but not required, that a cell value flagged as null is filled with the NaN value for floating point or complex datatypes, and zero-valued bytes for other datatypes. It is particularly recommended that a variable length array cell value flagged as null is represented as 4 zero-valued bytes, indicating a zero-length value.
The way the stream of bytes is arranged for the data of the example in section 5.1 is illustrated in Figure 4.
VOTable provides two approaches to representing null values in data.
The first approach makes use of the VALUES element's null attribute to indicate that whenever a particular "magic" value is encountered in a column's data, that entry should be considered as null. This magic value must represent a legal scalar value for the column's datatype, for instance in the case of datatype="unsignedByte" it must be an integer in the range 0-255. This approach, inherited from FITS, works in the same way for all of the defined VOTable serializations. However it can present difficulties when generating VOTables, since the magic value must be distinct from all actual data values in the column, and must be chosen before the column data has been written, since the FIELD element precedes the DATA.
The second approach, introduced at VOTable 1.3, is to mark null values using some mechanism external to the data itself, and it works differently for the different serializations. In the TABLEDATA serialization an empty TD element signals a null value, and in the BINARY2 serialization a separate null-ness flag is provided for each cell. The BINARY and FITS serializations do not support this approach at all. It should be noted that when using this approach, unlike with magic values, the different serializations do not have identical capabilities for representing data, so that lossless round-tripping between serializations is not always possible.
Some other subtleties concerning null values should also be mentioned:
As a result of the serialization, the table has been converted to a byte stream, either text or binary. If the TABLEDATA serialization is used, then the table is represented as XML tags directly embedded in the document, and conventional tools can be used to encode the entire XML document. However, VOTable also provides limited encoding of its own. A VOTable document may point to a remote data resource that is compressed; rather than decompressing before sending on the wire, it can be dynamically decoded by the VOTable reader. We might also use the encoding facilities to convert a binary file to text (through base64 encoding), so that binary data can be used in the XML document.
In this version of VOTable, it is not possible to encode individual columns of the table: the whole table must be encoded in the same way. However, the possibility of encoding selected table cells is being examined for future versions of VOTable (see appendix A.5).
In order to use an encoding of the data, it must be enclosed in a STREAM element, whose attributes define the nature of the encoding. The encoding attribute is a string that should indicate to the parser how to undo the encoding that has been applied. Parsers should understand and interpret at least the following values:
The default value of the encoding attribute is the null string, meaning that no encoding has been applied. In future releases, we might allow more complex strings in the encoding attribute, allowing combinations of encoding filters and a way for the parser to find the software needed for the decoding.
Note that for inline streamed data (a STREAM with no href attribute) it is effectively required to use encoding="base64", since of the available options only base64 will ensure that binary data is encoded as legal XML content.
If the encoding of the data produces text, or if the serialization is naturally text-based, then it can be directly embedded into the XML document:
<DATA><BINARY>
<STREAM encoding="base64">
AAAAAj/yVZiDGSSUwFZ6ypR4yGkADwAcQV0euAAIAAJBmMzNwZWZmkGle4tBR3jVQT9ocwAA
……………………
</STREAM>
</BINARY></DATA>
However, if the data stream is very large, it may be preferable to keep the data separate from the metadata. The href attribute of the STREAM element, if present, provides a URI giving the location of the data, for example:
<STREAM href="http://server.com/mydata.dat"/><STREAM href="https://server.com/mydata.dat" expires="2004-02-29T23:59:59"/>
<STREAM href="https://server.com/mydata.dat" actuate="onLoad"/>
<STREAM href="file:///usr/home/me/mydata.dat"/>
Any dereferenceable URI may be used for the href attribute, but access to remote streams may be limited by capabilities of the parser implementation. Parsers SHOULD be able to read from URIs using common schemes such as "http", "https" and "file".
There are further attributes of the STREAM element that may be useful. The expires attribute indicates the expiration time of the data; this is useful when data are dynamically created and stored on some staging disk where files only persist for a specified lifetime and are then automatically deleted. The expires attribute expresses when a remote resource ceases to become valid, and is expressed in Universal Time in the same way as the FITS specification, itself conforming to the ISO 8601 standard.
The rights attribute expresses authentication information that may be necessary to access the remote resource. If the VOTable document is suitably encrypted, this attribute could be used to store a password.
The actuate attribute is borrowed from the XML Xlink specification, expressing when the remote link should be actuated. The default is "onRequest", meaning that the data is only fetched when explicitly requested (like a link on an HTML page), and the "onLoad" value means that data should be fetched as soon as possible (like an embedded image on an HTML page).
This section describes the primitives summarized in Table 1 and their representations in the BINARY/BINARY2 and TABLEDATA serializations (see section 5). In the following, the term "hexadigit" designates the ASCII numbers "0" to "9", or the ASCII lower- or upper-case letters "a" to "f" (i.e. a digit in a hexadecimal representation of a number).
The representation of null values is discussed in section 5.5.
The XML Schema defining a VOTable 1.6 document is available from http://www.ivoa.net/xml/VOTable/votable-1.6.xsd as well as in appendix B of this document. In this section we illustrate this XML Schema by a set of boxes describing the structure of a VOTable, and the list of attributes of each VOTable element.
Note that in case of discrepancies between the XML Schema and these diagrams, the schema is definitive.
The hierarchy of the elements existing in VOTable 1.6 is illustrated below; it uses the following conventions:
<VOTABLE> ⊕ < DESCRIPTION > ° < COOSYS > … ° < TIMESYS > … ° < INFO > … ° < PARAM > … ° < GROUP > … ⊕ <RESOURCE>… ⊕ < INFO > … </VOTABLE>
<RESOURCE> ⊕ < DESCRIPTION > ⊕ < INFO > … ° < COOSYS > … ° < TIMESYS > … ° < GROUP > … ° < PARAM > … ⊕ < LINK > … ⊕ < TABLE > … ⊕ < RESOURCE > … ⊕ < INFO > … </RESOURCE>
<TABLE> ⊕ < DESCRIPTION > ° < FIELD > … ° < PARAM > … ° < GROUP > … ⊕ < LINK > … ⊕ < DATA > ⊕ < INFO > … </TABLE>
<FIELD> ⊕ < DESCRIPTION > ⊕ < VALUES > ⊕ < LINK > … </FIELD>
<PARAM> ⊕ < DESCRIPTION > ⊕ < VALUES > ⊕ < LINK > … </PARAM>
<DATA> → <TABLEDATA> ⊕ < TR > … ⊕ <TD>… → <BINARY> ⊕ <STREAM> → <BINARY2> ⊕ <STREAM> → <FITS> ⊕ <STREAM> </DATA>
<GROUP> ⊕ < DESCRIPTION > ° < FIELDref > …(t) ° < PARAM > … ° < PARAMref > … ° < GROUP > … </GROUP> (t) only within <TABLE>
<VALUES> ⊕ < MIN > ⊕ < MAX > ⊕ < OPTION > … ° < OPTION > … </VALUES>
VOTABLE (section 3) ID version
COOSYS (section 3.4) ID equinox epoch system refposition
TIMESYS (section 3.5) ID timeorigin timescale refposition
INFO (section 4.8) ID name value xtype ref unit ucd utype
GROUP (section 4.9) ID name ref ucd utype
RESOURCE (section 3.6) ID name type utype
PARAM (section 4.1) ID unit datatype precision width xtype ref name ucd utype arraysize value
FIELD (section 4.1) ID unit datatype precision width xtype ref name ucd utype arraysize type
TABLE (section 3.8) ID name ucd utype ref nrows
FIELDref (section 4.9) ref ucd utype
PARAMref (section 4.9) ref ucd utype
STREAM (section 5.6) type href actuate encoding expires rights
FITS (section 5.2) extnum
TR (section 5.1) ID
TD (section 5.1) encoding
MIN (section 4.7) value inclusive
MAX (section 4.7) value inclusive
OPTION (section 4.7) name value
VALUES (section 4.7) ID type null ref
LINK (section 3.7) ID content-role content-type title value href action
A VOTable document should be introduced by a Media Type (sometimes called MIME type). Media type syntax is described in RFC 2045 section 5.1, and its semantics in RFC 2046. Associating a media type to a document enables the data consumer (an application or a web browser) to launch the desired application (e.g. a visualisation tool).
In the HTTP protocol (RFC 9110), the media type is the value specified by the Content-Type: header. The recommended media type describing a VOTable document is "application/x-votable+xml": the x- prefix indicates an experimental type, and is required for non-registered media types; and the +xml suffix (defined by RFC 7303 section 4.2) indicates that the type describes a specialization of XML. The following optional parameters are defined for use with this media type:
Alternatively the "text/xml" media type is acceptable for services delivering data which are expected to be visualized by humans in a browser; this media type would preferably be associated with an XSL style sheet, for a presentation of well-formatted tables. Note that use of the "text" top-level media type means that line breaks must be represented as a CRLF sequence (RFC 2046, section 4.1.1). The optional charset parameter is also defined for this media type with the same comments as above.
Any of the following Content-Type header values may therefore be used by a service producing VOTables with the TABLEDATA serialization and considered to contain datalink content:
The LINK element in Astrores (Accomazzi and Albrecht et al., 2001) contains a mechanism for string substitution, which is a powerful way of defining a link to external data which adapts to each record contained in the table DATA.
When a LINK element appears within a RESOURCE or a TABLE element, extra functionality is implied: the href attribute may not be a simple link, but instead a template for a link. If, in the example of section 3.1, we add the link
<LINK href="http://ivoa.net/lookup?Galaxy=${Name}&RA=${RA}&DE=${DE}"/>
a substitution filter is applied in the context of a particular row. For the first row of the table, the substitution would result in the URL
http://ivoa.net/lookup?Galaxy=N%20224&RA=010.68&DE=%2b41.27
Whenever the pattern ${...} is found in the original link, the part in the braces is compared with the set of ID (preferably) or name attributes of the fields of the table. If a match is found, then the value from that field of the selected row is used in place of the ${...}. If no match is found, no substitution is made. Thus the parser makes available to the calling application a value of the href attribute that depends on which row of the table has been selected. Another way to think of it is that there is not a single link associated with the table, but rather an implicitly defined new column of the table. This mechanism can be used to connect each row of the table to further information resources.
The purpose of the link is defined by the content-role attribute. The allowed values are "query" (see section A.2), "hints" for information for use by the application, and "doc" for human-readable documentation.
The column names invoked in the pattern of the href attribute of the LINK element should exist in the document to generate meaningful links. In the common case where the VOTable was generated from a query of a database and contains only some of the columns in that database, it might be necessary to include columns additional to those requested in order to ensure that the LINKS in the VOTable are operational. Such a FIELD included "by necessity" is marked with the attribute type="hidden". The primary key of a relational table is a typical example of a FIELD which would carry the type="hidden" attribute.
The metadata part included in a RESOURCE contains all the details necessary to create a form for querying the resource. The addition of a link having the action attribute can turn VOTable into a powerful query interface.
In Astrores (Accomazzi and Albrecht et al., 2001), the details on the input parameters available in queries are described by the PARAM and FIELD elements, and the syntax used to generate the actual query is described in the ASU procotol (Albrecht and Barylak et al., 1996): the FIELD or PARAM elements are paired in the form name=value, where name is the contents of the name attribute of a FIELD or PARAM, and value represents a constraint written with the ASU conventions (e.g. "<8" or "12.0..12.5" which denotes a range of values). Such pairs are appended to the action specified in the LINK element contained in the RESOURCE, separated by the ampersand (&) symbol - in a way quite similar to the HTML syntax used to describe a FORM.
A special type="no_query" attribute of the PARAM or FIELD elements marks the fields which are not part of the form, i.e. are ignored in the collection of name=value pairs.
The following is an example of a transformation of the VOTable in section 3.1 into a form interface:
<?xml version="1.0" encoding="UTF-8"?> <VOTABLE version="1.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ivoa.net/xml/VOTable/v1.3" > <RESOURCE name="myFavouriteGalaxies" type="meta"> <TABLE name="results"> <DESCRIPTION>Velocities and Distance estimations</DESCRIPTION> <GROUP utype="stc:CatalogEntryLocation"> <PARAM name="href" datatype="char" arraysize="*" utype="stc:AstroCoordSystem.href" value="ivo://STClib/CoordSys#UTC-ICRS-TOPO"/> <PARAM name="URI" datatype="char" arraysize="*" utype="stc:DataModel.URI" value="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"/> <FIELDref utype="stc:AstroCoords.Position2D.Value2.C1" ref="col1"/> <FIELDref utype="stc:AstroCoords.Position2D.Value2.C2" ref="col2"/> </GROUP> <PARAM name="-out.max" ucd="meta.number" datatype="int" value="50"> <DESCRIPTION>Maximal number of records to retrieve</DESCRIPTION> </PARAM> <FIELD name="RA" ID="col1" ucd="pos.eq.ra;meta.main" datatype="float" width="6" precision="2" unit="deg"/> <FIELD name="Dec" ID="col2" ucd="pos.eq.dec;meta.main" datatype="float" width="6" precision="2" unit="deg"/> <FIELD name="Name" ID="col3" ucd="meta.id;meta.main" datatype="char" arraysize="8*"/> <FIELD name="RVel" ID="col4" ucd="spect.dopplerVeloc" datatype="int" width="5" unit="km/s"/> <FIELD name="e_RVel" ID="col5" ucd="stat.error;spect.dopplerVeloc" datatype="int" width="3" unit="km/s"/> <FIELD name="R" ID="col6" ucd="pos.distance;pos.heliocentric" datatype="float" width="4" precision="1" unit="Mpc"> <DESCRIPTION>Distance of Galaxy, assuming H=75km/s/Mpc</DESCRIPTION> </FIELD> <LINK content-role="query" action="myQuery?-source=myGalaxies&" /> </TABLE> </RESOURCE> </VOTABLE>
Note that the RESOURCE displaying the parameters accessible for a query has the type="meta" attribute; it is also assumed that only one LINK having the content-role="query" attribute together with an action attribute exists within the current RESOURCE. The PARAM with name="-out.max" has been added in this example to control the size of the result.
A valid query generated by this VOTable could be:
myQuery?-source=myGalaxies&-out.max=50&R=10..100
FITS invented the Substring Array convention (defined in an appendix, i.e. not officially approved) which defines a separator character used to denote the end of a string and the beginning of the next one. In this convention (rA:SSTRw/ccc) the total size of the character array is specified by r, w defines the maximum length of one string, and ccc defines the separator character as its ASCII equivalent value. The possible values for the separator includes the space and any printable character, but excludes the control characters.
Such arrays of variable-length strings are frequently useful e.g. to enumerate a list of properties of an observed source, each property being represented by a variable-length string. A convention similar to the FITS one could be introduced in VOTable in the arraysize attribute, using the s followed by the separator character; an example can be arraysize="100s," indicating a string made of up to 100 characters, where the comma is used to separate the elements of the array.
Rather than requiring that all data described in the set of FIELDs are contained in a single stream which follows the metadata part, it would be possible to let the FIELD act as a pointer to the actual data, either in the form of a URI or of a reference to a component of a multipart document.
Each component of the data described by a FIELD may effectively have different requirements: while text data or small lists of numbers are quite efficiently represented in pure XML, long lists like spectra or images generate poor performances if these are converted to XML. The method available to gain efficiency is to use a binary representation of the whole data stream by means of the STREAM element - at the price of delivering data in a totally non-human readable format.
The following options would allow more flexibility in the way the various FIELDs can be accessed:
An example of a table describing a set of spectra could look like the following:
<TABLE name="SpectroLog"> <FIELD name="Target" ucd="meta.id" datatype="char" arraysize="30*"/> <FIELD name="Instr" ucd="instr.setup" datatype="char" arraysize="5*"/> <FIELD name="Dur" ucd="time.expo" datatype="int" width="5" unit="s"/> <FIELD name="Spectrum" ucd="meta.ref.url" datatype="float" arraysize="*" unit="mW/m2/nm" type="location"> <DESCRIPTION>Spectrum absolutely calibrated</DESCRIPTION> <LINK content-role="location" href="http://ivoa.spectr/server?obsno="/> </FIELD> <DATA><TABLEDATA> <TR><TD>NGC6543</TD><TD>SWS06</TD><TD>2028</TD><TD>01301903</TD></TR> <TR><TD>NGC6543</TD><TD>SWS07</TD><TD>2544</TD><TD>01302004</TD></TR> </TABLEDATA></DATA> </TABLE>
The reading program has therefore to retrieve the data for this first row by resolving the URI
http://ivoa.spectr/server?obsno=01301903
The same method could also be immediately applicable to Content-IDs which designate elements of a multipart message, using the protocol prefix cid: [RFC2111]
Note that the VOTable LINK substitution proposed in section A.1 fills a similar functionality: generate a pointer which can incorporate in its address components from the DATA part for the VOTable.
In order to keep the full VOTable document in a unique stream, VOTable 1.0 introduced the encoding attribute in the STREAM element, meaning that the data, stored as binary records, are converted into some ASCII representation compatible with the XML definitions. One drawback of this method is that the entire data contents become non human-readable.
The addition of the encoding attribute in the TD element allows the data server to decide, at the cell level, whether it is more efficient to distribute the data as binary-encoded or as edited values. The result may look like the following:
<TABLE name="SpectroLog"> <FIELD name="Target" ucd="meta.id" datatype="char" arraysize="30*"/> <FIELD name="Instr" ucd="instr.setup" datatype="char" arraysize="5*"/> <FIELD name="Dur" ucd="time.expo" datatype="int" width="5" unit="s"/> <FIELD name="Spectrum" ucd="phot.flux;em.opt" datatype="float" arraysize="*" unit="mW/m2/nm" precision="E3"/> <DATA><TABLEDATA> <TR><TD>NGC6543</TD><TD>SWS06</TD><TD>2028</TD><TD encoding="base64"> QJKPXECHvndAgMScQHul40CSLQ5ArocrQLxiTkC3XClAq0OWQKQIMUCblYFAh753QGij10BT Em9ARKwIQExqf0BqbphAieuFQJS0OUCJWBBAhcrBQJMzM0CmRaJAuRaHQLWZmkCyhytAunbJ QLN87kC26XlA1KwIQOu+d0DsWh1A5an8QN0m6UDOVgRAxO2RQM9Lx0Din75A3o9cQMPfO0C/ dLxAvUeuQKN87kCXQ5ZAjFodQH0vG0B/jVBAgaHLQI7Ag0CiyLRAqBBiQLaXjUDYcrBA8p++ QPcKPUDg7ZFAwcKPQLafvkDDlYFA1T99QM2BBkCs3S9AjLxqQISDEkCO6XlAmlYEQKibpkC5 wo9AvKPXQLGBBkCs9cNAuGp/QL0euEC4crBAuR64QL6PXEDOTdNA2987QN9T+EDoMSdA8mZm QOZumEDDZFpAmmZmQGlYEEBa4UhAivGqQLel40Dgan9A4WBCQLNcKUCIKPZAk1P4QNWRaEEP kWhBKaHLQTkOVkFEan9BUWBCQVyfvg== </TD></TR> </TABLEDATA></DATA> </TABLE>
When decoded, the contents of the last column is the binary representation of the spectrum, as defined in section 5.3; no length prefix is required here, the total length of the array being implicitly defined by the length of the encoded text.
<TABLE name="Model_A"> <DESCRIPTION>Star luminosities in Model A</DESCRIPTION> <DESCRIPTION context="latex">$L(T_{eff})$ in Model {\bf A}</DESCRIPTION> <FIELD name="Teff" datatype="float" unit="K" ucd="phys.temperature.effective"> <DESCRIPTION>Effective temperature</DESCRIPTION> <TITLE context="latex">$T_{eff}$</TITLE> </FIELD> <FIELD name="Lum" datatype="float" unit="Lsun" ucd="phys.luminosity"> <DESCRIPTION>Corresponding luminosity in Model A</DESCRIPTION> <DESCRIPTION context="latex">$L(T_{eff})$</DESCRIPTION> <TITLE context="latex">$L/L_\odot$</TITLE> </FIELD> </TABLE>
In practice this extension would mean that, wherever a DESCRIPTION element is currently acceptable, a set of DESCRIPTION and TITLE elements would become acceptable, each with an optional context additional attribute. The new TITLE element would have the role of expliciting the column header in a field or parameter, or to supply a caption of a table or a set of tables (resource) in addition to its description.
Providing descriptions in several languages would be another obvious advantage of this extension.
<TABLE name="Messier"> <FIELD name="Number" ID="M" ucd="meta.record" datatype="int" > <DESCRIPTION>Messier Number</DESCRIPTION> </FIELD> <FIELD name="R.A.2000" ID="RA" ucd="pos.eq.ra;meta.main" unit="deg" datatype="float" width="5" precision="1" /> <FIELD name="Dec.2000" ID="DE" ucd="pos.eq.dec;meta.main" unit="deg" datatype="float" width="5" precision="1" /> <FIELD name="Name" ID="N" ucd="meta.id" datatype="char" arraysize="*"> <DESCRIPTION>Common name used to designate the Messier object</DESCRIPTION> </FIELD> <FIELD ID="T" name="Classification" datatype="char" arraysize="10*" ucd="src.class"> <DESCRIPTION>Classification (galaxy, glubular cluster, etc)</DESCRIPTION> </FIELD> <DATA><XMLDATA> <TR> <M>3</M> <RA>205.5</RA> <DE>+28.4</DE> <N/> <T>Globular Cluster</T> </TR> <TR> <M>31</M> <RA>010.7</RA> <DE>+41.3</DE> <N>Andromeda Galaxy</N> <T>Galaxy</T> </TR> </XMLDATA></DATA> </TABLE>
The full document would need an XML-Schema definition of the tags M, RA, DE, N and T; these being derived directly from the ID attribute of the FIELD element, their definition can be generated automatically from the set of FIELD definitions.
<?xml version="1.0" encoding="UTF-8"?> <!--W3C Schema for VOTable = Virtual Observatory Tabular Format .Version 1.0 : 15-Apr-2002 .Version 1.09: 23-Jan-2004 Version 1.09 .Version 1.09: 30-Jan-2004 Version 1.091 .Version 1.09: 22-Mar-2004 Version 1.092 .Version 1.094: 02-Jun-2004 GROUP does not contain FIELD .Version 1.1 : 10-Jun-2004 remove the complexContent .Version 1.11: GL: 23-May-2006 remove most root elements, use name= type= iso ref= structure .Version 1.11: GL: 29-Aug-2006 review and added comments (prefixed by GL) before sending to Francois Ochsenbein .Version 1.12: FO: Preliminary Version 1.2 .Version 1.18: FO: Tested (jax) version 1.2 .Version 1.19: FO: Completed INFO attributes .Version 1.20: FO: Added xtype; content-role is less restrictive (May2009) .Version 1.20a: FO: PR-20090710 Cosmetics. .Version 1.20b: FO: INFO does not accept sub-elements (2009-09-29) .Version 1.20c: FO: elementFormDefault="qualified" to stay compatible with 1.1 .Version 1.3: MT: Added BINARY2 element .Version 1.3: MT: Further relaxed LINK content-role type to token .Version 1.3-Erratum-2 MT: Made slight change to precType pattern .Version 1.4pre1: MD: merged 1.3-Erratrum 2, added TIMESYS. .Version 1.4wd-a: TD: updates for initial draft of v1.4. .Version 1.4: TD: Change version to 1.4 .Version 1.5pre1: MD: adding refposition attribute and FIELDref/PARAMref in COOSYS, which no longer is derived from xs:string, either. .Version 1.5pre2: MD: vocabularising system attribute in COOSYS .Version 1.5pre3: TD: Undo the FIELDref/PARAMref addition to COOSYS .Version 1.5: TD: Update version to 1.5 for REC .Version 1.6: MT: Update version to 1.6pre --> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" xmlns="http://www.ivoa.net/xml/VOTable/v1.3" targetNamespace="http://www.ivoa.net/xml/VOTable/v1.3" version="1.6pre" > <xs:annotation><xs:documentation> VOTable is meant to serialize tabular documents in the context of Virtual Observatory applications. This schema corresponds to the VOTable document available from http://www.ivoa.net/Documents/latest/VOT.html </xs:documentation></xs:annotation> <!-- Here we define some interesting new datatypes: - anyTEXT may have embedded XHTML (conforming HTML) - astroYear is an epoch in Besselian or Julian year, e.g. J2000 - arrayDEF specifies an array size e.g. 12x23x* - dataType defines the acceptable datatypes - ucdType defines the acceptable UCDs (UCD1+) - precType defines the acceptable precisions - yesno defines just the 2 alternatives --> <xs:complexType name="anyTEXT" mixed="true"> <xs:sequence> <xs:any minOccurs="0" maxOccurs="unbounded" processContents="skip"/> </xs:sequence> </xs:complexType> <xs:simpleType name="astroYear"> <xs:restriction base="xs:token"> <xs:pattern value="[JB]?[0-9]+([.][0-9]*)?"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="ucdType"> <xs:restriction base="xs:token"> <xs:annotation><xs:documentation> Accept UCD1+ Accept also old UCD1 (but not / + %) including SIAP convention (with :) </xs:documentation></xs:annotation> <xs:pattern value="[A-Za-z0-9_.:;\-]*"/><!-- UCD1 use also / + % --> </xs:restriction> </xs:simpleType> <xs:simpleType name="arrayDEF"> <xs:restriction base="xs:token"> <xs:pattern value="([0-9]+x)*[0-9]*[*]?(s\W)?"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="encodingType"> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="gzip"/> <xs:enumeration value="base64"/> <xs:enumeration value="dynamic"/> <xs:enumeration value="none"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="dataType"> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="boolean"/> <xs:enumeration value="bit"/> <xs:enumeration value="unsignedByte"/> <xs:enumeration value="short"/> <xs:enumeration value="int"/> <xs:enumeration value="long"/> <xs:enumeration value="char"/> <xs:enumeration value="unicodeChar"/> <xs:enumeration value="float"/> <xs:enumeration value="double"/> <xs:enumeration value="floatComplex"/> <xs:enumeration value="doubleComplex"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="precType"> <xs:restriction base="xs:token"> <xs:pattern value="[EF]?[0-9][0-9]*"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="yesno"> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> <xs:complexType name="Min"> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="inclusive" type="yesno" default="yes"/> </xs:complexType> <xs:complexType name="Max"> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="inclusive" type="yesno" default="yes"/> </xs:complexType> <xs:complexType name="Option"> <xs:sequence> <xs:element name="OPTION" type="Option" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="name" type="xs:token"/> <xs:attribute name="value" type="xs:string" use="required"/> </xs:complexType> <!-- VALUES expresses the values that can be taken by the data in a column or by a parameter --> <xs:complexType name="Values"> <xs:sequence> <xs:element name="MIN" type="Min" minOccurs="0"/> <xs:element name="MAX" type="Max" minOccurs="0"/> <xs:element name="OPTION" type="Option" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="type" default="legal"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="legal"/> <xs:enumeration value="actual"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="null" type="xs:token"/> <xs:attribute name="ref" type="xs:IDREF"/> </xs:complexType> <!-- The LINK is a URL (href) or some other kind of reference (gref) --> <xs:complexType name="Link"> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="content-role" type="xs:token"/> <xs:attribute name="content-type" type="xs:token"/> <xs:attribute name="title" type="xs:string"/> <xs:attribute name="value" type="xs:string"/> <xs:attribute name="href" type="xs:anyURI"/> <xs:attribute name="gref" type="xs:token"/><!-- Deprecated in V1.1 --> <xs:attribute name="action" type="xs:anyURI"/> </xs:complexType> <!-- No sub-element is accepted in INFO for backward compatibility --> <xs:complexType name="Info"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="name" type="xs:token" use="required"/> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="unit" type="xs:token"/> <xs:attribute name="xtype" type="xs:token"/> <xs:attribute name="ref" type="xs:IDREF"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType> <!-- Expresses the coordinate system we are using --> <xs:complexType name="CoordinateSystem"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="ID" type="xs:ID" use="required"/> <xs:attribute name="equinox" type="astroYear"/> <xs:attribute name="epoch" type="astroYear"/> <xs:attribute name="system" default="FK5"> <xs:annotation> <xs:documentation> Values for this attribute must be taken from the IVOA refframe vocabulary, http://www.ivoa.net/rdf/refframe </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="refposition" type="xs:token"> <xs:annotation> <xs:documentation> The reference position SHOULD be taken from the IVOA refposition vocabulary (http://www.ivoa.net/rdf/refposition). </xs:documentation> </xs:annotation> </xs:attribute> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:simpleType name="Timeorigin"> <xs:annotation> <xs:documentation> This is a time origin of a time coordinate, given as a Julian Date for the the time scale and reference point defined. It is usually given as a floating point literal; for convenience, the magic strings “MJD-origin” (standing for 2400000.5) and “JD-origin” (standing for 0) are also allowed. </xs:documentation> </xs:annotation> <xs:restriction base="xs:token"> <xs:pattern value="[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?|(JD|MJD)-origin"> </xs:pattern> </xs:restriction> </xs:simpleType> <xs:complexType name="TimeSystem"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="ID" type="xs:ID" use="required"/> <xs:attribute name="timeorigin" type="Timeorigin"> <xs:annotation> <xs:documentation> The time origin is the offset or the time coordinate to Julian Date. The timeorigin attribute MUST be given unless the time's representation contains a year of a calendar era, in which case it MUST NOT be present. </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="timescale" use="required" type="xs:token"> <xs:annotation> <xs:documentation> This is the time scale used. Values SHOULD be taken from the IVOA timescale vocabulary (http://www.ivoa.net/rdf/timescale). </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="refposition" use="required" type="xs:token"> <xs:annotation> <xs:documentation> The reference position SHOULD be taken from the IVOA refposition vocabulary (http://www.ivoa.net/rdf/refposition). </xs:documentation> </xs:annotation> </xs:attribute> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:complexType name="Definitions"> <xs:annotation><xs:documentation> Deprecated in Version 1.1 </xs:documentation></xs:annotation> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="COOSYS" type="CoordinateSystem"/> <xs:element name="TIMESYS" type="TimeSystem"/> <xs:element name="PARAM" type="Param"/> </xs:choice> </xs:complexType> <!-- FIELD is the definition of what is in a column of the table --> <xs:complexType name="Field"> <xs:sequence> <xs:element name="DESCRIPTION" type="anyTEXT" minOccurs="0"/> <xs:element name="VALUES" type="Values" minOccurs="0"/> <xs:element name="LINK" type="Link" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="unit" type="xs:token"/> <xs:attribute name="datatype" type="dataType" use="required"/> <xs:attribute name="precision" type="precType"/> <xs:attribute name="width" type="xs:positiveInteger"/> <xs:attribute name="xtype" type="xs:token"/> <xs:attribute name="ref" type="xs:IDREF"/> <xs:attribute name="name" type="xs:token" use="required"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> <xs:attribute name="arraysize" type="xs:string"/> <xs:attribute name="type"> <!-- type is not in the Version 1.1, but is kept for backward compatibility purposes --> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="hidden"/> <xs:enumeration value="no_query"/> <xs:enumeration value="trigger"/> <xs:enumeration value="location"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> <!-- A PARAM is similar to a FIELD, but it also has a "value" attribute --> <xs:complexType name="Param"> <xs:complexContent> <xs:extension base="Field"> <xs:attribute name="value" type="xs:string" use="required"/> </xs:extension> </xs:complexContent> </xs:complexType> <!-- GROUP groups columns; may include descriptions, fields/params/groups --> <xs:complexType name="Group"> <xs:sequence> <xs:element name="DESCRIPTION" type="anyTEXT" minOccurs="0"/> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="FIELDref" type="FieldRef"/> <xs:element name="PARAMref" type="ParamRef"/> <xs:element name="PARAM" type="Param"/> <xs:element name="GROUP" type="Group"/> </xs:choice> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="name" type="xs:token"/> <xs:attribute name="ref" type="xs:IDREF"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> </xs:complexType> <!-- FIELDref and PARAMref are references to FIELD or PARAM defined in the parent TABLE or RESOURCE --> <xs:complexType name="FieldRef"> <xs:attribute name="ref" type="xs:IDREF" use="required"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> </xs:complexType> <xs:complexType name="ParamRef"> <xs:attribute name="ref" type="xs:IDREF" use="required"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> </xs:complexType> <!-- DATA is the actual table data, in one of three formats --> <xs:complexType name="Data"> <xs:annotation><xs:documentation> Added in Version 1.2: INFO for diagnostics </xs:documentation></xs:annotation> <xs:sequence> <xs:choice> <xs:element name="TABLEDATA" type="TableData"/> <xs:element name="BINARY" type="Binary"/> <xs:element name="BINARY2" type="Binary2"/> <xs:element name="FITS" type="FITS"/> </xs:choice> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Pure XML data --> <xs:complexType name="TableData"> <xs:sequence> <xs:element name="TR" type="Tr" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="Td"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:annotation><xs:documentation> The 'encoding' attribute is added here to avoid problems of code generators which do not properly interpret the TR/TD structures. 'encoding' was chosen because it appears in appendix A.5 </xs:documentation></xs:annotation> <xs:attribute name="encoding" type="encodingType"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:complexType name="Tr"> <xs:annotation><xs:documentation> The ID attribute is added here to the TR tag to avoid problems of code generators which do not properly interpret the TR/TD structures </xs:documentation></xs:annotation> <xs:sequence> <xs:element name="TD" type="Td" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> </xs:complexType> <!-- FITS file, perhaps with specification of which extension to seek to --> <xs:complexType name="FITS"> <xs:sequence> <xs:element name="STREAM" type="Stream"/> </xs:sequence> <xs:attribute name="extnum" type="xs:positiveInteger"/> </xs:complexType> <!-- BINARY data format --> <xs:complexType name="Binary"> <xs:sequence> <xs:element name="STREAM" type="Stream"/> </xs:sequence> </xs:complexType> <!-- BINARY2 data format --> <xs:complexType name="Binary2"> <xs:sequence> <xs:element name="STREAM" type="Stream"/> </xs:sequence> </xs:complexType> <!-- STREAM can be local or remote, encoded or not --> <xs:complexType name="Stream"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="type" default="locator"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="locator"/> <xs:enumeration value="other"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="href" type="xs:anyURI"/> <xs:attribute name="actuate" default="onRequest"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="onLoad"/> <xs:enumeration value="onRequest"/> <xs:enumeration value="other"/> <xs:enumeration value="none"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="encoding" type="encodingType" default="none"/> <xs:attribute name="expires" type="xs:dateTime"/> <xs:attribute name="rights" type="xs:token"/> </xs:extension> </xs:simpleContent> </xs:complexType> <!-- A TABLE is a sequence of FIELD/PARAMs and LINKS and DESCRIPTION, possibly followed by a DATA section --> <xs:complexType name="Table"> <xs:annotation><xs:documentation> Added in Version 1.2: INFO for diagnostics </xs:documentation></xs:annotation> <xs:sequence> <xs:element name="DESCRIPTION" type="anyTEXT" minOccurs="0"/> <!-- Added Version 1.2: --> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> <!-- An empty table without any FIELD/PARAM should not be acceptable --> <xs:choice minOccurs="1" maxOccurs="unbounded"> <xs:element name="FIELD" type="Field"/> <xs:element name="PARAM" type="Param"/> <xs:element name="GROUP" type="Group"/> </xs:choice> <xs:element name="LINK" type="Link" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="DATA" type="Data" minOccurs="0"/> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="name" type="xs:token"/> <xs:attribute name="ref" type="xs:IDREF"/> <xs:attribute name="ucd" type="ucdType"/> <xs:attribute name="utype" type="xs:string"/> <xs:attribute name="nrows" type="xs:nonNegativeInteger"/> </xs:complexType> <!-- RESOURCES can contain DESCRIPTION, (INFO|PARAM|COSYS), LINK, TABLEs --> <xs:complexType name="Resource"> <xs:annotation><xs:documentation> Added in Version 1.2: INFO for diagnostics in several places </xs:documentation></xs:annotation> <xs:sequence> <xs:element name="DESCRIPTION" type="anyTEXT" minOccurs="0"/> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="COOSYS" type="CoordinateSystem"/> <xs:element name="TIMESYS" type="TimeSystem"/> <xs:element name="GROUP" type="Group" /> <xs:element name="PARAM" type="Param" /> </xs:choice> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="LINK" type="Link" minOccurs="0" maxOccurs="unbounded"/> <xs:choice> <xs:element name="TABLE" type="Table" /> <xs:element name="RESOURCE" type="Resource" /> </xs:choice> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <!-- Suggested Doug Tody, to include new RESOURCE types --> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="name" type="xs:token"/> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="utype" type="xs:string"/> <xs:attribute name="type" default="results"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="results"/> <xs:enumeration value="meta"/> </xs:restriction> </xs:simpleType> </xs:attribute> <!-- Suggested Doug Tody, to include new RESOURCE attributes --> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> <!-- VOTable is the root element --> <xs:element name="VOTABLE"> <xs:complexType> <xs:sequence> <xs:element name="DESCRIPTION" type="anyTEXT" minOccurs="0"/> <xs:element name="DEFINITIONS" type="Definitions" minOccurs="0"/><!-- Deprecated --> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="COOSYS" type="CoordinateSystem"/> <xs:element name="TIMESYS" type="TimeSystem"/> <xs:element name="GROUP" type="Group" /> <xs:element name="PARAM" type="Param" /> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> </xs:choice> <xs:element name="RESOURCE" type="Resource" minOccurs="1" maxOccurs="unbounded"/> <xs:element name="INFO" type="Info" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="ID" type="xs:ID"/> <xs:attribute name="version"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="1.3"/> <xs:enumeration value="1.4"/> <xs:enumeration value="1.5"/> <xs:enumeration value="1.6"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> </xs:schema>
1http://fits.gsfc.nasa.gov/fits_registry.html