==================== StandardsRegExt: a :doc:`VOResource <../VOResource/VOResource>` Schema Extension for Describing IVOA Standards ==================== Official bibliographic entry for published version :cite:p:`2012ivoa.spec.0508H`. :Status: StandardsRegExt 1.1 REC 2025-10-20 .. role:: raw-latex(raw) :format: latex .. .. _`StandardsRegExt:acknowledgements`: 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 :doc:`VODataService <../VODataService/VODataService>` specification :doc:`VODataService <../VODataService/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. .. _`StandardsRegExt:sect:intro`: 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 :cite:p:`2007ivoa.spec.0302H` (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 :doc:`VOResource <../VOResource/VOResource>` :cite:p:`2018ivoa.spec.0625P`. 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 :raw-latex:`\xmlel{capability}` element. The specific standard protocol supported is uniquely identified via an attribute of the :raw-latex:`\xmlel{capability}` element called :raw-latex:`\xmlel{standardID}` whose value is a URI. :doc:`VOResource <../VOResource/VOResource>` does not place a formal validation requirement on the :raw-latex:`\xmlel{standardID}` 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 :cite:p:`2016ivoa.spec.0523D`, an IVOA identifier must be registered as a resource in an IVOA-compliant registry. This document defines a :doc:`VOResource <../VOResource/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 :doc:`VOResource <../VOResource/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 :cite:p:`2007ivoa.rept.0628P` using the authority identifier ``ivoa.net`` as discussed in Sect. :ref:`StandardsRegExt:sect:operations`. However, other standards, be they ad hoc or endorsed by another body, may be published in any compliant registry. .. _`StandardsRegExt:role-within-the-vo-architecture`: 1.1 Role within the VO Architecture ----------------------------------- .. container:: float :name: StandardsRegExt:fig:archdiag .. raw:: latex \centering `role_diagram.pdf `__ Fig. :ref:`StandardsRegExt:fig:archdiag` shows the role this document plays within the IVOA architecture :cite:p:`2021ivoa.spec.1101D`. 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 :doc:`VOResource <../VOResource/VOResource>` defines the XML format. StandardsRegExt is an extension of the :doc:`VOResource <../VOResource/VOResource>` standard that defines extra metadata for describing a standard. .. _`StandardsRegExt:syntax-notation-using-xml-schema`: 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 :cite:p:`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 :cite:p:`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 :doc:`VOResource <../VOResource/VOResource>` schema include the namespaces prefix, ``vr``, as in :raw-latex:`\xmlel{vr:Resource}` (a type defined in the :doc:`VOResource <../VOResource/VOResource>` schema). Reference to specific elements and types defined in the StandardsRegExt schema include the namespaces prefix, ``vstd``, as in :raw-latex:`\xmlel{vstd:ServiceStandard}` (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 :cite:p:`2018ivoa.spec.0723D` applies. .. _`StandardsRegExt:the-standardsregext-data-model`: 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 :doc:`HiPS <../HiPS/HiPS>` standard and its associated *keys*. .. code:: xml HiPS -- Hierarchical Progressive Survey ivo://ivoa.net/std/hips IVOA Apps Working Group Fernique, P. ... 2017-06-01T09:33:00 IVOA Apps Working Group apps@ivoa.net Virtual observatory Standards HiPS 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. http://ivoa.net/documents/HiPS 1.0 hipslist-1.0 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. hips-1.0 A single HiPS. This term is used to form a standardID, for instance for use in vr:Capability. .. _`StandardsRegExt:the-schema-namespace-and-location`: 2.1 The Schema Namespace and Location ------------------------------------- The namespace associated with StandardsRegExt extensions is .. math:: \hbox{\nolinkurl{http://www.ivoa.net/xml/StandardsRegExt/v1.0}.} Just like the namespace URI for the :doc:`VOResource <../VOResource/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 :cite:t:`2018ivoa.spec.0529H` (section 2.2.3) for the background of this slightly confusing convention. Authors of :doc:`VOResource <../VOResource/VOResource>` instance documents may choose to provide a location for the :doc:`VOResource <../VOResource/VOResource>` XML Schema document and its extensions using the :raw-latex:`\xmlel{xsi:schemaLocation}` 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 :doc:`VOResource <../VOResource/VOResource>` schema, as in :raw-latex:`\xmlel{vr:Resource}`. As recommend by the :doc:`VOResource <../VOResource/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 :raw-latex:`\xmlel{xsi:type}` attribute. .. _`StandardsRegExt:summary-of-metadata-concepts`: 2.2 Summary of Metadata Concepts -------------------------------- The StandardsRegExt extension defines two new types of resources which are specifically for independently documented standards: :raw-latex:`\xmlel{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 :raw-latex:`\xmlel{referenceURL}` (from the core :doc:`VOResource <../VOResource/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. :raw-latex:`\xmlel{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 :raw-latex:`\xmlel{vstd:Standard}` in that it also allows one to describe specific constraints on the service interface via its :raw-latex:`\xmlel{interface}` element. .. raw:: latex \begin{admonition}{Note} In general, \xmlel{vstd:StandardKey}-s used by a standard should be defined in that standard's registry record. That is, the practice currently employed by ADQL \citep{2023ivoa.spec.1215M} that defines standard keys in TAPRegExt's StandardsRegExt record is to be considered a historical artefact. The deprecated \xmlel{vstd:StandardKeyEnumeration} was originally envisioned as a container for names that are not closely related to a single standard and hence perhaps not suitable for that standard's record. With the adoption of Vocabularies in the VO 2 \citep{2021ivoa.spec.0525D}, this type has become obsolete. \end{admonition} .. _`StandardsRegExt:sect:keys`: 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 :raw-latex:`\xmlel{xsd:enumeration}` 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 :doc:`VOResource <../VOResource/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 :raw-latex:`\xmlel{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: .. math:: \hbox{\emph{ivoa-identifier}\verb|#|\emph{key-name}}, 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: .. math:: \hbox{\nolinkurl{ivo://ivoa.net/std/QueryProtocol#case-insensitive}}. 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 :doc:`SSO <../SSO/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 :doc:`VOResource <../VOResource/VOResource>` record. .. raw:: latex \begin{admonition}{Note} When these enumerations are presented to a user in a GUI it is expected that 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''. \end{admonition} Some applications may wish to publish additional metadata associated with a key definition through further extension of :doc:`VOResource <../VOResource/VOResource>` metadata. This could be done by extending :raw-latex:`\xmlel{vstd:StandardKey}` type. .. _`StandardsRegExt:the-standardsregext-metadata`: 3 The StandardsRegExt Metadata ============================== .. _`StandardsRegExt:resource-type-extensions`: 3.1 Resource Type Extensions ---------------------------- This specification defined two new resource types. As is spelled out in the :doc:`VOResource <../VOResource/VOResource>` specification, a resource description indicates that it refers to one of these types of resources by setting the :raw-latex:`\xmlel{xsi:type}` attribute to the namespace-qualified type name. Doing so implies that the semantic meaning of that type applies to the resource. .. _`StandardsRegExt:standard`: 3.1.1 Standard ~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vstd:Standard}` resource type describes any general standard specification. This typically refers to an IVOA standard but is not limited to such. Generally, the :raw-latex:`\xmlel{vstd:Standard}` type is intended for standards *other than* standard protocols (which should use the :raw-latex:`\xmlel{vstd:ServiceStandard}` type instead). It extends the generic :raw-latex:`\xmlel{vr:Resource}` type as follows. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vstd:Standard} Type Schema Documentation} \noindent{\small{}a description of a standard specification.\par} \noindent{\small{}This typically refers to an IVOA standard but is not limited to such.\par} \vspace{1ex}\noindent\textbf{\xmlel{vstd:Standard} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:Standard} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{endorsedVersion}] \begin{description} \item[Type] a string with optional attributes \item[Meaning] the version of the standard that is recommended for use. \item[Occurrence] required; multiple occurrences allowed. \item[Comment] More than one version can be listed, indicating that any of these versions are recognized as acceptable for use. \end{description} \item[Element \xmlel{schema}] \begin{description} \item[Type] composite: \xmlel{vstd:Schema} \item[Meaning] a description and pointer to a schema document defined by this standard. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This is most typically an XML Schema, but it need not be strictly. \end{description} \item[Element \xmlel{deprecated}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] when present, this element indicates that all versions of the standard are considered deprecated by the publisher. The value is a human-readable explanation for the designation. \item[Occurrence] optional \item[Comment] The explanation should indicate if another standard should be preferred. \end{description} \item[Element \xmlel{key}] \begin{description} \item[Type] composite: \xmlel{vstd:StandardKey} \item[Meaning] a defined key associated with this standard. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} 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 :raw-latex:`\xmlel{referenceURL}` 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 :raw-latex:`\xmlel{key}` elements define terms with special meaning to the standard; see Sect. :ref:`StandardsRegExt:sect:standardkeys`. The purpose of the required :raw-latex:`\xmlel{endorsedVersion}` 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 :raw-latex:`\xmlel{use}` attribute can further help steer the users to the preferred version. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vstd:EndorsedVersion} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:EndorsedVersion} Attributes} \begingroup\small\begin{bigdescription} \item[status] \begin{description} \item[Type] string with controlled vocabulary \item[Meaning] the IVOA status level of this version of the standard. \item[Occurrence] optional \item[Allowed Values\vrule width 0pt depth 5pt]\hfil \begin{longtermsdescription}\item[rec]an IVOA Recommendation \item[pr]an IVOA Proposed Recommendation \item[wd]an IVOA Working Draft \item[iwd]an internal Working Draft of an IVOA Working Group \item[note]a published IVOA Note \item[pen]a Proposed Endorsed Note \item[en]an Endorsed Note \item[n/a]not an IVOA standard or protostandard at this time. \end{longtermsdescription} \item[Default] n/a \item[Comment] For values of “rec”, “pr”, “wd”, “note”, “pen”, and “en” the record's referenceURL element should point to the official specification document in the IVOA Document Repository; if the document does not appear there, these values should not be used. \end{description} \item[use] \begin{description} \item[Type] string with controlled vocabulary \item[Meaning] A designation of preference for the version compared to other versions in use. \item[Occurrence] optional \item[Allowed Values\vrule width 0pt depth 5pt]\hfil \begin{longtermsdescription}\item[preferred]the most preferred version. \item[deprecated]a version whose use is now discouraged because a newer version is preferred. \end{longtermsdescription} \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} When all versions of the standard are considered deprecated by the resource publisher, the :raw-latex:`\xmlel{deprecated}` child element should appear. The explanation given as a value should mention the standard that the current standard is deprecated by when relevant. .. raw:: latex \begin{admonition}{Note} An example where the \xmlel{deprecated} element might be used in the VO is in the case of the SkyNode standard. When StandardsRegExt was originally written, there were many instances of SkyNode services available in the VO, and where they were used, version 1.01 was endorsed; however, the IVOA has deprecated this standard in favor of the Table Access Protocol. Thus, a \xmlel{vstd:ServiceStandards} record for SkyNode should include a \xmlel{deprecated} element whose content refers viewers to the TAP standard. \end{admonition} The :raw-latex:`\xmlel{}` 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 :raw-latex:`\xmlel{referenceURL}` 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. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vstd:Schema} Type Schema Documentation} \noindent{\small{}a description of a schema definition\par} \vspace{1ex}\noindent\textbf{\xmlel{vstd:Schema} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:Schema} Attributes} \begingroup\small\begin{bigdescription} \item[namespace] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] an identifier for the schema being described. Each instance of this attribute must be unique within the resourse description. \item[Occurrence] required \item[Comment] For XML schemas, this should be the schema's namespace URI. Otherwise, it should be a unique label to distinguish it from other schemas described in the same resource description. \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:Schema} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{location}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A URL pointing to a document that formally defines the schema. \item[Occurrence] required \item[Comment] The document should be in a machine-parsable format when applicable. For example, when refering to an XML schema, the document should be an XML Schema or similar document that can be used to validate an instance document. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A human-readable description of what the schema defines or is used for. \item[Occurrence] optional \item[Comment] A brief description--e.g. one statement--is recommended for display purposes. \end{description} \item[Element \xmlel{example}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A URL pointing to a sample document that illustrates the use of the schema. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] When applicable (e.g. XML), the document should be in the format defined by the schema document. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} As multiple schemas can be listed in the resource description, the **``namespace``** attribute provides an identifying label for each **````** element. The main component of the :raw-latex:`\xmlel{schema}` content is the URL pointing to the schema’s definition document, but it can also provide additional information useful for display. .. _`StandardsRegExt:servicestandard`: 3.1.2 ServiceStandard ~~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vstd:ServiceStandard}` resource type extends :raw-latex:`\xmlel{vstd:Standard}` to describe more specifically a standard protocol. It adds an :raw-latex:`\xmlel{interface}` element to allow the interface defined by the standard to be described in a machine-readable way. Its type is defined to be :raw-latex:`\xmlel{vr:Interface}`, which is defined in the :doc:`VOResource <../VOResource/VOResource>` schema. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vstd:ServiceStandard} Type Schema Documentation} \noindent{\small{}a description of a standard service protocol.\par} \noindent{\small{}This typically refers to an IVOA standard but is not limited to such.\par} \vspace{1ex}\noindent\textbf{\xmlel{vstd:ServiceStandard} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:ServiceStandard} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{interface}] \begin{description} \item[Type] composite: \xmlel{vr:Interface} \item[Meaning] an abstract description of one of the interfaces defined by this service standard. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This element can provide details about the interface that apply to all implementations. Each interface element should specify a role with a value starting with {"}std:{"} or, if there is only one standard interface, is equal to {"}std{"}. \item[Comment] Applications that, for example, wish to build a GUI to the service on-the-fly would first access this generic description. Site-specific variations, such as supported optional arguments or site specific arguments, would be given in the actual implemented service description and overrides any common information found in this generic description. This generic interface description can be matched with the site-specific one using the role attribute. \item[Comment] Even though the Interface type requires an accessURL child element, this element is intended to describe a service in the abstract--i.e. without reference to a particular installation of the service. Consequently, the accessURL may contain a bogus URL; applications should not expect it to be resolvable. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Even though the ``vr:Interface`` type requires an ```` child element, the ```` 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 :doc:`VOResource <../VOResource/VOResource>` resource record for the service instance (e.g. from a registry). #. The application extracts the :raw-latex:`\xmlel{standardID}` attribute for the desired service capability. #. The :raw-latex:`\xmlel{standardID}` is resolved (via a registry) to a :raw-latex:`\xmlel{vstd:ServiceStandard}` 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 :raw-latex:`\xmlel{vstd:ServiceStandard}` record. The so-called “simple” data access layer (DAL) services, such as the Simple Image Access services :doc:`SIA <../SIA/SIA>`, are registered using the :raw-latex:`\xmlel{vs:ParamHTTP}` interface type :doc:`VODataService <../VODataService/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 :raw-latex:`\xmlel{vstd:ServiceStandard}` record contains an interface of type :raw-latex:`\xmlel{vs:ParamHTTP}`, such ignoreable parameters should have their :raw-latex:`\xmlel{use}` attribute set to *ignored*. Applications that consume such :raw-latex:`\xmlel{vstd:ServiceStandard}` 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 :raw-latex:`\xmlel{vstd:ServiceStandard}` 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 :raw-latex:`\xmlel{vstd:ServiceStandard}` record is shown in Appendix :ref:`StandardsRegExt:app:fullrecord`. It describes the Simple Image Access Specification and in particular illustrates the recommended way to list input parameters defined by the standard. .. _`StandardsRegExt:sect:standardkeys`: 3.2 Defining Keys: StandardKey and StandardKeyURI ------------------------------------------------- The :raw-latex:`\xmlel{vstd:StandardKey}` type provides the means to define keys (as described in Sect. :ref:`StandardsRegExt:sect:keys`) within a :doc:`VOResource <../VOResource/VOResource>` record. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vstd:StandardKey} Type Schema Documentation} \noindent{\small{}The name and definition of a key--a named concept, feature, or property.\par} \noindent{\small{}This key can be identified via an IVOA identifier of the form ivo://authority/resource\#name where name is the value of the child name element.\par} \noindent{\small{}This type can be extended if the key has other metadata associated with it.\par} \vspace{1ex}\noindent\textbf{\xmlel{vstd:StandardKey} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vstd:StandardKey} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string of the form: \emph{([A-Za-z0-9;/$\backslash$?:@\&=$\backslash$+\$,$\backslash$-\_$\backslash$.!~$\backslash$*'$\backslash$($\backslash$)]|\%[A-Fa-f0-9]\{2\})+} \item[Meaning] The property identifier which would appear as the fragment (string after the pound sign, \#) in an IVOA identifier. To facilitate comparisons of such keys given that registry identifiers are case insensitive, all newly created standard keys must not contain uppercase letters. \item[Occurrence] required \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A human-readable definition of this property. \item[Occurrence] required \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Defining a key via a :raw-latex:`\xmlel{key}` element within a :doc:`VOResource <../VOResource/VOResource>` record implies the definition of a unique URI formed according to the syntax described in Sect. :ref:`StandardsRegExt:sect:keys` that represents the semantics given by the value of the :raw-latex:`\xmlel{description}` child element. Because the URI must be globally unique, the key name (given by the :raw-latex:`\xmlel{name}` child element) must be unique within the :doc:`VOResource <../VOResource/VOResource>` record. Though it is not needed by StandardsRegExt resource records, the StandardsRegExt schema further defines a convenience type, :raw-latex:`\xmlel{vstd:StandardKeyURI}`, which defines the legal pattern for a full standard key identifier (as defined in Sect. :ref:`StandardsRegExt:sect:keys`). Applications that wish to use XML Schema to validate the form of a key URI may import the StandardsRegExt schema and use this type. .. raw:: latex \begin{admonition}{Note} It is worth noting that just using or otherwise referencing a standard key URI in an application does not require importing the StandardsRegExt nor need there be any reference to the StandardsRegExt namespace. The role of the StandardsRegExt schema is simply to provide a way of documenting the definitions in a VOResource record. Thus, an application may dereference the URI for display or user help purposes; however, dereferencing is not necessary to use the URI. \end{admonition} .. _`StandardsRegExt:sect:operations`: 4 Operational Aspects ===================== .. _`StandardsRegExt:management-of-standards-records`: 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 :raw-latex:`\xmlel{standardID}` 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 :cite:p:`ivoatexDoc` offers templates for StandardsRegExt records and recommends keeping these in the respective standards’ source code repositories. .. _`StandardsRegExt:management-of-standard-keys`: 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 :cite:p:`2021ivoa.spec.0525D`; 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 ========== .. _`StandardsRegExt:app:fullrecord`: 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. .. code:: xml Simple Image Access Protocol SIA ivo://ivoa.net/std/SIA International Virtual Observatory Alliance Doug Tody Ray Plante 2004-05-24 Data Access Layer Working Group dal@ivoa.net software standard virtual observatory 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. http://www.ivoa.net/Documents/latest/SIA.html Other Research 1.0 http://sample.org/cgi-bin/sia GET text/xml+votable POS Search Position in the form "ra,dec" where ra and dec are given in decimal degrees in the ICRS coordinate system. degrees real SIZE Size of search region in the RA and Dec. directions in decimal degrees. degrees real FORMAT Requested format of images. string INTERSECT Choice of intersection of matched images with the region of interest. string NAXIS The number of pixels desired along each axis integer CFRAME the coordinate frame to impose on the image. string EQUINOX the epoch of the mean equator and equinox for the specified coordinate system reference frame (CFRAME). coordinate frame to impose on the image. string CRPIX the pixel position to locate the reference position in the output image. real CRVAL the world coordinates of the reference position in the output image in decimal degrees real CDELT the scale of the output image in decimal degrees per pixel real ROTANG the rotation angle to put into the coordinate system of the output image real PROJ the projection to impose in the construction of the output image string VERB the level of verbosity in the output. string .. _`StandardsRegExt:changes-from-previous-versions`: B Changes from Previous Versions ================================ .. _`StandardsRegExt:changes-since-rec-1.0`: B.1 Changes since Rec-1.0 ------------------------- - Corrected typos identified in RFC remarks - Corrected and clarified some wordings. - Removed references to :raw-latex:`\xmlel{vstd:StandardKeyEnumeration}` (which is now deprecated) from this document and associated schema. Replaced computer language example by :doc:`HiPS <../HiPS/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). .. _`StandardsRegExt:changes-since-pr-v1.0-20120217`: B.2 Changes since PR-v1.0 20120217: ----------------------------------- - none other than date and status. .. _`StandardsRegExt:changes-since-pr-v1.0-20120213`: B.3 Changes since PR-v1.0 20120213: ----------------------------------- - added the :raw-latex:`\xmlel{schema}` element to :raw-latex:`\xmlel{vstd:Standard}` - updated example for :raw-latex:`\xmlel{vstd:Standard}` .. _`StandardsRegExt:changes-since-pr-v1.0-20111017`: B.4 Changes since PR-v1.0 20111017: ----------------------------------- - added Note box that recommends against using :raw-latex:`\xmlel{vstd:StandardKeyEnumeration}` to describe keys when they are defined by an IVOA standard. - added statement highlighting that ``#`` signs are not allowed in key names. - added ``iwd`` and ``note`` as allowed values for :raw-latex:`\xmlel{vstd:EndorsedVersion}`’s :raw-latex:`\xmlel{status}` attribute. - converted a Note box in to a normative paragraph that recommends listing optional :raw-latex:`\xmlel{ParamHTTP}` parameters as ignored. Note that there is a related error in the :doc:`VODataService <../VODataService/VODataService>` standard: while the ``ignored`` value is defined in the schema, it is not included in the document text. - added sample :raw-latex:`\xmlel{vstd:ServiceStandard}` instance record back in as Appendix B - added references to :doc:`TAP <../TAP/TAP>` and :doc:`SIA <../SIA/SIA>` - fixed various grammatical typos. .. _`StandardsRegExt:changes-since-pr-v1.0-20110921`: B.5 Changes since PR-v1.0 20110921: ----------------------------------- - In :raw-latex:`\xmlel{endorsedVersion}`, changed “prop” to “pr”. - various typo corrections .. _`StandardsRegExt:changes-since-pr-v1.0-20110316`: B.6 Changes since PR-v1.0 20110316: ----------------------------------- - Corrected ampersand representation in schema listing - Various typo corrections and clarifications .. _`StandardsRegExt:changes-since-wd-v1.0-20100519`: 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) .. _`StandardsRegExt:changes-since-wd-v1.0-20100514`: B.8 Changes since WD-v1.0 20100514: ----------------------------------- - short name changed from VOStandard to StandardsRegExt .. _`StandardsRegExt:changes-since-wd-v0.4`: B.9 Changes since WD-v0.4: -------------------------- - removed App. B. (Sample instance) as examples appear throughout the document. .. [1] http://www.nsf.gov/ .. [2] http://cordis.europa.eu/fp7/capacities/home_en.html .. [3] https://ivoa.net/xml/index.html .. [4] :raw-latex:`\auxiliaryurl{StandardsRegExt-v1.1.xsd}`