VOResource: an XML Encoding Schema for Resource Metadata

Official bibliographic entry for published version [VOResource1.2].

Status:

VOResource 1.3 WD 2025-10-31

Acknowledgments

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 European Commission’s Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON). Funding for the 2016 update was provided by BMBF grant GAVO-2014, grant number 05A14VHA.

Conformance-related definitions

The words “MUST”, “SHALL”, “SHOULD”, “MAY”, “RECOMMENDED”, and “OPTIONAL” (in upper or lower case) used in this document are to be interpreted as described in IETF standard RFC2119 [].

The Virtual Observatory (VO) is a general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The International Virtual Observatory Alliance (IVOA) is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications.

Syntax Notation Using XML Schema

The eXtensible Markup Language, or XML, is document syntax for marking textual information with named tags and is defined by . 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 [].

The XML Schema of VOResource is available from the IVOA document repository [1] at any time. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity. Where the content of the pieces of schema embedded in this text diverges from the schema document in the IVOA document repository, the version in the schema repository is authoritative.

References to specific elements and types defined in the VOResource schema include the namespaces prefix as in (a type defined in the VOResource schema). For more details on the intended interpretation, refer to sect. 2.1 The Schema Namespace and Location.

1 Introduction

The IVOA recommendation “Resource Metadata for the Virtual Observatory” [RM1.1], hereafter referred to as the 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 organisation or a data collection. This definition is consistent with its use in the general Web community as “anything that has an identity” []. 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. The present document provides a concrete encoding of the resulting metadata model on XML suitable for embedding into OAI-PMH responses.

In addition to concepts and structures laid down in the RM, VOResource also acknowledges other (though mostly related) metadata schemes. Of particular importance here is the metadata scheme employed by DataCite, which at the time of writing is at version 4.6 []. This, in particular, concerns the alignment of the vocabularies for date roles and relationships.

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 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 intended 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 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 sect. 2.3 Extending the VOResource Schema.

1.1 Role within the VO Architecture

Fig. VOResource:fig:archdiag shows the role VOResource plays within the IVOA architecture [IVOAArchitecture2.0].

VOResource depends on the following other IVOA standards:

Resource Metadata, v1.12

The RM [RM1.1] provides the central concepts and structures mapped here into an XML schema.

There are relationships to the following other IVOA standards:

Registry Interfaces

The Registry Interfaces [RegistryInterface1.1] standard describes how registries exchange VOResource records, and it provides a -typed element to hold them within XML data (VOResource itself has no global elements).

VOResource extensions

VOResource lays the foundations upon which description schemes for concrete resources are built in various VOResource extensions. At the time of writing, recommendations have been passed for the description of VO Standards [StandardsRegExt1.0], various “simple” data discovery protocols [SimpleDALRegExt1.1], generic data services ref, and TAP services [TAPRegExt1.0]. The Registry Interfaces standard also contains a VOResource extension.

RegTAP

The Registry Relational Schema [RegTAP1.1] gives a relational mapping of the models discussed here.

VOSI

The VO support interfaces [VOSI1.1] re-use the service model developed here to facilitate service self-description.

Vocabularies

VOResource contains several controlled vocabularies that are maintained and can be used as per Demleitner et al. [Vocabularies2.1].

2 The VOResource Data Model

The primary use for VOResource, of course, is to describe a resource using the metadata concepts defined in the RM. Here is an example of a VOResource document describing an organisation, the Radio Astronomy Imaging Group at the National Center for Supercomputing Applications.

<?xml version="1.0" encoding="UTF-8"?>
<ri:Resource xsi:type="vr:Organisation"
          xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
          xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/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
                              http://www.ivoa.net/xml/RegistryInterface/v1.0
                              http://www.ivoa.net/xml/RegistryInterface/v1.0"
          created="2009-02-15T12:00:00"
          updated="2009-02-15T12:00:00"
          status="active">
    <validationLevel validatedBy="ivo://archive.stsci.edu/nvoregistry">
      2
    </validationLevel>

    <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> Crutcher, Richard </name>
            <logo>
                http://rai.ncsa.uiuc.edu/rai.jpg
            </logo>
        </creator>
        <date>1993-01-01</date>
        <contact>
            <name>Plante, R.</name>
            <email>rplante@ncsa.uiuc.edu</email>
        </contact>
    </curation>

    <content>
        <subject>radio-astronomy</subject>
        <subject>astronomy-software</subject>
        <subject>astronomy-web-services </subject>
        <subject>search-for-extraterrestrial-intelligence</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>

</ri:Resource>

This example illustrates some important components of a VOResource record:

1. the VOResource namespace (line 3),

2. the specific type of resource indicated by the value of the attribute as discussed in sect. 2.2.7 Refined Semantics with Derived Types (line 2),

3. the location of the schema documents used by this description (lines 6–9) – this is to facilitate document validation –,

4. values for the three main types of core metadata: identity (lines 17–19), curation (lines 21–36), and content (lines 38–54),

5. a reference to another resource is made by providing that resource’s IVOA identifier (line 22),

6. string values can be padded with spaces for easier readability (e.g., lines 22–24),

7. extension metadata specific to the type of resource (lines 56–59).

Actual services obviously need additional metadata defining the modalities of service access. In VOResource, such information is typically encapsulated in -typed elements. This document only provides a generic base class for them, deferring the definition of more useful subclasses to VOResource extensions like VODataService ref or SimpleDALRegExt [SimpleDALRegExt1.1].

2.1 The Schema Namespace and Location

The VOResource schema namespace URI is

\[\hbox{\nolinkurl{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 that defines the VOResource schema. Applications may assume that the namespace URI is so resolvable.

Although this schema is in version 1.3 now, the URL still ends in v1.0. This is to avoid unnecessarily breaking existing clients relying on the namespace as defined by version 1.0 of this specification. As laid out in the IVOA schema versioning policies [XMLVers1.0], although minor versions should never have been part of namespace URIs, for namespaces defined before this note they cannot be dropped despite their potential for confusion.

Clients should in general not care about minor versions of schemas. To cover the rare cases in which such information is necessary, instance documents for version 1.3 of VOResource must have a attribute with value 1.3 on their root element (i.e., ).

Document authors are strongly encouraged to bind this namespace to the prefix. While in generic XML processing, the concrete prefix used is irrelevant as long as the namespace URI mapped is the one given by this specification, in the Virtual Observatory context uniform, per-major-version prefixes are viewed as helping interoperability. This is particularly true when prefixes appear in attribute values (e.g., of ), as non-schema aware XML processors cannot URI-normalize such occurrences. Also, non-XML-aware software (e.g., ADQL engines) will use these prefixes rather than the full namespace URIs.

Authors of instance documents that use the VOResource schema may choose to provide a location for VOResource XML Schema document using the attribute; the choice of the location value is the choice of the author. In general, the use of is recommended by this specification with a 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"

The VOResource XML schema sets to unqualified. This means that instance documents must not bind the empty namespace in any element containing VOResource elements, as XML element names in VOResource must be interpreted outside of any namespace. Conversely, the VOResource namespace prefix must not be used to qualify tag names of VOResource elements.

In general, namespace prefixes in VOResource are only used to qualify type names given as values to the attribute in VOResource (see next section). VOResource extensions should also set elementFormDefault="unqualified" for consistency.

2.2 The Core Structural and Semantic Model

The VOResource schema only defines global types; it does not define any global elements (often referred 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.

The IVOA Registry Interface standard [RegistryInterface1.1], for example, at the time of writing includes a small schema that defines a global element of base type . It is primarily intended as the child of in OAI-PMH responses [], the protocol used for VOResource record exchange by Registry Interface-compliant Registries. Note that even -typed elements will still use to indicate the actual resource type.

Applications describe a single resource using an element of the type or a legal derivation of it. The content of this element is referred to as the core VOResource metadata and can be grouped into four categories (corresponding to the sections 3.1, 3.2, 3.3, and 4 of the RM):

• identity metadata: the , , and elements;

• curation metadata: the contents of the element;

• general content metadata: the contents of the element;

• metadata quality flags: the element.

These elements are defined in more detail in sect. 3 The VOResource Metadata.

2.2.1 Naming Convention

VOResource uses the following conventions for names of elements and types:

• all global types it defines have names that are capitalized. (This practice would extend to global elements, if they existed in the VOResource.)

• Locally defined elements begin with a lower-case character.

• For all types and element names that are made up of multiple words, such as , upper-case letters are used to demarcate the start of appended word (the “camel” format).

• Names that include abbreviations, such as , all letters in the abbreviation are capitalized.

It is recommended that this convention be followed in other schemas that either use the VOResource schema (via an or ) or extend it.

2.2.2 String Values

Many of the elements in VOResource that are meant to have string or URI values are defined as being of the type . 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 types will cause an XML Schema-compliant parser to replace tab, line feed, and carriage return characters with simple spaces, then replace multiple sequential occurrences of spaces with a single space, and then remove all leading and trailing spaces.

The children of resources and capabilities, on the other hand, are of type , which means that even schema-aware processors will preserve whitespace. This is intended to allow simple markup like paragraphs (empty lines) in the descriptions, which may be little texts. Since in VO practice, constructs like simple ASCII tables sometimes appear in such descriptions, clients are encouraged to not reflow descriptions and display them in a fixed-with font.

2.2.3 Language and Transliteration

Several VOResource elements contain natural language (e.g., or ). In order to ensure reliable discovery, in core VOResource, these elements must contain English text, with US spelling strongly preferred; technically, an value of en-US is implied.

Registry extensions may allow attributes on elements. If they do, such elements must be repeatable, and an element without (and hence, en-US implied) should be required for global discoverability. The requirements on from the XML specification [] apply. Additionally, in VOResource documents BCP 47 language identifiers must be written in lowercase.

Several VOResource elements contain names. Again, for reliable global discoverability, such names must be given in (common) English transliteration where their original form uses non-Latin scripts. Latin letters with diacritics are allowed, but Registry components are generally expected to treat them equivalent to their base letters.

2.2.4 Dates and Times

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. The type provides a special restriction of the format that requires inclusion of date and time, but enforces the use of the UTC timezone. The time format to be used by VOResource (designed to coincide with what the OAI-PMH transport protocol mentioned above defines) therefore requires timestamps like

\[\hbox{\texttt{2008-02-22T12:22:34Z}},\]

where optional fractional seconds are allowed. See the schema documentation for the actual regular expression pattern.

For historical reasons, VOResource also allows a form without any timezone marker. Such timestamps are to be interpreted as if they had a trailing Z.

Where day granularity might suffice for some instance documents, VOResource and extensions can employ the type.

2.2.5 Alternate Identifiers

While registered resources should be referenced with their IVOA identifiers in order to allow simple and uniform resolution, other identifier schemes are frequently useful in order to have machine-readable references to entities not registered (e.g., authors) or also resolvable using external resolvers. Prime examples for such identifiers are DOIs and ORCIDs.

VOResource keeps such identifiers in elements (for resources and creators, which can have multiple such identifiers) or attributes (for elements of type , which for simplicity are only allowed one alternate identifier each).

In order to not bind the Registry to any single resolver, we prefer non-http URI forms for such identifiers. Where the originators of the identifier scheme strongly urges the use of http URIs directly pointing to a resolver, we adopt these conventions.

The following identifier schemes are recognised by VOResource in this version:

doi

A digital object identifier. These always use the doi URI schema rather the http schema. Hence, in VO resource records, doi:10.5072/7273288 must be used rather than https://doi.org/10.5072/7273288 or any of its variants.

orcid

An open researcher and contributor id. In accordance with ORCID’s instructions [2], ORCIDs must be given as HTTPS URIs using orcid.org’s infrastructure, for instance https://orcid.org/0000-0001-2345-6789.

bibcode

A bibliographic code as used by ADS and CDS []. These must be used with an ad-hoc URI scheme of bibcode, as in bibcode:2008ivoa.spec.0222P.

ROR id

An identifier for an organisation (and hence suitable in elements like or records of type ) taken from the Research Organization Registry [3]. In accordance with their 2024 preferences, ROR identifiers in VOResource always use the browser-resolvable URL form with an https schema, such as https://ror.org/04rcqnp59. This regulation stays in place for VOResource even if upstream reconsiders this preference.

Other schemes may be used in -s.

2.2.6 VOResource Semantics

All VOResource types and elements have an associated semantic meaning which is given in the first 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.

Here are three examples that illustrate the semantics communicated by VOResource entities:

1. The type describes the curation of a resource. The element describes curation of the specific resource described by the enclosing type and identified by its element.

2. The type is a generic reference to another resource. The element gives a reference to the publisher of the specific resource being described which may itself be a registered resource described elsewhere.

3. The element gives the title of the resource being described by the enclosing type and identified by its element. The element’s type, (a restriction on ), has no inherent meaning associated with it.

Additional semantics are transmitted through the use of derived types using the attribute. In the sample instance document above, the use of the XSI type vr:Organisation means that the resource being described is specifically an organisation as defined by the type. This type provides additional metadata that are not part of the core resource metadata. The semantics associated with the use of is described further in the next subsection.

2.2.7 Refined Semantics with Derived Types

When a resource is described with an element explicitly of the type , 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 type; rather, they will use types that are derived from .

Defining derived types accomplishes two things:

1. it sharpens the semantic meaning of the resource description by indicating what specific type of resource it is, and

2. it may allow additional metadata not part of the core but specific to that type of resource.

The VOResource schema defines two types derived from : and . The adds metadata describing the astronomical facilities such as telescopes that are associated with the organisation it describes. The type adds an element called which describes the service’s interface as well as information regarding its behavior.

Extension of the type is a key way in which derivation is used in VOResource to provide refined resource descriptions. Two other important parent types in the schema are and ; these are extended to provide more refined descriptions of services (see sect. 2.2.8 The Service Data Model). The motivation for extending these types is the same as for : 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 without adding any additional metadata.

As described in sect. 2.2 The Core Structural and Semantic Model, it is intended that derived , and types be invoked in instance documents using the 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 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 is substitution groups. Invoking derived 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.

2.2.8 The Service Data Model

The type extends the core metadata data by adding the element (see sect. 2.3.2 Defining New Service Capabilities and Interfaces). 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 elements, each describing a different major functionality; however, these capabilities should be related in an obvious, logical way (they would hardly share their core VOResource metadata otherwise).

The element, through its type , describes the behavior of service capability and how to access it. The latter is described by a child element. As for the behavior, the base type only provides a element that can contain human-readable text on what this capability provides. More structured behavioral information must be provided through specialized extensions. In particular, a service standard (e.g. Simple Image Access Protocol) or an ancillary standard built upon the service standard will define an extension of that adds additional metadata that can describe the service’s behavior in relation to the standard.

The added metadata can describe limitations of the service implementation or indicate support for optional features. As a rough guideline, whenever the standard has a SHOULD or MAY in the sense of RFC2119 and clients have no other way to discover the choices of a concrete service implementation, a respective declaration should be considered for the capability or the interface elements defined by the registry extension.

The specific type is invoked using the mechanism described in sect. 2.1 The Schema Namespace and Location. Here is an example for assigning a specialized Capability type for a standard service capability. In this example, it is assumed that extension type is defined in a separate schema document, the target namespace of which is being bound to the prefix in the capability element itself (it could, of course, be bound in some enclosing element just as well):

<capability xsi:type="ex:ExampleCapType"
  standardID="ivo://example.com/std/exampleAccess"
  xmlns:ex="http://ivoa.net/std/example-1.xsd">
  ...
</capability>

Note that the and the can vary independently of each other. There is no requirement to use a given capability type for an endpoint conforming to a certain standard, as indicated by the capability’s . Conversely, it may make sense to re-use a certain capability type in a different standard.

Historically, several VOResource extension types have had fixed :raw-latex:`xmlel{standardID}`s. This is now discouraged, as it needlessly limits the applicability of the encoded metadata models.

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 can be used as-is, possibly with the appropriate .

Each element can contain one or more child elements, each describing how the capability can be accessed. The element’s type, , is abstract; thus, the element must be accompanied by an attribute that indicates a extension type. The VOResource schema defines two extension types: , for describing an interface access via web browser, and , for accessing a service described by a Web Service Description Language (WSDL) document. In today’s VO, the latter interface type has almost vanished with the general move away from SOAP-based architectures. VO standard capabilities currently typically use interface types defined in VODataService. [4]

As an example, a simple, browser-based interface could be declared with an untyped capability like this (this assumes the prefix has been bound in an ancestor element):

<capability>
  <interface xsi:type="vr:WebBrowser">
    <accessURL use="full"
      >http://example.org/browser-service</accessURL>
  </interface>
</capability>

Note that for less trivial interfaces, in particular , the parameters accepted should be declared in the interface element.

When a contains more than one , each should be interpreted as an alternative interface for accessing essentially the same underlying capability. The interfaces can differ in their overall type (e.g. , ) or in the supported input parameters or output products.

When a standard capability is being described (i.e., there is a attribute), then at least one of the elements should describe an interface required by the standard. The attribute is used to mark the standard interfaces (typically with the value “std”). All other interfaces are considered non-standard alternatives. To best support real-world discovery strategies, it is recommended to avoid having non-standard interfaces in capabilities with well-known :raw-latex:`xmlel{standardID}`s.

Another way xmlel{capability}` element can be used is if a standard forsees different versions of a protocol within the same capability. Different interfaces can then be distinguished by different values of the interface’s attribute. Previous versions of this document in effect recommended this pattern for VO standards.

While this pattern can still be employed, most VO standards that actually have different versions distinguish their endpoints by different standard identifiers, as described in section 4.2 of IVOA Identifiers 2.0 [IVOAIdentifiers2.0]. In these cases – where the ’s attribute already uniquely determines the protocol spoken –, the specification of on elements is optional (although encouraged).

2.3 Extending the VOResource Schema

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 :raw-latex:`xmlel{xsd:do-cumentation}` element inside the type or element definition. Subsequent documentation elements may provide additional comments or discussion.

• Avoid the use of :raw-latex:`xmlel{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; for examples, see the and defintions in VODataService 1.1 [VODataService1.1].

• Avoid the use of substitution groups. VOResource prefers instead the use of which are (with a few exceptions) functionally equivalent to substitution groups in terms of structure; however, 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 type, used to define specific types of resources, and the derivation of service metadata elements.

2.3.1 Defining New Resource Types

Derivation of to define new kinds of resources should be done by extension (i.e., using ) rather than restriction. It is not required that the derived type change the content model from that of the base type; in this case, the purpose of the derivation is only to sharpen the semantic meaning of the resource description.

In VOResource itself, this mechanism is used to derive and .

2.3.2 Defining New Service Capabilities and Interfaces

As described in sect. 2.2.8 The Service Data Model, a service standard will often define a new extension type to allow implementations to describe how they support the standard. This definition of the 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.

An extension schema can define new interface types, though not necessarily in the context of any specific standard service capability. The basic type provides only , , and as child elements. A derived type must indicate in the documentation how the 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.

Examples for extension schemas can be found in the IVOA Document Repository. [5] Sect. 1.1 Role within the VO Architecture enumerates the ones in Recommendation state at the time of writing. In VOResource itself, the mechanism can be inspected in the derivation of and .

3 The VOResource Metadata

This section enumerates the types and elements defined in the VOResource schema.

3.1 The Base Resource Type

A resource, as defined by the RM, is any entity or component of a VO application that is describable and identifiable by an IVOA Identifier. A resource is described using VOResource by an element of the type 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 through 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.

Note that the attributes (, , ) represent a special class of metadata: they describe the resource metadata contained within the itself as opposed to the resource being described. Also note that with OAI-PMH 2.0, VOResource records that would have a of deleted should not occur since OAI-PMH mandates that is empty for deleted records, and VOResource’s essentially is a refinement of OAI-PMH’s . Having VOResource records with set to deleted might still be useful outside of OAI-PMH.

The attribute of an element gives the version of the schema it was written against, as prescribed in the IVOA Note “XML Schema Versioning Policies” [XMLVers1.0]. If missing, the value of this attribute can be assumed to be 1.0. This attribute should not be used to locate the schema file – clients should either consult or retrieve the latest schema for the namespace from the IVOA schema repository.

The following sections discuss the complex types mentioned in the above definitions. All rules and advice given in the “Comments” portions in the RM definition for the individual items apply. In some details, in particular as regards enumerations of values, this document deviates from RM in content.

3.1.1 Identity Metadata

The identity metadata described in the RM (section 3.1) are represented as top-level children of the type.

Two special types, and are defined to support identity metadata. The definition enforces the 16-character limit on shortNames.

3.1.2 Curation Metadata

The curation metadata described in the RM (section 3.2) are bundled together into the child element . Its content is defined by the complex type.

Resource Names

Several of the curation elements (most importantly, and ) make use of the type. This type provides a means of referring to another resource, by name, by its IVOA identifier, or by some other identifier scheme. Not all resources referred to using this type will necessarily be registered and, therefore, will have an IVOA identifier; thus, the identifier (which is encoded as an attribute) is optional.

For entities registered in some other way – in particular, DOIs or ORCIDs –, resource names can give -s.

The Creator Type

The element is defined by the complex type which bundles together the RM metadata Creator and Creator.Logo.

The ’s should contain exactly one name. Since the creator name is what Registry users use when searching for resources “by author”, it should be set with care. To make sensible collation simple for clients, person names should be formatted last name first wherever appropriate.

In collaborative efforts, multiple creator elements should be used, one element per person or organisation involved.

Examples for encouraged use of creator include:

<creator>
    <name>van der Waals, Johannes Diderik</name>
  </creator>
  <creator>
    <name>de Vaucouleurs, G.</name>
  </creator>
  <creator>
    <name>Zhang Hailong</name>
  </creator>
  <creator>
    IVOA Registry Working Group
  </creator>

While the following uses of creator do not make a resource record technically invalid, they are frowned upon:

<creator>
    <!-- do not include multiple names in one name element -->
    <name>Mornilov, V.G., Polkov, I.M., Bakharov, A.I</name>
  </creator>
  <creator>
    <!-- Do not include functions or similar -->
    <name>PI: Ita Varajedini</name>
  </creator>
  <creator>
    <!-- Do not abuse creator for provenance, do not include markup -->
    <name>All data is downloaded from the &lt;a href=http:...</name>
  </creator>

In VOResource 1.1 the and elements received child elements, mainly to enable inclusion of ORCIDs in VOResource documents. In VOResource version 1.2, the type received an attribute, and hence an alternate identifier like an ORCID can be communicated through the children of and .

We hence deprecate the children in these two elements (but not in itself). New resource records must use the attributes to communicate ORCIDs or similar identifiers for persons.

Dates and Their Roles

The element’s type, , is an extension of the type that adds an optional attribute called .

The purpose of the role attribute is to indicate what aspect of the resource the date describes. This allows several elements to be provided, each with a different role. The possible values for this attribute are not controlled by the schema. The IVOA, however, defines an RDF vocabulary at http://www.ivoa.net/rdf/voresource/date_role from which the terms should be taken if at all possible. At the time of writing, the vocabulary consists of three old-style VOResource 1.0 terms and terms from the DataCite Metadata 4.6 []; see the RDF URL for the definitions of the terms. The following identifiers are available at the time of writing (omitting deprecated ones):

Accepted, Available, Collected, Copyrighted, Created, ExportRequested, Inspected, Issued, Submitted, Updated, Valid

Terms can be added to this vocabulary without changes to this specification. Applications are not expected to support semantic relationships between the terms (except for mapping the deprecated VOResource 1.0 terms to the modern DataCite Metadata ones).

The Contact Type

The element is defined by the type which bundles together several component pieces of information, including the RM metadata Contact.Name and Contact.Email.

3.1.3 General Content Metadata

The general content metadata described in the RM (section 3.3) are bundled together into the child element . Its content is defined by the complex type.

The content of should be drawn from the Unified Astronomy Thesaurus (UAT), the concepts of which are identified through human-readable fragments given in the IVOA-flavoured UAT at http://www.ivoa.net/rdf/uat. The details and the rationale of the IVOA’s use of the UAT are discussed in Demleitner and Frey [uat-as-upstream1.0].

The content of should conform to the values from a vocabulary. At the time of writing, this vocabulary contained the terms:

Amateur, General, Research

For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/content_level.

The content of should conform to the values from a vocabulary. At the time of writing, this vocabulary contained the terms:

Animation, Archive, Artwork, Background, BasicData, Bibliography, Catalog, Education, EPOResource, Historical, Journal, Library, Organisation, Other, Outreach, Photographic, Press, Project, Registry, Simulation, Survey, Transformation

For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/content_type.

The element’s type, , is an extension of the type that adds an optional attribute called .

The is defined by the complex type which bundles together the RM metadata Relationship and RelationshipID.

The nature of the relationship is given by relationshipType. The values of this are taken from a vocabulary that is available in RDF form at http://www.ivoa.net/rdf/voresource/relationship_type. This vocabulary at the time of writing consists of

• the terms from VOResource 1.0 (mirror-of, service-for, served-by, derived-from, and related-to); these are guaranteed to remain within VOResource 1.x

• selected terms from the DataCite Metadata relationType enumeration.

The resulting mix of term styles is an aesthetic defect that may actually lead to the construction of invalid terms. While, for backward compatibility, we will not drop the VOResource 1.0 terms in VOResource 1.x, they should not be used in new records. Instead, resource records should use the terms given as Preferred in the vocabulary retrievable at the URL given above.

At the time of writing, the full vocabulary consists of these terms (omitting deprecated ones):

Cites, Continues, HasPart, IsContinuedBy, IsDerivedFrom, IsIdenticalTo, IsNewVersionOf, IsPartOf, IsPreviousVersionOf, IsServedBy, IsServiceFor, IsSourceOf, IsSupplementedBy, IsSupplementTo

For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/relationship_type.

3.1.4 Resource Record Quality with validationLevel

The RM’s ResourceValidationLevel is encoded in the VOResource schema with the element, which can appear in multiple places within a type or sub-type. It may appear zero or more times as direct children of a type and/or, if the resource is a type or sub-type, zero or more times as the first children of any element.

The element’s attribute takes an IVOID as a value. This IVOID must refer to a registered organisation or registry that assigned the numerical value. The element can appear multiple times, each with a different value, to reflect the code assigned by different organisations.

3.2 Resource Type Extensions: Organisation and Service

The VOResource schema defines two extensions of the base type for describing two specific types of resources: and . In addition to providing more refined semantic meanings over , they add additional metadata for describing the resource which do not necessarily apply in the generic case.

3.2.1 The Organisation Resource Type

The 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, and :

The main role of an organisation in the VO (that is, the main reason for describing organisations in a registry) is as a provider or publisher of other resources. In particular, an organisation description in a registry declares the association of an IVOA identifier 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 the opening example in sect. 2 The VOResource Data Model).

3.2.2 The Service Resource Type

The resource type is used to describe a service–a resource that actually does something – in the sense defined by the RM:

:raw-latex:`noindent `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 sect. 2.2.8 The Service Data Model. The Service type extends the Resource type by adding two elements: which indicates the modalities of service use and access, and which describes how the service behaves and how it is invoked.

Declaration of copyrights, usage limitations, and licenses

The element contains free text, where it is recommended that standard licenses are named and special circumstances like embargoes are mentioned. The attribute can be used to reference the full license text. In order to facilitate automatic identification of usage conditions, it is strongly recommended to use the license URIs [6] maintained by the System Package Data Exchange SPDX.

While the schema allows multiple elements and thus multiple license URIs, within the VO such use is discouraged. This means that clients that discard information from additional elements are not considered to be in violation of this specifiation. In practice, resource record authors should place all usage limitations, citation recommendations, etc., directed at VO users in the first element.

An example could look like this:

<rights rightsURI="https://spdx.org/licenses/CC-BY-4.0.html">
  The images from the X survey are copyright 2016, the X project.
  They are published under the creative commons attribution 4.0
  international license.  If you use this data, please cite
  doi:10.5072/7273288.

  Images are under embargo for one year after their addition to the
  repository.
</rights>

Service capabilities

As described in sect. 2.2.8 The Service Data Model, multiple elements may appear, each describing a different capability of the service.

The 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 extension that adds additional metadata that are specific to the behavior of that particular type of service.

More on interfaces

The element is of the complex type ; its usage, in particular as regards the mandatory use of its attribute and typical values thereof, is discussed sect. 2.2.8 The Service Data Model.

Exactly how a client uses the value of the element depends on the specific type derived from . Extension schemas that define non-abstract types derived from MUST provide documentation that explains the exact use of the ; this documentation should follow the documention conventions described in sect. 2.2 The Core Structural and Semantic Model.

In version 1.0, operators of services with multiple mirrors were encouraged to give multiple elements. This feature was not used in practice, presumably for concerns users might end up on remote mirrors. Since version 1.1, we therefore deprecate multiple within an interface. Access URLs of actual mirrors can now be declared using elements. As before, neither nor must not point to an installation that is outside the administrative control of the service’s listed publisher; such a mirror should be described in a separate resource record. To aid in user interfaces for mirror selection, admits a attribute:

Declaring access restrictions

The type is defined as a complex type but with empty content:

While this simple element (when the 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 . If such a sub-type is available, it may be employed at location within a -typed element, in which case it should be invoked via a attribute to the element.

Web browser interfaces

is one of the two 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 , then, represents the URL of a web page containing one or more forms used to invoke the service.

As can be seen in the schema definition above, the type does not define any additional interface metadata (though other derivations may). Thus, this type is provided purely for its semantic meaning.

is the second sub-type available from the VOResource schema:

Legacy web service interfaces

The interface is one that is described by a Web Service Description Language [] document. This is typically realized as one that employs the Simple Object Access Protocol []; however, like WSDL, this interface type is not restricted to it. With this interface, the must refer to the service endpoint URL.

Note that must not be used when no WSDL for the service is available. This is true for all modern VO standard services. It is thus unlikely that modern services will use this interface. See sect. 2.2.8 The Service Data Model for details.

Appendices

A Change History

A.1 Changes from REC-1.3

• Deprecated the attributes of and .

A.2 Changes from PR-1.2

• Also listing ROR as a recognised identifier type.

• Replacing “representative” as vr:Date/@role’s defaut with “Collected” as per the date_role vocabulary. This replacement has alreday been done by RegTAP services since VOResource 1.1.

A.3 Changes from REC-1.1

• Adding an altIdentifier attribute to to let data providers use DOIs when declaring relationships. This also covers what and was created for. These special constructs introduced in version 1.1 are now deprecated again.

• We now specify that “using the UAT” from version 1.1 means “use fragments into http://www.ivoa.net/rdf/uat/#”.

• Now strongly recommending to use SPDX URIs for rightsURI.

• Adding doi as a recognised source format.

• The schema now requires referenceURLs to have http or https URI schemes.

A.4 Changes from PR-20171107

• Editoral changes after DAL and Semantics RFC comments.

A.5 Changes from PR-20170425

• now only allows zero or one elements (rather than zero to unlimited in version 1.0). This is to keep discovery patterns simple in the presence of services requiring authentication. While this is a potentially incompatible change, no actual records have ever used multiple security methods, and the change has been agreed upon with the stakeholders at the time of the change.

• creator and contact can now have ivo-id attributes (analogous to publisher and contributor); these are intended for when the roles are filled by organizations.

• @updated and @created on resource are now vr:UTCTimestamp rather than xs:datetime. There has always been a textual requirement that these are UTC. This is now enforced by the schema.

• The schema example for an ORCID used a non-standard URI form. It is now deleted, and the text gives an example for an https URI.

A.6 Changes from WD-20170123

• Explanation for mismatch between namespace URI and actual version.

• has erroneously had multiplicity 0…n. It is now defined as 0…1.

• Adopting DataCite 4.0 as upstream, explanation of the relationship between VOResource 1.0 and DataCite terms.

• altIdentifier is now allowed on Contact now (mainly for symmetry with Creator).

A.7 Changes from WD-20161010

• Now recommending the Unified Astronomy Thesaurus instead of the old IAU Thesaurus.

• date/role terms are now flat (rather than deprecated terms being specialisations of their successors).

A.8 Changes from REC-1.03

• Adopting DataCite as another “upstream” in addtion to RM.

• While we still reference RM, it is now no longer informally authoritative for VOResource (we’d have to change RM before we change VOResource otherwise)

• References to the RM terms in the metadata definition dropped (could add support in ivoatex/schemadoc if we want them back).

• Adding altIdentifier elements to creator and resource.

• Adding a version attribute to vr:Resource for compliance with XML Schema Versioning Policies

• The vocabulary of date/@role is now managed as a separate resource; DataCite terms have been added to it, and the old 1.0 terms deprecated.

• The vocabulary of relationshipType is now managed as a separate resource; some DataCite terms have been added to it.

• Service/rights now is free text rather than the tree-term enumeration. In addition, it now has a rightsURI attribute, DataCite-style.

• content/type is now xs:token rather than a special restriction. The vocabulary is now managed as an external resource. Consequently, the vr:Type type vanishes from the XSD.

• content/level is now xs:token rather than a special restriction. The vocabulary is now managed as an external resource. Consequently, the vr:ContentLevel type vanishes from the XSD.

• New testQueryString and mirrorURL children of interface.

• Now discouraging fixing standardID in VOResource extensions. Also, removed indication that capability/@xsi:type should be used for service discovery.

• Now allowing a Z timezone marker in UTCTimestamp, indeed discouraging non-timezone use. This is in line with OAI-PMH use. Therefore, while technically changing the schema such that legacy clients might be confused, we do not expect incompatibilites.

• resource/description and capability/description are now xs:string to enable simple plain text markup.

• Adding language on using capability/@standardID rather than interface/@ver:raw-latex:`-`sion to distinguish between different protocol versions in the normal case, removed skynode example.

• Consequently, removing 1.0 default on interface/@version.

• Added advice about the use of creator.name

• Removed SOAP/WSDL example and a bit of the accompanying language.

• Section 3 needed some refactoring since the schema documentation is now generated from the schema document. To accommodate this, some text manually embedded within the schema documentation had to be moved out of the generated material or removed.

• Strongly advising the use of the vr: prefix, removing some duplicated advice regarding prefixes

• Removed example for deriving a SIA capability (this is now in the document repository)

• Ported document source to .

A.9 Changes from v1.02

• converted to Recommendation

A.10 Changes from v1.01

• attribute is now required.

• added this Change History appendix.

A.11 Changes from v1.0

• dropped , and replaced with .

• made ’s attribute required.

• reference citation correction for SOAP, WSDL

[1]

http://www.ivoa.net/xml

[2]

https://support.orcid.org/knowledgebase/articles/116780

[3]

https://ror.org

[4]

Retrospectively, should probably have been part of VOResource itself; changing this now, however, does not seem to be worth the migration effort.

[5]

http://ivoa.net/documents; TAPRegExt or SimpleDALRegExt give starting points. The actual schema files are available from http://ivoa.net/xml.

[6]

https://spdx.org/licenses/