StandardsRegExt: a VOResource Schema Extension for Describing IVOA Standards#
Official bibliographic entry for published version [StandardsRegExt1.0].
- Status:
StandardsRegExt 1.1 REC 2025-10-20
Acknowledgements#
The first versions of this document have been developed with support from the National Science Foundation’s [1] 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 Seventh Framework Program [2].
This document contains text lifted verbatim, with small changes, and with substantial changes from (old versions of) the VODataService specification VODataService. 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.
1 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 where resources can be described and thus discovered by users and applications in the VO. The standard Resource Metadata for the Virtual Observatory [RM1.1] (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 [VOResource1.1]. 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 element. The specific standard protocol supported is uniquely identified via an attribute of the element called whose value is a URI. VOResource does not place a formal validation requirement on the other than it be a legal URI; however, it was intended that IVOA-endorsed standards would be represented via an IVOA identifier. As per the IVOA Identifier standard [IVOAIdentifiers2.0], an IVOA identifier must be registered as a resource in an IVOA-compliant registry.
This document defines a VOResource extension schema called StandardsRegExt which allows standards writers 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 compliant 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 it allows registry users who discover services that conform to a particular standard to also discover the document that describes that standard.
StandardsRegExt 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 standard keys or 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 onto the IVOA identifier associated with the descriptions.
StandardsRegExt records that describe standards endorsed or otherwise in development by the IVOA are published in the IVOA Registry of Registries [RegistryOfRegistries1.0] using the authority identifier ivoa.net as discussed in Sect. 4 Operational Aspects. However, other standards, be they ad hoc or endorsed by another body, may be published in any compliant registry.
1.1 Role within the VO Architecture#
Fig. StandardsRegExt:fig:archdiag shows the role this document plays within the IVOA architecture [IVOAArchitecture2.0]. The Registry enables applications in the User Layer to discover archives and services in the Resource Layer. The registry metadata model standards (in blue text and boxes) give structure to the information that enables that discovery. StandardsRegExt defines metadata for describing standards themselves (like those that define the Data Access Protocols).
In this architecture, users can leverage a variety of tools (from the User Layer) to discover archives and services of interest (represented in the Resource Layer); registries provide the means for this discovery. A registry is a repository of descriptions of resources that can be searched based on the metadata in those descriptions. In general, a resource can be more than just archives, data, or services; an IVOA standard, as represented by an IVOA document, can also be a resource. The Resource Metadata standard defines the core concepts used in the resource descriptions, and VOResource defines the XML format. StandardsRegExt is an extension of the VOResource standard that defines extra metadata for describing a standard.
1.2 Syntax Notation Using XML Schema#
The eXtensible Markup Language, or XML, is a document syntax for marking textual information with named tags and is defined by the World Wide Web Consortium (W3C) Recommendation, XML 1.0 [std:XML]. The set of XML tag names and the syntax rules for their use is referred to as the document schema. One way to formally define a schema for XML documents is using the W3C standard known as XML Schema [std:XSD].
This document defines the StandardsRegExt schema using XML Schema. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity. The full schema is available from the IVOA schema repository [3]. For documentation and development purposes, this document is accompanied by a copy of that schema [4]. In case of conflicts, the copy at the schema repository is normative.
Reference to specific elements and types defined in the VOResource schema include the namespaces prefix, vr, as in (a type defined in the VOResource schema). Reference to specific elements and types defined in the StandardsRegExt schema include the namespaces prefix, vstd, as in (a type defined in the StandardsRegExt schema). Use of the vstd prefix in compliant instance documents is strongly recommended. It is required where the Registry Interfaces standard [RegistryInterface1.1] applies.
2 The StandardsRegExt Data Model#
The StandardsRegExt extension in general enables the description of two types of resources:
a generic standard (specified by an external document)
a standard specifically defining a service protocol
Each type of resource can have a set of related, standardized names called keys.
Here’s an example of defining the HiPS standard and its associated keys.
<ri:Resource xsi:type="vstd:Standard"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:vstd="http://www.ivoa.net/xml/StandardsRegExt/v1.0"
xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0"
created="2017-06-01T09:33:00Z"
updated="2017-06-01T09:33:00Z"
status="active">
<title>HiPS -- Hierarchical Progressive Survey</title>
<identifier>ivo://ivoa.net/std/hips</identifier>
<curation>
<publisher>IVOA Apps Working Group</publisher>
<creator>
<name>Fernique, P.</name>
</creator>
...
<date role="created">2017-06-01T09:33:00</date>
<contact>
<name>IVOA Apps Working Group</name>
<email>apps@ivoa.net</email>
</contact>
</curation>
<content>
<subject>Virtual observatory</subject>
<subject>Standards</subject>
<subject>HiPS</subject>
<description>
HiPS: a hierarchical scheme for the description, storage and access of
sky survey data. The system is based on hierarchical tiling of sky regions
at finer and finer spatial resolution which facilitates a progressive
view of a survey, and supports multi-resolution zooming and panning.
HiPS uses the HEALPix tessellation of the sky as the basis for the scheme
and is implemented as a simple file structure with a direct indexing
scheme that leads to practical implementations.
</description>
<referenceURL>http://ivoa.net/documents/HiPS</referenceURL>
</content>
<endorsedVersion status="rec" use="preferred">1.0</endorsedVersion>
<key>
<name>hipslist-1.0</name>
<description>
A service returning a list of HiPS identifiers
and metadata for HiPS. This term is used to form a standardID,
for instance for use in vr:Capability.
</description>
</key>
<key>
<name>hips-1.0</name>
<description>
A single HiPS. This term is used to form a standardID,
for instance for use in vr:Capability.
</description>
</key>
</ri:Resource>
2.1 The Schema Namespace and Location#
The namespace associated with StandardsRegExt extensions is
Just like the namespace URI for the VOResource schema, the StandardsRegExt namespace URI can be interpreted as a URL. Resolving it will return the XML Schema document that defines the StandardsRegExt schema. This namespace is constant for all versions of StandardsRegExt version one, in particular the current version 1.1. See Harrison et al. [XMLVers1.0] (section 2.2.3) for the background of this slightly confusing convention.
Authors of VOResource instance documents may choose to provide a location for the VOResource XML Schema document and its extensions using the attribute. While the location value is the choice of the author, this specification recommends using the StandardsRegExt namespace URI as its location URL (as illustrated in the example above), as in,
xsi:schemaLocation="http://www.ivoa.net/xml/StandardsRegExt/v1.0
http://www.ivoa.net/xml/StandardsRegExt/v1.0"
The prefix, vstd, is used by convention as the prefix defined for the StandardsRegExt 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), 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 .
As recommend by the VOResource standard, the StandardsRegExt 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 StandardsRegExt type name given as the value of an attribute.
2.2 Summary of Metadata Concepts#
The StandardsRegExt extension defines two new types of resources which are specifically for independently documented standards:
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 (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.
This resource type, which extends from
vstd:Standard, is specifically for describing a standard service protocol (e.g. Simple Cone Search). It differs from in that it also allows one to describe specific constraints on the service interface via its element.
2.3 Defining Enumerations of Identifiers#
A common practice when defining metadata is to restrict certain string values to a controlled set of defined names, each with a well-defined meaning. With XML Schema, the controlled set can be enforced by a validating parser (using the construct). One disadvantage of locking in the vocabulary in an XML Schema document is that in order to grow the list of allowed names, a revision of the XML Schema document is required, which can be a disruptive change. To avoid this, it is the practice within 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 StandardsRegExt schema provides an alternative to XML Schema-based definitions of controlled names. Instead, a controlled list of names, called standard keys, can be defined as part of any of the two StandardsRegExt resource types. Updating a resource description is much less disruptive than a Schema document, and as a resource is available via an IVOA-compliant registry, it is still possible for a (non-Schema-based) application to validate the use of the vocabulary.
The StandardsRegExt 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 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:
where ivoa-identifier is the resource’s IVOA identifier and key-name is the name of a key defined in that resource. Consistent with the URI standard, the key-name must not contain a pound (#) sign.
For example, we consider a resource description with an IVOA identifier given by ivo://ivoa.net/std/QueryProtocol that defines a key named case-insensitive; the URI identifying this key would be:
Note that registry references in the sense of IVOA Identifiers 2 (i.e., the part in front of the the pound sign, #) must be compared case-insensitively. To facilitate comparisons of full IVOIDs, since version 1.1 this specifiation requires that standard key names do not contain uppercase letters. In this way, clients can safely lowercase the full standard key references before comparing them.
This is also true for all IVOA-approved standard keys before version 1.1 except for the keys for authentication methods from SSO. Clients implementing other IVOA standards can hence safely compare IVOIDs for standard keys by checking for identity after lowercasing.
This form of defining multiple keys, each with its own mapping to a URI, all in one resource has several advantages:
The enumerations are naturally grouped under a single registry resource, and so can be retrieved with one registry query and need no further metadata to assert the association.
The “Dublin core” metadata that is associated with a resource need only be entered once for the whole enumeration, rather than for each member of the enumeration – this saves both curation effort and space in the registry.
If it is necessary to expand the list of controlled names (or shrink it), it is simple and fairly undisruptive to update the VOResource record.
Some applications may wish to publish additional metadata associated with a key definition through further extension of VOResource metadata. This could be done by extending type.
3 The StandardsRegExt Metadata#
3.1 Resource Type Extensions#
This specification defined two new resource types. As is spelled out in the VOResource specification, a resource description indicates that it refers to one of these types of resources by setting the attribute to the namespace-qualified type name. Doing so implies that the semantic meaning of that type applies to the resource.
3.1.1 Standard#
The resource type describes any general standard specification. This typically refers to an IVOA standard but is not limited to such. Generally, the type is intended for standards other than standard protocols (which should use the type instead). It extends the generic type as follows.
As one of the purposes of this resource type is to enable users to discover the documentation that defines the standard that the resource describes, the should point either to the standard’s specification document or to summary information about the standard that can lead one to the specification document.
The child elements define terms with special meaning to the standard; see Sect. 3.2 Defining Keys: StandardKey and StandardKeyURI.
The purpose of the required element is to point potential users of the standard to the version that is most preferred by the standard’s publisher. If multiple versions are relevant or in use, multiple elements may be given; in this case, the attribute can further help steer the users to the preferred version.
When all versions of the standard are considered deprecated by the resource publisher, the child element should appear. The explanation given as a value should mention the standard that the current standard is deprecated by when relevant.
The element allows one to list the locations of any schemas defined by the standard thereby making them discoverable as well (just as the specification document is discoverable via the element). It also can provide pointers to example uses of the schemas. Typically (especially for IVOA standards), the schema is an XML schema, and the location points to an XML Schema document; however, this is not required. Other schema types and definition formats are allowed.
As multiple schemas can be listed in the resource description, the ``namespace`` attribute provides an identifying label for each ``<schema>`` element.
The main component of the content is the URL pointing to the schema’s definition document, but it can also provide additional information useful for display.
3.1.2 ServiceStandard#
The resource type extends to describe more specifically a standard protocol. It adds an element to allow the interface defined by the standard to be described in a machine-readable way. Its type is defined to be , which is defined in the VOResource schema.
Even though the vr:Interface type requires an <accessURL> child element, the <interface> element in a vstd:ServiceStandard is intended to describe a service in the abstract–i.e. without reference to a particular installation of the service. Consequently, the accessURL should contain a bogus URL; applications should not expect it to be resolvable.
An application can, in principle, get a complete machine-readable description of a particular instance of a standard service (to, say, create a GUI for that service on-the-fly) by combining the general description in the vstd:ServiceStandard record with the service resource description for the specific instance. The intended process for building that description is as follows:
The application obtains a VOResource resource record for the service instance (e.g. from a registry).
The application extracts the attribute for the desired service capability.
The is resolved (via a registry) to a record for the service. This description would capture the required and optional (but standard) components of the service interface.
The specific instance’s interface description is merged into the standard one. The service’s support of optional components as well as its allowed customizations would override the generic description from the record.
The so-called “simple” data access layer (DAL) services, such as the Simple Image Access services SIA, are registered using the interface type VODataService to describe their interfaces. This interface type allows one to list input parameters accepted by the service. Each parameter can be marked as required, optional, or ignored. In several DAL standards, there are optional parameters that implementations may choose to ignore. When a record contains an interface of type , such ignoreable parameters should have their attribute set to ignored.
Applications that consume such records should thus interpret the parameters marked ignored as optional for use by clients and ignorable by implementations. This minimizes the list of parameters that the service provider must list in the registration of a particular service instance to the ones that are actually supported (i.e., not ignored). When the list of parameters from the service instance description is merged into the list of parameters from the record (step 4 above), the result is an accurate list of the optional but supported versus optional but ignored parameters for that service instance.
An example of an instance of a record is shown in Appendix A A Sample Record. It describes the Simple Image Access Specification and in particular illustrates the recommended way to list input parameters defined by the standard.
3.2 Defining Keys: StandardKey and StandardKeyURI#
The type provides the means to define keys (as described in Sect. 2.3 Defining Enumerations of Identifiers) within a VOResource record.
Defining a key via a element within a VOResource record implies the definition of a unique URI formed according to the syntax described in Sect. 2.3 Defining Enumerations of Identifiers that represents the semantics given by the value of the child element. Because the URI must be globally unique, the key name (given by the child element) must be unique within the VOResource record.
Though it is not needed by StandardsRegExt resource records, the StandardsRegExt schema further defines a convenience type, , which defines the legal pattern for a full standard key identifier (as defined in Sect. 2.3 Defining Enumerations of Identifiers). Applications that wish to use XML Schema to validate the form of a key URI may import the StandardsRegExt schema and use this type.
4 Operational Aspects#
4.1 Management of Standards Records#
Only IVOA standards that actually make use of identifiers to or into StandardsRegExt records MUST be accompanied with active records published by the ivoa.net registry. This, in particular, concerns all standards defining capabilities to be discerned using their attribute. Other standards MAY be registered in this way once they have entered the IVOA document repository.
There are no regulations on StandardsRegExt records published under authorities other than ivoa.net; these can be published (and withdrawn) at any time.
Editors of standards requiring an ivoa.net StandardsRegExt record SHOULD upload one when they submit the first Working Draft in order to make IVOIDs valid even in prototyping phases. They MUST upload it at the beginning of the standard’s RFC phase to ensure validators can work properly, and they MUST update the record when the standard reaches REC status.
Submission to the ivoa.net registry generally happens through e-mail. See http://rofr.ivoa.net/ for contact information.
The ivoatex package [ivoatexDoc] offers templates for StandardsRegExt records and recommends keeping these in the respective standards’ source code repositories.
4.2 Management of Standard Keys#
Standards using standard keys must specify rules defining when and how standard keys are being added. In the simplest case, this would be “Keys in this standard’s StandardsRegExt record are defined in this text.” This will make sure that additions of keys receive the same review as the standard text itself.
However, other, more flexible regulations are conceivable, as for instance “Keys in this standard’s StandardsRegExt record can be added by the chair of the managing Working Group after consultation on the WG’s mailing list”. However, complicated processes should be avoided here; if regular key additions requiring consensus building are expected, the standard should probably rather define a proper IVOA vocabulary [Vocabularies2.0]; this also has the advantage over StandardsRegExt keys that non-VO RDF tools can evaluate the resources produced, which is not the case for StandardsRegExt records.
Appendices#
A A Sample Record#
This example shows how one can describe an IVOA standard, the Simple Image Access Protocol. It includes a description of the input parameters defined in the specification. Note that this no longer corresponds to the actual SimpleDALRegExt record for the Simple Image Access Protocol as distributed by the Registry of Registries.
<resource xsi:type="vstd:ServiceStandard" status="active"
created="2000-01-01T09:00:00" updated="2000-01-01T09:00:00"
xmlns:vstd="http://www.ivoa.net/xml/StandardsRegExt/v1.0"
xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
http://www.ivoa.net/xml/VODataService/v1.1
http://www.ivoa.net/xml/StandardsRegExt/v1.0
http://www.ivoa.net/xml/StandardsRegExt/v1.0">
<title> Simple Image Access Protocol </title>
<shortName> SIA </shortName>
<identifier> ivo://ivoa.net/std/SIA </identifier>
<curation>
<publisher ivo-id="ivo://ivoa.net/IVOA">
International Virtual Observatory Alliance
</publisher>
<creator>
<name> Doug Tody </name>
</creator>
<creator>
<name> Ray Plante </name>
</creator>
<date> 2004-05-24 </date>
<contact>
<name> Data Access Layer Working Group </name>
<email> dal@ivoa.net </email>
</contact>
</curation>
<content>
<subject> software standard </subject>
<subject> virtual observatory </subject>
<description>
The Simple Image Access Protocol is a protocol for retrieving
image data from a variety of astronomical image repositories
through a uniform interface. The interface is meant to be
reasonably simple to implement by service providers. A query
defining a rectangular region on the sky is used to query for
candidate images. The service returns a list of candidate
images formatted as a VOTable. For each candidate image an
access reference URL may be used to retrieve the image. Images
may be returned in a variety of formats including FITS and
various graphics formats. Referenced images are often computed
on the fly, e.g., as cutouts from larger images.
</description>
<referenceURL>
http://www.ivoa.net/Documents/latest/SIA.html
</referenceURL>
<type> Other </type>
<contentLevel> Research </contentLevel>
</content>
<endorsedVersion status="rec"> 1.0 </endorsedVersion>
<interface xsi:type="vs:ParamHTTP" role="std" version="1.0">
<accessURL use="base"> http://sample.org/cgi-bin/sia </accessURL>
<queryType>GET</queryType>
<resultType>text/xml+votable</resultType>
<!--
- These are the standard input parameters defined in the
- SIA spec
-->
<param use="required">
<name>POS</name>
<description>
Search Position in the form "ra,dec" where ra and dec are given
in decimal degrees in the ICRS coordinate system.
</description>
<unit>degrees</unit>
<dataType arraysize="2">real</dataType>
</param>
<param use="required">
<name>SIZE</name>
<description>
Size of search region in the RA and Dec. directions in decimal
degrees.
</description>
<unit>degrees</unit>
<dataType arraysize="2">real</dataType>
</param>
<param use="optional">
<name>FORMAT</name>
<description>Requested format of images.</description>
<dataType>string</dataType>
</param>
<param use="optional">
<name>INTERSECT</name>
<description>
Choice of intersection of matched images with the region of
interest.
</description>
<dataType>string</dataType>
</param>
<param use="ignored">
<name>NAXIS</name>
<description>
The number of pixels desired along each axis
</description>
<dataType arraysize="2">integer</dataType>
</param>
<param use="ignored">
<name>CFRAME</name>
<description>
the coordinate frame to impose on the image.
</description>
<dataType>string</dataType>
</param>
<param use="ignored">
<name>EQUINOX</name>
<description>
the epoch of the mean equator and equinox for the specified
coordinate system reference frame (CFRAME). coordinate frame to
impose on the image.
</description>
<dataType>string</dataType>
</param>
<param use="ignored">
<name>CRPIX</name>
<description>
the pixel position to locate the reference position in the output
image.
</description>
<dataType arraysize="2">real</dataType>
</param>
<param use="ignored">
<name>CRVAL</name>
<description>
the world coordinates of the reference position in the output
image in decimal degrees
</description>
<dataType arraysize="2">real</dataType>
</param>
<param use="ignored">
<name>CDELT</name>
<description>
the scale of the output image in decimal degrees per pixel
</description>
<dataType arraysize="2">real</dataType>
</param>
<param use="ignored">
<name>ROTANG</name>
<description>
the rotation angle to put into the coordinate system of the output
image
</description>
<dataType arraysize="2">real</dataType>
</param>
<param use="ignored">
<name>PROJ</name>
<description>
the projection to impose in the construction of the output image
</description>
<dataType>string</dataType>
</param>
<param use="ignored">
<name>VERB</name>
<description>
the level of verbosity in the output.
</description>
<dataType>string</dataType>
</param>
</interface>
</resource>
B Changes from Previous Versions#
B.1 Changes since Rec-1.0#
Corrected typos identified in RFC remarks
Corrected and clarified some wordings.
Removed references to (which is now deprecated) from this document and associated schema. Replaced computer language example by HiPS standard definition example.
Added en and pen to the list of document types.
Adding regulations on record upload and key additions.
Requiring new keys to be all-lowercase in order to simplify comparisons.
Ported to ivoatex. This entailed some re-shuffling the previous content.
Dropped the “example of a Standard resource that summarizes this specification” (we have an example in the appendix already, and it’s not clear why there would be another one inline).
Dropped the in-document full schema (we now have auxiliaryurl, and it’s unclear whether it’s a good idea to have a second copy of the schema anyway).
B.2 Changes since PR-v1.0 20120217:#
none other than date and status.
B.3 Changes since PR-v1.0 20120213:#
added the element to
updated example for
B.4 Changes since PR-v1.0 20111017:#
added Note box that recommends against using to describe keys when they are defined by an IVOA standard.
added statement highlighting that
#signs are not allowed in key names.added
iwdandnoteas allowed values for ’s attribute.converted a Note box in to a normative paragraph that recommends listing optional parameters as ignored. Note that there is a related error in the VODataService standard: while the
ignoredvalue is defined in the schema, it is not included in the document text.added sample instance record back in as Appendix B
fixed various grammatical typos.
B.5 Changes since PR-v1.0 20110921:#
In , changed “prop” to “pr”.
various typo corrections
B.6 Changes since PR-v1.0 20110316:#
Corrected ampersand representation in schema listing
Various typo corrections and clarifications
B.7 Changes since WD-v1.0 20100519:#
Prepped for PR
improved discussion of example in section on the data model
Added standard architecture sub-section
updated in-lined schema (App. 1)
B.8 Changes since WD-v1.0 20100514:#
short name changed from VOStandard to StandardsRegExt
B.9 Changes since WD-v0.4:#
removed App. B. (Sample instance) as examples appear throughout the document.