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."
Comments on this document are due 30 June 2003 for consideration in the next version of this document. They should be sent to registry@ivoa.net, a mailing list with a public archive. General discussion of related technology is also welcome on the Rwp03 wiki site.
A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), and from the Eurpean Commission's Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON).
The Virtual Observatory (VO) is general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The International Virtual Observatory Alliance (IVOA) is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications.
XML document validation is a software process that checks that an XML document is not only well-formed XML but also conforms to the syntax rules defined by the applicable schema. Typically, when the schema is by one or more XML Schema [Schema] documents (see next section), validation refers to checking for conformance to the syntax described in those Schema documents. This document describes additional syntax constraints that cannot be enforced solely by the rules of XML Schema; thus, in this document, use of the term validation includes the extra checks that goes beyond common Schema-aware parsers which ensure conformance with this document.
UTC refers to Universal Coordinated Time as defined by....
The eXtensible Markup Language, or XML, is document syntax for marking textual information with named tags and is defined by the World Wide Web Consortium (W3C) Recommendation, XML 1.0 [XML]. The set of XML tag names and the syntax rules for their use is referred to as the document schema. One way to formally define a schema for XML documents is using the W3C standard known as XML Schema [Schema].
This document defines the VOResource schema using XML Schema. The full Schema document is listed in Appendix A. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity.
Reference to specific elements and types defined in the VOResource
schema include the namespaces prefix, vr
, as in
vr:Resource
(a type defined in the VOResource schema).
Use of the vr
prefix in compliant instance documents is
not required (see section 2.1); its use in this
document is simply to indicate that it is an entity defined in the
VOResource schema.
The IVOA Standard, Resource Metadata for the Virtual Observatory [Hanisch et al. 2004] (hereafter referred to as RM) defines metadata terms for describing resources. The RM defines a resource as:
... VO element that can be described in terms of who curates or maintains it and which can be given a name and a unique identifier. Just about anything can be a resource: it can be an abstract idea, such as sky coverage or an instrumental setup, or it can be fairly concrete, like an organization or a data collection. This definition is consistent with its use in the general Web community as "anything that has an identity" (Berners-Lee 1998, IETF RFC2396). We expand on this definition by saying that it is also describable.
The resource metadata are, then, the terms and concepts that describe a resource in general. The RM defines the terms as well as describes reasonable or allowed values; it does not, however, describe how the terms and values should be encoded. This is because resource metadata may be encoded in several different formats, depending on the context. This document specifically describes an encoding called VOResource.
The primary intended use of VOResource is to provide an XML interchange format for use with resource registries. A registry is a repository of resource descriptions [RM] and is employed by users and applications to discover resources. VOResource can be used to pass descriptions from publishers to registries and then from registries to applications. Another inended use is as a language for services to describe themselves directly. VOResource may be used in other ways, in whole or in part, using the standard XML mechanisms (e.g., import, include).
The VOResource schema provides XML encoding for so-called core metadata from the RM that (with a few exceptions) can apply to all resources; however, it is recognized that a full and useful description of a specific resource will require additional metadata that is relevant only to a resource of its type. Thus, the VOResource schema has been especially designed to be extended. The model for doing this is described in section XX.
- Note:
- The name "VOResource" has in practice had two meanings within IVOA discussions. The first refers specifically to the core XML schema defined by this document. The second refers more broadly to the core schema plus the set of legal extensions. In this document, use of the name "VOResource" corresponds to the first meaning. Reference to the broader set of schemas will be indicated explicitly with the annotating phrase, "and its legal extensions."
The primary use for VOResource, of course, is to describe a resource using the metadata concepts defined in the RM. Here's an example of a VOResource document describing an organisation, the Radio Astronomy Imaging Group at the National Center for Supercomputing Applications.
2 1 3 3 4 4 4 4 4 5 5 5 6 6 6 6 6 6 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 7 7 7 7 |
<?xml version="1.0" encoding="UTF-8"?> <resource xsi:type="Organisation" xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0 http://www.ivoa.net/xml/VOResource/v1.0"> <title>NCSA Radio Astronomy Imaging</title> <shortName>NCSA-RAI</shortName> <identifier>ivo://rai.ncsa/RAI</identifier> <curation> <publisher ivo-id="ivo://ncsa.uiuc/NCSA"> National Center for Supercomputing Applications </publisher> <creator> <name> Dr. Richard Crutcher </name> <logo> http://rai.ncsa.uiuc.edu/rai.jpg </logo> </creator> <date>1993-01-01</date> <contact> <name>Dr. Raymond Plante</name> <email>rplante@ncsa.uiuc.edu</email> </contact> </curation> <content> <subject>radio astronomy</subject> <subject>data repositories</subject> <subject>digital libraries</subject> <subject>grid-based processing</subject> <description> The Radio Astronomy Imaging Group at the National Center for Supercomputing Applications is focused on applying high-performance computing to astronomical research. Our projects include the NCSA Astronomy Digital Image Library, the BIMA Data Archive, the BIMA Image Pipeline, and the National Virtual Observatory. </description> <referenceURL>http://rai.ncsa.uiuc.edu/</referenceURL> <type>Organisation</type> <contentLevel>Research</contentLevel> </content> <facility>Berkeley-Illinois-Maryland Array (BIMA)</facility> <facility> Combined Array for Research in Millimeter Astronomy (CARMA) </facility> </resource> |
This example illustrates some important components of a VOResource record:
xsi:type
attribute, The VOResource schema namespace is "http://www.ivoa.net/xml/VOResource/v1.0". The namespace URI has been chosen to allow it to be resolved as a URL to the XML Schema document (given in Appendix A) that defines the VOResource schema. Applications may assume that the namespace URI is so resolvable.
Authors of instance documents that use the VOResource schema may choose to
provide a location for VOResource XML Schema document using the
xsi:schemaLocation
attribute; the choice of
the location value is the choice of the author. In general, the use
of
xsi:schemaLocation
is recommended by
this specification with a the namespace URI given as the location as
illustrated in the example above, unless the application prefers
otherwise.
xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0 http://www.ivoa.net/xml/VOResource/v1.0"
Whenever instance validation is needed, use of
the VOResource schema and its legal extensions must be declared using
the standard namespace declaration attribute,
xmlns:prefix
(where prefix is an arbitrary
prefix). The prefix, vr
, is used by convention as the
prefix defined for the VOResource schema; however, instance documents
may use any prefix of the author's choosing. In this document, the
vr
prefix is used to label, as shorthand, a type or
element name that is defined in the VOResource schema, as in
vr:Resource
.
Because the VOResource XML schema sets
elementFormDefault="unqualified"
, documents that use the
VOResource schema must not use the namespace declaration attribute,
xmlns
(used to set the default namespace), anywhere in
the document where the VOResource schema is in effect. (This is a
restriction set by the rules of XML Schema). Furthermore, in
accordance with the Schema rules for unqualified elements, the
VOResource namespace prefix must not used to qualify VOResource
elements. In general, namespace prefixes are only used to qualify
type names given as values to the xsi:type
attribute (see
next section). Legal extensions of the VOResource schema SHOULD also
set elementFormDefault="unqualified"
for consistancy.
The VOResource schema only defines global types; it does not define any global elements (often refered to as root elements). It is the responsibility of the application to define the root element of the VOResource-employing documents it operates on. Typically, the root element is defined in a separate application-specific schema. The type of an application document's root element is not assumed to be any particular type defined in the VOResource schema (nor any of its legal extensions). In fact, it need not be of a type from the VOResource at all; rather, VOResource types may appear anywhere in the document.
- Note:
- The IVOA Registry Interface standard, for example, includes a small schema that defines a single global element,
<VOResources>
, that can contain a series of<resource>
child elements. The child element is defined to be of the typeResource
from the VOResource schema.
- Note:
- In the example instance document at the beginning of section 2, the root element,
<resource>
is not defined in any schema. Nevertheless, this document is still legal and verifiable XML. This is because the element's type is explicitly specified with thexsi:type
attribute.
VOResource uses the following conventions for names of elements and types:
shortName
, upper-case letters are
used demarcate the start of appended word (the "camel"
format). IdentifierURI
, all letters in the abbreviation are
capitalized. xsd:import
or
xsd:include
) or extend it.
Applications describe a single resource using an element of the type
vr:Resource
or a legal derivation of it.
The content of the vr:Resource
type is
referred to as the core VOResource metadata, and
they fall into four categories (corresponding to the sections 3.1,
3.2, 3.3, and 4 of the RM):
<title>
,
<shortName>
, and
<identifier>
elements;
<curation>
element;
<content>
element;
<validationLevel>
element.
Many of the elements in VOResource that are meant to have string or
URI values are defined as being of the type vr:PaddedString
and vr:PaddedURI
, respectively:
<xs:simpleType name="PaddedString"> <xs:restriction base="xs:string"> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType>
<xs:simpleType name="PaddedURI"> <xs:restriction base="xs:anyURI"> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType>
This allows authors of VOResource instance documents to pad string and URI values with spaces and include carriage returns to improve readability. The definition of these type will cause an XML Schema-compliant parser to replace tab, line feed, and carraige return characters with simple spaces, then replace multiple sequential occurances of spaces with a single space, and then remove all leading and trailing spaces.
All VOResource elements and attributes that
contain dates must be interpreted as UTC dates and
must be encoded in compliance with ISO8601 standard Date and Time Format
[ISO8601]. The vr:UTCDateTime
enforces a restricted form of this format which allows encoding of the
date and time, but disallows the timezone format:
<xs:simpleType name="UTCDateTime"> <xs:restriction base="xs:dateTime"> <xs:whiteSpace value="collapse"/> <xs:pattern value="\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?"/> </xs:restriction> </xs:simpleType>
When this type is used, authors must provide an applicable UTC date and time, and applications must interpret the time and date as UTC.
All VOResource types and elements have an associated semantic meaning
which is given in the first <xsd:documentation>
node within the type or element's definition in the schema. The
meaning associated with a type is generic, indicating the kind of
information the type provides. The semantics that are delivered by a
VOResource instance document, however, are those associated with
VOResource elements. The meaning of a VOResource element can be
thought of as having two parts: the generic meaning of the set of
information it contains as defined by its type, and a specific meaning
describing the context in which that information applies. Because all
VOResource elements are locally defined (in the XML Schema
sense), they do not have an absolute meaning, but rather have a
meaning tied to the thing being described by that element as
represented by the enclosing type.
The vr:Curation
type describes the curation of a
resource. The <curation>
element
describes curation of the specific resource described by the
enclosing vr:Resource
type and identified by its
identifier
element.
The vr:ResourceName
type is a generic reference to
another resource. The <publisher>
element
gives a reference to the publisher of the specific resource being
described which may itself be a registered resource described
elsewhere.
The <title>
element gives the title of
the resource being described the enclosing
vr:Resource
type and identified by its
<identifier>
element. The
<title>
element's type,
vr:PaddedString
(a restriction on
xsd:string
), has no inherent meaning associated
with it.
Additional semantics are transmitted through the use of derived types
using the xsi:type
attribute. In the
sample instance document above, the
use of xsi:type="Organisation"
means that the resource
being described is specifically an organisation as defined by the
vr:Organisation
type. This type provides additional
metadata that are not part of the core resource metadata. The
semantics associated with the use of xsi:type
is
described further in the next subsection.
When a resource is described with an element explicitly of the type
vr:Resource
, it is being described in the most generic
sense. The metadata presented in this type, including both free text
values and controlled vocabulary, can give some sense of what
type of resource is being described and what it might be used for.
However, the most useful descriptions of resources will not explicitly
use the vr:Resource
type; rather, they will use types
that are derived from vr:Resource
.
Defining derived vr:Resource
types accomplishes two
things:
The VOResource schema defines two types derived from
vr:Resource
: vr:Organisation
and
vr:Service
. The vr:Organisation
adds
metadata describing the astronomical facilities such as telescopes
that are associated with the organisation it describes. The
vr:Service
type adds an element called
capability
which describes the service's interface as
well as information regarding its behavior.
Extensions of the vr:Resource
type is a key way
derivation is used in VOResource to provide refined resource
descriptions. Two other important parent types in the schema are
vr:Capability
and vr:Interface
; these are
extended to provide more refined descriptions of services (see section 2.2.2). The motivation for extending
these types are the same as for vr:Resource
: to provide
more specific semantic meaning through the derived type's name, and to
provide additional, specialized metadata that is not part of the
parent type. Note, however, that in general, a derived type need not
alter the content model of its base type. This allows derived types
to add more specific meaning with out adding any additional metadata.
As described in section 2.2, it is intended that
derived vr:Resource
, vr:Capability
and
vr:Interface
types be invoked in instance
documents using the xsi:type
attribute (as illustrated in
the sample document above). This
method illustrates a polymorphism for resource metadata in that any
place where an element of parent type is expected, the derived type
may be inserted. The use of xsi:type
illustrates both
what specific type is being inserted in as well as what it is being
inserted in for. That is, as in our
example, the resource being
described is an organisation.
The other mechanism for polymorphism provided by XML Schema
[Schema] is substitution groups. Invoking
derived vr:Resource
types via elements in a substitution
group is discouraged because it is less obvious from looking at the
instance document that a substitution is being made.
The vr:Service
type extends the core
vr:Resource
metadata data by adding the
capability
element (see section
3.2.2). This element is used to describe a major functionality of
the service, usually accessible through a single service endpoint URL.
In particular, it is used to describe support for an IVOA service
standard (e.g. Simple Image Access Protocol). A service resource
record may have multiple child capability
elements, each
describing a different major functionality; however, these
capabilities should be related in an obvious, logical way by virtue of
sharing same core VOResource metadata.
- Note:
- Whether multiple related capabilities are grouped together in a single Service record or are described in separate Service records is expected to be the choice of the VOResource record author. However, it is also expected that resource registry providers will provide some guidance to authors on best practices. This guidance could in part come in the form of a GUI that naturally encourage or contrains to aggregation of capabilities in a single record.
The capability
element, through its type
vr:Capability
, describes the behavior of service
capability and how to access it. The latter is described by a child
interface
element. As for the behavior, the base
vr:Capability
type only provides a
description
element that can contain human-readable text
on what this capability provides. More structured behavioral
information must be provided through specialized
vr:Capability
extensions. In particular, it is expected
that a service standard (e.g. Simple Image Access Protocol) would
define an extension of vr:Capability
that adds additional
metadata that can describe the service's behavior in relation to the
standard; for example, the added metadata can describe limitations of
the service implementation or indicate support for optional features.
The specific vr:Capability
type is invoked using the
xsi:type
mechanism described in
section 2.2.1.
SimpleImageAccess
extension type is defined in a separate
schema document. <capability xsi:type="sia:SimpleImageAccess" standardID="ivo://ivoa.net/std/SIA"> ... </capability>
As the example above suggests, a common way for locating or otherwise
identifying support for a standard service capability is by looking
for the appropriate value in a capability
's
xsi:type
attribute.
If the service capability being described does not conform to any
standard or if the standard does not require any specialized
capability metadata for describing an implementation's behavior, then
no vr:Capability
extension is required. In this case,
the base capability
element is simply used without any
xsi:type
attribute provided. It is expected that the
metadata provided outside of the capability
element as
well as (optionally) it's description
element is
sufficient for describing what the service does.
Because each vr:Capability
extension features a different
set of behavioral metadata, introducing a new
vr:Capability
extension can impose a non-trivial cost on
applications that process VOResource records. Thus, an alternative
way to indicate support for a service standard is provided by the
standardID
attribute which is useful when the standard
does not require any specialized behavioral metadata to be provided.
The value is set to a URI which represents the service standard. Some
service standards that do extend vr:Capability
may force the value of this attribute to be set to the
appropriate value (see section 2.3.2);
this allows one to use, when appropriate, the standardID
as a way to locate support for a standard regardless of whether an
extension type has been defined or not.
Each capability
element can contain one or more child
interface
elements, each describing how the capability
can be accessed. The interface
element's type,
vr:Interface
, is abstract; thus, the
interface
element must be accompanied by an
xsi:type
attribute that indicates an
vr:Interface
extension type. The VOResource schema
defines two vr:Interface
extension types:
vr:WebBrowser
, for describing an interface access via web
browser, and vr:WebService
, for accessing a service
described by a Web Service Description Language (WSDL) document (see
section XX for details).
<interface xsi:type="vr:WebService"> <accessURL> http://archive.org/service/query </accessURL> </capability>
When a capability
contains more than one
interface
, each interface
should be
interpreted as an alternative interface for accessing essentially the
same underlying capability. The interfaces can differ in their
overall type (e.g. vr:WebBrowser
,
vr:WebService
) or in the supported input parameters or
output products.
When a standard capability is being described (i.e. either the
vr:Capability
sub-type is defined by a standard or the
standardID
is provided), then at least one of the
interface
elements should describe an interface required
by the standard. The role
attribute is used to mark the
standard interfaces (typically with the value "std"; see section XX
for details). All other interfaces are considered non-standard
alternatives.
Another important way interface
s inside the same
capability
element can be different is in the version of
the service standard the interface supports. Whenever, an interface
supports a version other than "1.0", the interface
element must include a version
attribute set to the
version being supported. Valid values for version
are
defined by the standard.
SkyNode
extension type is defined in a separate
schema document. <capability xsi:type="sn:SkyNode" standardID="ivo://ivoa.net/std/SkyNode"> <!-- version 1.0 of the standard SkyNode interface --> <interface xsi:type="vr:WebService" role="std" version="1.0"> <accessURL> http://archive.org/service/skynode </accessURL> </interface> <!-- version 1.1 of the standard SkyNode interface --> <interface xsi:type="vr:WebService" role="std" version="1.1"> <accessURL> http://archive.org/service/skynode1.1 </accessURL> </interface> <!-- a interactive alternative interface, assesible via a browser --> <interface xsi:type="vr:WebBrowser"> <accessURL> http://archive.org/skynode.html </accessURL> </interface> ... </capability>
A schema made up only of global type definitions provides great flexibility for extension. Any global type defined in the VOResource schema may be used as the base of a derived type defined in another schema. The schema containing the derived types must declare its own namespace URI or default to the null namespace; it must not adopt the VOResource namespace URI. The application must then define what schemas, identified by their namespace URIs, are supported and/or required.
A VOResource extension is an XML Schema document whose primary purpose is to define new types derived from those defined in the VOResource schema for use in resource descriptions. It is recommended that VOResource extensions follow the definition styles used by the core VOResource. In particular:
Provide semantic definitions of all types and elements within
the first <xsd:documentation>
element inside
the type or element definition. Subsequent
<xsd:documentation>
elements may provide
additional comments or discussion.
Avoid the use of xsd:choice
elements.
VOResource does not use the choice structure because it does
not map readily into any object-oriented software language
structure. Choices are handled instead as multiple derived
types that can be inserted in place of a parent type.
Avoid the use of substitution groups. VOResource
prefers instead the use of xsi:type
which are
(with a few exceptions) functionally equivalent to substitution
groups in terms of structure; however, xsi:type
serves as an obvious flag in the instance document that a
substitution has been made.
Choose semantically meaningful names for derived
types. When the derived type appears in the pattern
<elname xsi:type="derivedType">
,
choose a derivedType name such that the sentence, "a
derivedType is a kind of elname" makes natural
and obvious sense. For example, "an Organisation is a
kind of resource."
Follow the VOResource naming conventions.
There are two types of derivation that are particularly important to
the VOResource data model: derivation of the vr:Resource
type, used to define specific types of resources, and the derivation
of service metadata elements.
Derivation of vr:Resource
to define new kinds of
resources should be done by extension (i.e. using
<xsd:extension>
) rather than restriction. It is
not required that the derived type change the content model from that
of the vr:Resource
base type; in this case, the purpose
of the derivation is only to sharpen the semantic meaning of the
resource description.
As described in section 2.2.3, a service
standard will often define a new vr:Capability
extension
type to allow implementations to describe how they support the
standard. This definition of the vr:Capability
extension
should be done in a schema document with a namespace identifier that
is dedicated to that standard (hereafter referred to as the
standard's extension schema). The extension type should include
elements representing the applicable Capability metadata described in
section 5.2 of the RM
(e.g. Service.MaxReturnRecords, Service.MaxReturnSize)
but can also include other concepts that are specific to that standard.
The standard's extension schema may create a derived
vr:Capability
type that forces the value of the
standardID
attribute to be set to a given URI. This
should be done by first deriving from vr:Capability
by
restriction (i.e. using
<xsd:restriction>
), keeping all of the parent's
content model except adding to the standardID
's attribute
definition use="required"
along with the
fixed
modifier set to the desired URI. Since this
restricted type is not intended for direct use in an instance
document, it should be marked as abstract. The restricted type should
then be extended to add the specialized capability metadata required
by the standard. (See the example below.)
It is not recommended that standard's extension schema attempt to force the inclusion of a required interface type.
An extension schema can define new interface types, though not
necessarily in the context of any specific standard service
capability. The basic vr:Interface
type provides only
accessURL
and securityMethod
as child
elements. A derived vr:Interface
type must indicate in
the documentation how the <accessURL>
should be
interpreted and used. The derived type may also include other added
metadata describing how to use the service (e.g., a description of the
input arguments). If the interface extension type is expected to be
referenced by a standard service capability, then it is recommended
that the additional metadata be optional unless the metadata is
absolutely required by clients in order to invoke the service.
- Note:
- It is intended that a set of common generic interface types would be defined in a separate VOResource extension schema. At the time of this writing, this schema is called VODataService. It currently defines an interface type for describing traditional GET and POST services. More specific interfaces, particularly those associated with standard IVOA services (like a Registry Service) would derive its specific interface descriptions from one of the common types as appropriate.
- Note:
- The Simple Image Access Protocol [SIA] is an example of a standard service that defines capability metadata. These include "maxRecords" that list the maximum number of records the SIA implementation can return at a time, and "MaxImageSize" gives the maximum image size that the service can return.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0" xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0" xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0" targetNamespace="http://www.ivoa.net/xml/SIA/v1.0" elementFormDefault="unqualified" attributeFormDefault="unqualified" version="1.0"> <xs:annotation> <xs:documentation> An XML Schema for describing a Simple Image Access Service implementation. </xs:documentation> </xs:annotation> <xs:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"/> <xs:complexType name="SIACapRestriction" abstract="true"> <xs:annotation> <xs:documentation> an abstract capability that fixes the standardID to the URI for the SIA standard. </xs:documentation> </xs:annotation> <xs:complexContent> <xs:restriction base="vr:Capability"> <xs:sequence> <xs:element name="validationLevel" type="vr:Validation" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="description" type="vr:PaddedString" minOccurs="0"/> <xs:element name="interface" type="vr:Interface" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="standardID" type="vr:IdentifierURI" use="required" fixed="ivo://ivoa.net/std/SIA"/> </xs:restriction> </xs:complexContent> </xs:complexType> <xs:complexType name="SimpleImageAccess"> <xs:annotation> <xs:documentation> The behavior and limitations of an SIA implementation. </xs:documentation> </xs:annotation> <xs:complexContent> <xs:extension base="sia:SIACapRestriction"> <xs:sequence> <xs:element name="maxRecords" type="xs:int"> <xs:annotation> <xs:documentation> The largest number of records that the Image Query web method will return. </xs:documentation> </xs:annotation> </xs:element> <!-- other capability metadata --> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> </xs:schema>
<resource xsi:type="vr:Service" xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0" xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <!-- the core VOResource metadata --> <capability xsi:type="sia:SimpleImageAccess"> <interface xsi:type="..."> <!-- interface description --> <accessURL> http://archive.org/services/sia <accessURL> </interface> <maxRecords>5000</maxRecords> <!-- other capability metadata --> </sia:capability> </resource>
This section enumerates the types and elements defined in the VOResource schema and describes their meaning in terms of the RM.
A resource, as defined by the RM, is
any entity or component of a VO application that is describable and
identifiable by a IVOA Identifier. A resource is described using
VOResource by an element of the type vr:Resource
or one
of its legal extensions. The schema definition (below) includes
elements that encode the identity, curation, and general content
metadata for a resource (see sections 3.1 thru 3.3 of the
RM). The RM states that certain
metadata are required in a minimally compliant resource description;
this requirement is enforced by the VOResource schema definition.
<xs:complexType name="Resource"> <xs:sequence> <xs:element name="validationLevel" type="vr:Validation" minOccurs="0" maxOccurs="unbounded"> <xs:element name="title" type="vr:PaddedString"/> <xs:element name="shortName" type="vr:ShortName" minOccurs="0"/> <xs:element name="identifier" type="vr:IdentifierURI"/> <xs:element name="curation" type="vr:Curation"/> <xs:element name="content" type="vr:Content"> </xs:sequence> <xs:attribute name="created" type="vr:UTCDateTime"/> <xs:attribute name="updated" type="vr:UTCDateTime"/> <xs:attribute name="status" default="active"/> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="active"/> <xs:enumeration value="inactive"/> <xs:enumeration value="deleted"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType>
The child elements for vr:Resource
are described in
subsequent sections.
The vr:Resource
attributes represent a special class of
metadata: they describe the resource metadata description contained within
the vr:Resource
itself as opposed to the resource being
described. Their meaning are as follows:
vr:Resource Attributes | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Attribute | Definition | ||||||||||||
created |
| ||||||||||||
updated |
| ||||||||||||
status |
|
The following sections define the elements that encode the specific metadata from the RM. In all cases, the semantic meaning of an element is defined by the RM metadatum it corresponds to (labeled "RM Name" below). All rules and advice given in the "Comments" portions in the RM definition apply. Any textual differences in the semantic definitions given below from those given in the RM are intended only for clarification for the XML encoding context.
The identity metadata described in the RM (section
3.1) are represented as top-level children of the
vr:Resource
type.
vr:Resource Identity Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
title |
| ||||||||
shortName |
| ||||||||
identifier |
|
Two special types, vr:ShortName
and
vr:identifierURI
are defined to support identity
metadata. The vr:ShortName
definition enforces the
16-character limit on shortNames.
<xs:simpleType name="ShortName"> <xs:restriction base="xs:string"> <xs:maxLength value="16"/> </xs:restriction> </xs:simpleType>
The vr:IdentifierURI
enforces the URI syntax for IVOA
Identifiers as defined by the IVOA Identifier standard
[ID].
<xs:simpleType name="IdentifierURI"> <xs:restriction base="xs:anyURI"> <xs:pattern value="ivo://[\w\d][\w\d\-_\.!~\*'\(\)\+=]{2,} (/[\w\d\-_\.!~\*'\(\)\+=]+(/[\w\d\-_\.!~\*'\(\)\+=]+)*)?"/> </xs:restriction> </xs:simpleType>
Two additional types which are not used within the
vr:Resource
type but are available to support the two
components of an IVOA Identifier [ID]:
vr:AuthorityID
and vr:ResourceKey
.
<xs:simpleType name="AuthorityID"> <xs:restriction base="xs:string"> <xs:pattern value="[\w\d][\w\d\-_\.!~\*'\(\)\+=]{2,}"/> </xs:restriction> </xs:simpleType>
<xs:simpleType name="ResourceKey"> <xs:restriction base="xs:string"> <xs:pattern value="[\w\d\-_\.!~\*'\(\)\+=]+(/[\w\d\-_\.!~\*'\(\)\+=]+)*"/> </xs:restriction> </xs:simpleType>
The curation metadata described in the RM (section
3.2) are bundled together into the vr:Resource
child element,
<curation>
. Its content is defined by the
vr:Curation
complex type.
<xs:complexType name="Curation"> <xs:sequence> <xs:element name="publisher" type="vr:ResourceName"/> <xs:element name="creator" type="vr:Creator" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="contributor" type="vr:ResourceName" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="date" type="vr:Date" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="version" type="vr:PaddedString" minOccurs="0"/> <xs:element name="contact" type="vr:Contact"/> </xs:sequence> </xs:complexType>
vr:Curation Metadata Elements | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||
publisher |
| ||||||||||
creator |
| ||||||||||
contributor |
| ||||||||||
date |
| ||||||||||
version |
| ||||||||||
contact |
|
Several of the curation elements (most importantly,
<publisher>
) make use of the
vr:ResourceName
type. This type is provides a means of
refering to another resource both by name and by its IVOA
identifier. Not all resources refered to using this type will
necessarily be registered and, therefore, will have an identifier;
thus, the identifier (which is encoded as an attribute) is optional.
<xs:complexType name="ResourceName"> <xs:simpleContent> <xs:extension base="vr:PaddedString"> <xs:attribute name="ivo-id" type="vr:IdentifierURI"/> </xs:extension> </xs:simpleContent> </xs:complexType>
The <creator>
element is defined by the
vr:Creator
complex type which bundles together the
RM metadata Creator and
Creator.Logo.
<xs:complexType name="Creator"> <xs:sequence> <xs:element name="name" type="vr:ResourceName"/> <xs:element name="logo" type="xs:anyURI" minOccurs="0"/> </xs:sequence> </xs:complexType>
vr:Creator Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
name |
| ||||||||
logo |
|
The <Date>
element's type, vr:Date
,
is an extension of the UTCDateTime
type that adds an optional attribute called role
.
<xs:complexType name="Date"> <xs:simpleContent> <xs:extension base="xs:date"> <xs:attribute name="role" type="xs:string" default="representative"/> </xs:extension> </xs:simpleContent> </xs:complexType>
The purpose of the role
attribute is to indicate what
aspect of the resource the date describes. This allows several
<date>
elements to be provided, each with a
different role. The possible values for this attribute are not
controlled; however, several values are recommended below and may be
recognized by applications. Other roles may be given. If a role is
not given, applications should interpret the date as
representative
as defined below.
vr:Date Attributes | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Attribute | Definition | ||||||||||||
role |
|
It is important to note that the <date>
element
describes the resource itself, not the resource record that describes
it. Dates describing the resource record are covered by
vr:Resource
attributes
created
and updated
The <contact>
element is defined by the
vr:Contact
type which bundles together several component
pieces of information, including the RM metadata Contact.Name
and Contact.Email.
<xs:complexType name="Contact"> <xs:sequence> <xs:element name="name" type="vr:ResourceName"/> <xs:element name="address" type="vr:PaddedString" minOccurs="0"/> <xs:element name="email" type="vr:PaddedString" minOccurs="0"/> <xs:element name="telephone" type="vr:PaddedString" minOccurs="0"/> </xs:sequence> </xs:complexType>
vr:Contact Metadata Elements | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||
name |
| ||||||||||
address |
| ||||||||||
| |||||||||||
telephone |
|
The general content metadata described in the RM
(section 3.3) are bundled together into the vr:Resource
child element, <content>
. Its content is
defined by the vr:Content
complex type.
<xs:complexType name="Content"> <xs:sequence> <xs:element name="subject" type="vr:PaddedString" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="description" type="vr:PaddedString"/> <xs:element name="source" type="vr:Source" minOccurs="0"/> <xs:element name="referenceURL" type="vr:PaddedURI"/> <xs:element name="type" type="vr:Type" minOccurs="0"/> <xs:element name="contentLevel" type="vr:ContentLevel" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="relationship" type="vr:Relationship" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>
vr:Content Metadata Elements | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
subject |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
description |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
source |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
referenceURL |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
type |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
contentLevel |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
relationship |
|
The <source>
element's type,
vr:Source
, is an extension of the
vr:PaddedString
type that
adds an optional attribute called format
.
<xs:complexType name="Source"> <xs:simpleContent> <xs:extension base="vr:PaddedString"> <xs:attribute name="format" type="xs:string"/> </xs:extension> </xs:simpleContent> </xs:complexType>
The format
indicates the syntactic format of the value of
the <source>
element. The possible values for this
attribute are not controlled; however, applications should
recognize a value equal to bibcode
as referring to the
standard astronomical bibcode format [Bibcode].
The <relationship>
is defined by the
vr:Relationship
complex type which bundles together the
RM metadata Relationship and
RelationshipID.
<xs:complexType name="Relationship" abstract="true"> <xs:sequence> <xs:element name="relatedResource" type="vr:ResourceName" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="CoreRelationship"> <xs:complexContent> <xs:extension base="vr:Relationship"> <xs:sequence> <xs:element name="relationshipType"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:whiteSpace value="collapse"/> <xs:enumeration value="mirror-of"/> <xs:enumeration value="service-for"/> <xs:enumeration value="served-by"/> <xs:enumeration value="derived-from"/> <xs:enumeration value="related-to"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType>
vr:Relationship Metadata Elements | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||
relatedResource |
| ||||||||||
relationshipType |
|
The vr:Relationship
type is abstract, so instance
documents must apply an xsi:type
attribute to the
relationship
element to indicate which list of controlled
relationship type names is being invoked. VOResource defines the
vr:CoreReslationship
type to provide a core set of
default relationships. The use of xsi:type
here means
that adding new relationship type name does not require a new version
of the VOResource core schema; instead, a new
vr:Relationship
sub-type can be defined in a separate
extension schema.
Allowed relationship type values defined by vr:CoreRelationship | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||||||
relationshipType |
|
The RM's
ResourceValidationLevel is encoded in the VOResource schema
with the <validationLevel>
element, which can
appear in multiple places within a vr:Resource
type or
sub-type. It may appear one or more times as the first children of a
vr:Resource
type and/or, if the resource is a
vr:Service
type or sub-type, one or more times as the
first children of any <capability>
element.
The validationLevel Element |
|||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||||||||||||||
validationLevel |
|
The validationLevel
element supports an attribute called
validatedBy
which takes an IVOA ID as a value. This ID
must refer to a registered organisation or registry that assigned the
numerical value. This element can appear multiple times, each with
different a validatedBy
value, to reflect the code
assigned by different organisations.
<xs:complexType name="Validation"> <xs:simpleContent> <xs:extension base="vr:ValidationLevel"> <xs:attribute name="validatedBy" type="vr:IdentifierURI"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:simpleType name="ValidationLevel"> <xs:restriction base="xs:integer"> <xs:whiteSpace value="collapse"/> <xs:enumeration value="0"/> <xs:enumeration value="1"/> <xs:enumeration value="2"/> <xs:enumeration value="3"/> <xs:enumeration value="4"/> </xs:restriction> </xs:simpleType>
The VOResource schema defines two extensions of the base
vr:Resource
type for describing two specific types of
resources: vr:Organisation
and vr:Service
. In
addition to providing more refined semantic meaning over
vr:Resource
, they add additional metadata for the
describing the resource which don't necessarily apply in the generic
case.
The Organisation resource type is used to describe an organisation in the sense defined by the RM:
An organisation is a specific type of resource that brings people together to pursue participation in VO applications. Organisations can be hierarchical and range greatly in size and scope. At a high level, an organisation could be a university, observatory, or government agency. At a finer level, it could be a specific scientific project space mission, or individual researcher.
The Organisation type extends the Resource
type by adding two additional elements to the core set of
metadata, <facility>
and
<instrument>
:
<xs:complexType name="Organisation"> <xs:complexContent> <xs:extension base="vr:Resource"> <xs:sequence> <xs:element name="facility" type="vr:ResourceName" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="instrument" type="vr:ResourceName" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType>
vr:Organisation Extension Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
facility |
| ||||||||
instrument |
|
The main role of an organisation in the VO (that is, the main reason for describing organisations in a registery) is as a provider or publishier of other resources. In particular, an organisation description in a registry declares the association of an IVOA identifier [ID] with the organisation. The organisation can then be referred to in other resource descriptions. For example, an organisation identifier will appear as the publisher identifier of service resource (as illustrated in our example from section 2).
The Service resource type is used to describe a service--a resource that actually does something--in the sense defined by the RM:
A service is any VO resource that can be invoked by the user to perform some action on their behalf.
The general data model is described in section
2.2.2. The Service type extends the Resource
type by adding two elements: <rights>
which
indicates who may access it, and <capability>
which
describes how the service behaves and how it is invoked.
<xs:complexType name="Service"> <xs:complexContent> <xs:extension base="vr:Resource"> <xs:sequence> <xs:element name="rights" type="vr:Rights" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="capability" type="vr:Capability" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType>
vr:Service Extension Metadata Elements | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||||||||||
rights |
| ||||||||||||||||
capability |
|
As described in section 2.2.2, multiple
capability
elements may appear, each describing a
different capability of the service.
<xs:complexType name="Capability"> <xs:sequence> <xs:element name="validationLevel" type="vr:Validation" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="description" type="vr:PaddedString" minOccurs="0"/> <xs:element name="interface" type="vr:Interface" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="standardID" type="xs:anyURI"/> </xs:complexType>
vr:Capability Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
validationLevel |
| ||||||||
description |
| ||||||||
interface |
|
The capability
element is sufficient for describing a
custom service capability--i.e., a service that is
particular to one provider and does not conform to a specific standard
(be it recognized by the IVOA or some other sub-community). However,
service standards will often create a vr:Capability
extension that adds additional metadata that are specific that that
are specific to the behavior of that particular type of service.
- Note:
- The RM defines three metadata that may be important for several standard query services: Service.MaxSearchRadius, Service.MaxReturnRecords, and Service.MaxReturnSize. These are examples of service-specific metadata that should be encoded as child elements in a type derived from
vr:Capability
.
vr:Capability Attribute | |||||||||
---|---|---|---|---|---|---|---|---|---|
Attribute | Definition | ||||||||
standardID |
|
<interface>
element is of the complex type
vr:Interface
.
<xs:complexType name="Interface" abstract="true"> <xs:sequence> <xs:element name="accessURL" type="vr:AccessURL" maxOccurs="unbounded"/> <xs:element name="securityMethod" type="vr:SecurityMethod" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>
The vr:Interface
type is defined as abstract, so as
described in section 2.2.2, the
<interface>
element must not be used as part of a
vr:Service
description unless it includes an
xsi:type
attribute that refers to a type derived from
vr:Interface
. The VOResource schema defines two derived
vr:Interface
types: vr:WebBrowser
and vr:WebService.
The vr:Interface
type provides two child elements:
<accessURL>
and <securityMethod>
.
vr:Interface Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
accessURL |
| ||||||||
securityMethod |
|
As mentioned in the table above, exactly how a client uses the value
of the <accessURL>
element depends on the specific
type derived from vr:Interface
. Extension schemas that
define non-abstract types derived from vr:Interface
MUST
provide documentation that explains the exact use of the
<accessURL>
; this documentation should follow the
documention conventions described in
section 2.2. If multiple
<accessURL>
may be provide; however, each URL should
point to a functionally identical or "mirror" installation of the same
service and administered by the same publisher listed above. An
<accessURL>
must not point to an installation
that is outside the administrative control of the service's listed
publisher; such a mirror should be describe in a separate resource
record.
As an additional aid to software agents that will attempt to interpret
its URL, the vr:AccessURL
includes an optional element,
use
(pronounced and interpreted as in the noun form of
the word use) which takes a controlled vocabulary:
vr:AccessURL Attribute | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Attribute | Definition | ||||||||||||||
use |
|
<xs:complexType name="AccessURL"> <xs:simpleContent> <xs:extension base="xs:anyURI"> <xs:attribute name="use"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="full"/> <xs:enumeration value="base"/> <xs:enumeration value="post"/> <xs:enumeration value="dir"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:extension> </xs:simpleContent> </xs:complexType>
The vr:SecurityMethod
type is
defined as a complex type but with empty content:
<xs:complexType name="SecurityMethod"> <xs:sequence/> <xs:attribute name="standardID" type="xs:anyURI"/> </xs:complexType>
vr:Capability Attribute | |||||
---|---|---|---|---|---|
Attribute | Definition | ||||
standardID |
|
While this simple element (when the standardID
attribute
is provided) may on its own be sufficient to describe the security
mechanism used, it is expected that some future
VOResource extension schema will define
additional types derived from vr:SecurityMethod
. If such
a sub-type is available, it may be employed at
securityMethod
location within a
vr:Interface
-typed element, in which case, it should be
invoked via a xsi:type
attribute to the
securityMethod
element.
vr:WebBrowser
is one of the two vr:Interface
sub-types defined by the VOResource schema. This type indicates that
the service is intended to be accessed interactively by a user through
a web browser. The <accessURL>
, then, reprensents
the URL of a web page containing one or more forms used to invoke the
service.
<xs:complexType name="WebBrowser"> <xs:complexContent> <xs:extension base="vr:Interface"> <xs:sequence/> </xs:extension> </xs:complexContent> </xs:complexType>
As can be seen in the schema definition above, the
vr:WebBrowser
type does not define any additional
interface metadata (though other vr:Interface
derivations
may). Thus, this type is provide purely for its semantic meaning.
vr:WebService
is the second vr:Interface
sub-type available from the VOResource schema:
<xs:complexType name="WebService"> <xs:complexContent> <xs:extension base="vr:Interface"> <xs:sequence> <xs:element name="wsdlURL" type="xs:anyURI" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType>
The vr:WebService
interface is one
that is described by a Web Service Description Language
[WSDL] document. This is typically realized as one
that employs the Simple Object Access Protocol [SOAP];
however, like WSDL, this interface type is not restricted to it.
With this interface, the vr:accessURL
must refer to the
service endpoint URL.
vr:WebService Extension Metadata Elements | |||||||||
---|---|---|---|---|---|---|---|---|---|
Element | Definition | ||||||||
wsdlURL |
|
- Note:
- It is intended that other
vr:Interface
types, along with additional resource types derived fromvr:Service
, will be defined in at least one other IVOA standard extension that is specifically geared to services.
http://www.ietf.org/rfc/rfc2119.txt
http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm
http://www.w3.org/TR/REC-xml
http://www.w3.org/TR/xmlschema-0/
http://www.w3.org/TR/NOTE-datetime
.
http://www.openarchives.org/OAI/openarchivesprotocol.html
.
http://www.ivoa.net/Documents/WD/SIA/sia-20040524.html
.
http://www.ivoa.net/Documents/REC/Identifiers/Identifiers-200505XX.html
.
http://cdsweb.u-strasbg.fr/simbad/refcode/refcode-paper.html
.
http://www.w3.org/TR/wsdl
.
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
.