IVOA

VOStandard: a VOResource Schema Extension for Describing IVOA Standards
Version 0.3

IVOA Working Draft
8 May 2009

This version:
http://www.ivoa.net/Documents/WD/ReR/VOStandard-XXXX.html
Latest version:
http://www.ivoa.net/Documents/latest/VOStandard.html
Previous versions
Authors:
Paul Harrison, Editor
Douglas Burke
Ray Plante
Guy Rixon
Dave Morris
and the IVOA Registry Working Group.

Abstract

This document describes an XML encoding standard for metadata about IVOA standards themselves, referred to as VOStandard. We describe the general model for the schema and explain how it may be included in other schema as a methodology of avoiding XML enumerations. This schema is primarily intended to support interoperable registries used for discovering resources.

Preface

Status of this document

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 "works in progress".

Comments on this document for consideration in the next version are welcome. They can be sent to registry@ivoa.net, a mailing list with a public archive or on the VOStandard twiki discussion page. When this document becomes a Proposed Recommendation, an official public Request For Comment period will begin.

A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.

Editor's Note:
Parts that the editor considers should be removed from the document are marked in red with a strike through line, and sections that need more work are indicated in green.

Acknowledgements

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).

This document contains text lifted verbatim, with small changes, and with substantial changes from the previously published VODataService specification [VODataService] (e.g. sections 2.0). This has been done without specific attribution as a means for providing consistency across similar documents. We acknowledge the authors of that document for this text.

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, RFC 2119 [RFC 2119].

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 defined 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.

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 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 VOStandard 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). Reference to specific elements and types defined in the VOStandard schema include the namespaces prefix, vstd, as in vstd:ServiceStandard (a type defined in the VOStandard schema). Use of the vstd prefix in compliant instance documents is strongly recommended, particularly in the applications that involve IVOA Registries (see [RI], section 3.1.2). Elsewhere, the use is not required.

Contents

Introduction

An important goal of the IVOA is to publish standards for services which can interoperate to create a Virtual Observatory (VO). Central to the coordination of these services is the concept of a registry ([RegInt]) where resources can be described and thus discovered by users and applications in the VO. The standard Resource Metadata for the Virtual Observatory [Hanisch et al. 2004] (hereafter referred to as RM) defines metadata terms for services and other discoverable resources. A specific XML encoding of these resources is described in the IVOA standard VOResource: an XML Encoding Schema for Resource Metadata [Plante et al. 2006] (hereafter refered to as VOResource). In this schema, support for a standard service protocol is described as a service's capability; the associated metadata is contained within the service resource description's <capability> element. The specific standard protocol supported is uniquely identified via an attribute of the <capability> element called standardID whose value is a URI. The VOResource standard does not place a formal validation requirement on the standardID other than it be a legal URI; however, it was intended that IVOA-endorsed standards would represented via an IVOA identifier. As per the IVOA Identifier standard [ID], an IVOA identifier must be registered as a resource in an IVOA-compliant registry.

This document defines a VOResource extension schema call VOStandard which allows one to describe a standard and register it with an IVOA registry. By doing so, a unique IVOA identifier becomes "attached" to the standard which can be referred to in other resource descriptions, namely for services that support the standard. Not only does this aid in the unambiguous discovery of complient service instances but also in validating their descriptions and support for the standard. Another benefit of associating an IVOA identifier with a standard is that allows registry users who discover services that conform to particular standard to also discover the document that describes that standard.

VOStandard has two other purposes. First, it allows a service protocol description to communicate specifics about the standard input parameters and output formats specified by the standard. Such a machine-readable description of the interface can assist intelligent portals and applications to build GUI interfaces to standard services and manage workflows built around them. Second, it allows for the definition of small controlled sets of standardized names (referred to as keys in this document) which might be used to identify, for example, specific features of a standard protocol (such as supported data transport protocols). By virtue of being defined within the context of a VOResource description, one can refer to the key using a globally unique URI by adding the key name as a URI fragment [ref] onto IVOA identifier associated with the descriptions.

It is envisaged that VOStandard instances that describe standards endorsed or otherwise in development by the IVOA will be published in the IVOA Registry of Registries [RofR] using the authority identifier [ID], ivoa.net. However, other standards, be they ad hoc or endorsed by another body, may be published in any compliant registry.

The VOStandard Data Model

The VOStandard extension in general enables the description of three types of resources:

Here's an example of defining a controlled list of computer languages that might be referred to in other descriptions of applications. Should other languages become prevalent, this resource description could be updated to add the new names.

An example of defining a list of programming languages
<ri:Resource xsi:type="vstd:StandardKeyEnumeration" created="2001-12-31T12:00:00"
             updated="2001-12-31T12:00:00" status="active">
   <title>application languages</title>
   <identifier>ivo://ivoa.net/std/application/languages</identifier>
   <curation>
      <publisher>IVOA</publisher>
      <creator>
         <name>IVOA</name>
         <logo>http://www.ivoa.net/icons/ivoa_logo_small.jpg</logo>
      </creator>
      <date role="representative">2006-07-17</date>
      <version>1.0</version>
      <contact>
         <name>IVOA Grid Registry WG</name>
         <email>registry@ivoa.net</email>
      </contact>
   </curation>
   <content>
      <subject>standard language identifiers</subject>
      <description>
         These language identifiers are to be used in the value of the
         va:ProgrammingLanguage type
      </description>
      <referenceURL>http://www.ivoa.net/twiki/bin/view/IVOA/IvoaResReg</referenceURL>
   </content>
   <key name="C">
      <description>The C programming language</description>
   </key>
   <key name="CPP">
      <description>The C++ programming language</description>
   </key>
   <key name="CSharp">
      <description>The C# programming language</description>
   </key>
   <key name="FORTRAN">
      <description>The FORTRAN programming language</description>
   </key>
   <key name="Java">
      <description>The Java programming language</description>
   </key>
   <key name="Perl">
      <description>The Perl programming language</description>
   </key>
   <key name="Python">
      <description>The Python programming language</description>
   </key>
</ri:Resource>

The Schema Namespace and Location

The namespace associated with VOStandard extensions is "http://www.ivoa.net/xml/VOStandard/v1.0". Just like the namespace URI for the VOResource schema, the VOStandard namespace URI can be interpreted as a URL. Resolving it will return the XML Schema document (given in Appendix A) that defines the VOStandard schema.

Authors of VOResource instance documents may choose to provide a location for the VOResource XML Schema document and its extensions using the xsi:schemaLocation attribute. While the choice of the location value is the choice of the author, this specification recommends using the VOStandard namespace URI as its location URL (as illustrated in the example above), as in,

xsi:schemaLocation="http://www.ivoa.net/xml/VOStandard/v1.0
                    http://www.ivoa.net/xml/VOStandard/v1.0"

Note:
The IVOA Registry Interface standard [RI] actually requires that the VOResource records it shares with other registries provide location URLs via xsi:schemaLocation for the VOResource schema and all legal extension schemas that are used in the records. This rule would apply to the VOStandard schema.

The prefix, vstd, is used by convention as the prefix defined for the VOStandard schema; however, instance documents may use any prefix of the author's choosing. In applications where common use of prefixes is recommended (such as with the Registry Interface specification [RI]), use of the vstd prefix is recommended. Note also that 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.

As recommend by the VOResource standard [VOR], the VOStandard schema sets elementFormDefault="unqualified". This means that it is not necessary to qualify element names defined in this schema with a namespace prefix (as there are no global elements defined). The only place it is usually needed is as a qualifier to a VOStandard type name given as the value of an xsi:type attribute.

Summary of Metadata Concepts

The VOStandard extension defines three new types of resources. Two are specifically for independently documented standards:
vstd:Standard
This resource describes a general standard (e.g. data model, schema, protocol, etc.). The most important piece of metadata associated with this resource is the <referenceURL> (from the core VOResource schema) which should point to the human-readable specification document that defines the standard. It also allows one to provide the recommended version of the standard to use.
vstd:ServiceStandard
This resource type, which extends from vstd:Standard, is specifically for describing a standard service protocol (e.g. Simple Cone Search). It differs from vstd:Standard in that it also allows one to describe specific constraints on the service interface via its <interface> element.
vstd:StandardKeyEnumeration
This resource type allows for the description of a related set controlled names (referred to as keys) and their meanings. While keys can be defined as part of a vstd:Standard or vstd:ServiceStandard resource, the vstd:StandardKeyEnumeration allows a set of key definitions stand as a resource on its own, regardless of whether it is part of a documented standard or not.

Defining Enumerations of Identifiers

A common practice when defining metadata to restrict certain string values to a controlled sets of defined names, each with a well-defined meaning. With XML Schema, the controlled set can be enforced by a validating parser (using the xsd:enumeration construct [Schema]). One disadvantage of locking in the vocabulary in an XML Schema document is that growing list of allowed names requires a revision of the XML Schema document, which can be a disruptive change. To avoid this, it is the practice VOResource and its extensions to avoid "hard-coded" enumerations in the XML Schema document for sets of defined values that will likely change over time.

The VOStandard schema provides an alternative to XML Schema-based definitions of controlled names. Instead, a controlled list of names, called keys, can be defined as part of any of the three VOStandard resource types. Updating a resourse description is much less disruptive than a Schema document, and as a resource available via an IVOA-compliant registry, it is still possible for a (non-Schema-based) application to validate the use of the vocabulary.

The VOStandard specification also defines a mapping from a key name to a URI. This allows these keys--and their underlying meaning--to be referenced in a globally unique way in a variety of contexts, not restricted to XML.

A key is defined using the vstd:StandardKey type which consists simply of a name and a description. The key is mapped to a URI by attaching the name as the "fragment"--i.e., appending after a pound sign, #--to the IVOA identifier for the resource description that defines the key:

ivoa-identifier#key-name
where ivoa-identifier is the resource's IVOA identifier and key-name is the name of a key defined in that resource.

For example with a key named case-insensitive defined within a resource description with an IVOA identifier given by <identifier> ivo://ivoa.net/std/QueryProtocol <identifier>, the URI identifying this key would be:

ivo://ivoa.net/std/QueryProtocol#case-insensitive

This form of defining multiple keys, each with its own mapping to a URI, all in one resources has several advantages:

Note:
When these enumerations are presented to a user in a GUI it is expected that the only the "fragment" part that distinguishes the various members of the enumeration will be used as a choice value, as the full IVO ID is not usually particularly "user-friendly".

Some applications may wish to publish additional metadata associated with a key definition through further extension of VOResource metadata. This can be be done by deriving a new key metadatum type derived by extension from the vstd:StandardKey.

An example of defining a list of programming languages
<ri:Resource xsi:type="vstd:StandardKeyEnumeration" created="2001-12-31T12:00:00"
             updated="2001-12-31T12:00:00" status="active">
   <title>application languages</title>
   <identifier>ivo://ivoa.net/std/application/languages</identifier>
   <curation>
      <publisher>IVOA</publisher>
      <creator>
         <name>IVOA</name>
         <logo>http://www.ivoa.net/icons/ivoa_logo_small.jpg</logo>
      </creator>
      <date role="representative">2006-07-17</date>
      <version>1.0</version>
      <contact>
         <name>IVOA Grid Registry WG</name>
         <email>registry@ivoa.net</email>
      </contact>
   </curation>
   <content>
      <subject>standard language identifiers</subject>
      <description>
         These language identifiers are to be used in the value of the
         va:ProgrammingLanguage type
      </description>
      <referenceURL>http://www.ivoa.net/twiki/bin/view/IVOA/IvoaResReg</referenceURL>
   </content>
   <key name="C">
      <description>The C programming language</description>
   </key>
   <key name="CPP">
      <description>The C++ programming language</description>
   </key>
   <key name="CSharp">
      <description>The C# programming language</description>
   </key>
   <key name="FORTRAN">
      <description>The FORTRAN programming language</description>
   </key>
   <key name="Java">
      <description>The Java programming language</description>
   </key>
   <key name="Perl">
      <description>The Perl programming language</description>
   </key>
   <key name="Python">
      <description>The Python programming language</description>
   </key>
</ri:Resource>

The VOStandard Metadata

Standard Keys: StandardKeyEnumeration

Describe StandardKeyEnumeration type here

vs:DataCollection Type Schema Definition
<xs:complexType name="DataCollection">
   <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:element name="rights" type="vr:Rights" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="format" type="vs:Format" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="coverage" type="vs:Coverage" minOccurs="0"/>
           <xs:element name="tableset" type="vs:TableSet" minOccurs="0">
             <xs:unique name="DataCollection-schemaName">
                <xs:selector xpath="schema" />
                <xs:field xpath="name" />
             </xs:unique>
             <xs:unique name="DataCollection-tableName">
                <xs:selector xpath="schema/table" />
                <xs:field xpath="name" />
             </xs:unique>
           <xs:element>
           <xs:element name="accessURL" type="vr:AccessURL" minOccurs="0"/>

         </xs:sequence>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

vs:[BlahBlah] Extension Metadata Elements
ElementDefinition
facility
Value type: string with optional ID attribute: vr:ResourceName
Semantic Meaning: the observatory or facility used to collect the data contained or managed by this resource.
Occurrences: optional; multiple occurrences allowed
Comments: MIME types should be used for network-retrievable, digital data. Non-MIME type values are used for media that cannot be retrieved over the network--e.g. CDROM, poster, slides, video cassette, etc.

vs:[BlahBlah] Attributes
AttributeDefinition
type
Value type: string: xs:token
Semantic Meaning: a name indicating the role this table plays.
Occurrences: optional
Recommeded Values:
output this table structure is used to format the output from a query
base_table this table contains records that represent the main subjects of the parent schema; other tables contain ancillary data.
view the table represents a useful combination or subset of other tables.
Other values are allowed.

Describing Standards

Describe Standard and ServiceStandard types here

Details of the VOStandard Schema

In accordance with the guidelines laid down by [VR], there has been no attempt to create enumerated lists for cases where there list could not be closed (e.g. the set of operating system names will grow as new operating systems are developed). This means that the values of certain elements in a document instance will not be checked by even a validating XML parser, and validation that the element contents are allowed will have to be done by a separate process. This section will list the allowed values for those enumerations where appropriate and instance documents MUST use these exact strings to represent the same concept.

Use of the VOStandard Schema

It should be noted that in many cases there is no need to introduce a dependency on this schema in other registry schemas e.g. the VOResouce schema does not include the VOStandard schema - it simply defines a type vr:ResourceIdentifier that limits a string to have the correct resource identifider syntax. XML entities registered using the VOResouce schema SHOULD refer to entities registered with the VOStandard schema when creating a standardID attribute, although there is no compulsion in the XML schema language to do so. The major IVOA standards will already have an appripriate standard describing resource registered, however it should always be possible for an 'experimental' standard to be registered.

Details of the elements for defining Standards

TBC

Appendix A: The complete VOStandard Schema

Note that this schema can be found on-line at http://www.ivoa.net/xml/VOStandard/v0.2 (i.e. the target namespace can also be used as a URL for the schema not yet uploaded for this draft) This location should represent the definitive source, the schema is only copied below for completeness of this document.

Appendix B: Standards instance

This is an example of the ivoa standards that can be defined with the VOStandard Schema. This example should not be taken as the definitive definition for any standards mentioned - an IVOA registry should always be consulted, where the standards will be registered under the authority identifier net.ivoa.standards

Appendix C: Change History

This is the first version that has been made public - it is derived from wiki content.

References

[RFC 2119]
Bradner, S. 1997. Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, http://www.ietf.org/rfc/rfc2119.txt
[RM]
Hanisch, Robert (ed.) 2004. Resource Metadata for the Virtual Observatory, Version 1.01, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm
[VR]
Plante, Ray (ed.) 2006. VOResource: an XML Encoding Schema for Resource Metadata, IVOA Working Draft, http://www.ivoa.net/Documents/latest/VOResource.html
[CEA]
Harrison, Paul. 2006. VOCEA: Schema , IVOA Working Draft, http://www.ivoa.net/Documents/latest/VOCEA.html
 
[xml]
Bray, Tim, Paoli, Jean, Sperberg-McQueen, C. M., Maler, Eve, Yergeau, Francois (editors) 2004, Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation 04 February 2004, http://www.w3.org/TR/REC-xml
[schema]
Fallside, David C., Walmsley, Priscilla (editors) 2004, XML Schema Part 0: Primer Second Edition, W3C Recommendation 28 October 2004, http://www.w3.org/TR/xmlschema-0/
[ISO8601]
Wolf, Misha and Wicksteed, Charles 1997, Date and Time Format, http://www.w3.org/TR/NOTE-datetime.
[ID]
Plante, R., Linde, T., Williams, R., Noddle, K. 2005, IVOA Identifiers v1.1, http://www.ivoa.net/Documents/REC/Identifiers/Identifiers-200505XX.html.
 

Last modified: Tue May 12 00:59:15 2009