StandardsRegExt.tex

\documentclass[11pt,a4paper]{ivoa}

\hyphenation{Standards-Reg-Ext}

\urlstyle{same}
\lstloadlanguages{XML}
\lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False,
  basicstyle=\footnotesize}

\usepackage{todonotes}

\input tthdefs
\input gitmeta


\ivoagroup{Registry}

\author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/DougBurke]{Douglas Burke}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Ray Plante}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon]{Guy Rixon}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris]{Dave Morris}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/RenaudSavalle]{Renaud Savalle}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}

\editor[http://www.ivoa.net/twiki/bin/view/IVOA/RenaudSavalle]{Renaud Savalle}

\previousversion[https://ivoa.net/documents/StandardsRegExt/20230921]{PR-20230921}
\previousversion[https://ivoa.net/documents/StandardsRegExt/20120508/]{REC-1.0}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20120217/]{
  PR-20120217}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20120213/]{
  PR-20120213}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20111017/]{
  PR-20111017}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20110921/]{
  PR-20110921}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20110316/]{
  PR-20110316}
\previousversion[http://www.ivoa.net/Documents/StandardsRegExt/20100519/]{
  WD-20100519}

\title{StandardsRegExt: a VOResource Schema Extension for Describing
IVOA Standards}

\begin{document}

\begin{abstract}
This document describes an XML encoding standard for metadata about
IVOA standards themselves, referred to as StandardsRegExt.  It is intended
to allow for the discovery of a standard via an IVOA identifier that
refers to the standard.  It also allows one to define concepts that
are defined by the standard which can themselves be referred to via an
IVOA identifier (augmented with a URL fragment identifier).  Finally,
it can also provide a machine interpretable description of a standard
service interface.  We describe the general model for the schema and
explain its intended use by interoperable registries for discovering
resources.
\end{abstract}


\section*{Conformance-related definitions}

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{https://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.

\section*{Acknowledgements}

The first versions of this document have been developed with support from the
National Science Foundation's\footnote{\url{http://www.nsf.gov/}}
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\footnote{\url{http://cordis.europa.eu/fp7/capacities/home_en.html}}.

This document contains text lifted verbatim, with small changes, and
with substantial changes from (old versions of) the VODataService
specification \citep{2021ivoa.spec.1102D}.  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.




\section{Introduction}

\label{sect:intro}

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 \citep{2007ivoa.spec.0302H}
(hereafter referred to as \textbf{RM}) defines
metadata terms for services and other discoverable resources.  A
specific XML encoding of these resources is described in the IVOA standard
VOResource \citep{2018ivoa.spec.0625P}.
In this schema, support for a standard service protocol is described
as a service's \emph{capability}; the associated metadata is
contained within the service resource description's
\xmlel{capability} element.  The
specific standard protocol supported is uniquely identified via an
attribute of the \xmlel{capability} element called
\xmlel{standardID}
whose value is a URI.  VOResource does
not place a formal validation requirement on the
\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
\citep{2016ivoa.spec.0523D},
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 \emph{standard keys} or \emph{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 \citep{2007ivoa.rept.0628P} using the
authority identifier \texttt{ivoa.net} as discussed in
Sect.~\ref{sect:operations}.
However, other standards, be they ad hoc or endorsed by another
body, may be published in any compliant registry.



\subsection{Role within the VO Architecture}

\begin{figure}
\centering
\includegraphics[width=0.9\textwidth]{role_diagram.pdf}
\caption{Architecture diagram for this document}
\label{fig:archdiag}
\end{figure}

Fig.~\ref{fig:archdiag} shows the role this document plays within the
IVOA architecture \citep{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 VOResource defines
the XML format.  StandardsRegExt is an extension of the VOResource
standard that defines extra metadata for describing a standard.

\subsection{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 \citep{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 \citep{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\footnote{\url{https://ivoa.net/xml/index.html}}.  For
documentation and development purposes, this document is accompanied by
a copy of that
schema\footnote{\auxiliaryurl{StandardsRegExt-v1.1.xsd}}.  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, \texttt{vr}, as in
\xmlel{vr:Resource} (a type defined in the VOResource schema).
Reference to specific elements and types defined in the StandardsRegExt
schema include the namespaces prefix, \texttt{vstd}, as in
\xmlel{vstd:ServiceStandard} (a type defined in the StandardsRegExt schema).
Use of the \texttt{vstd} prefix in compliant instance documents is
strongly recommended.  It is required where the Registry Interfaces
standard \citep{2018ivoa.spec.0723D} applies.




\section{The StandardsRegExt Data Model}

The StandardsRegExt extension in general enables the description of two
types of resources:

\begin{itemize}
\item  a generic standard (specified by an external document)
\item  a standard specifically defining a service protocol
\end{itemize}

Each type of resource can have a set of related, standardized names called \emph{keys}.

Here's an example of defining the HiPS standard and its associated \emph{keys}.

\begin{lstlisting}[language=xml]
<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>
\end{lstlisting}




\subsection{The Schema Namespace and Location}

The namespace associated with StandardsRegExt extensions is
$$
\hbox{\nolinkurl{http://www.ivoa.net/xml/StandardsRegExt/v1.0}.}
$$

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 \citet{2018ivoa.spec.0529H} (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
\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,



\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
xsi:schemaLocation="http://www.ivoa.net/xml/StandardsRegExt/v1.0
                      http://www.ivoa.net/xml/StandardsRegExt/v1.0"
\end{lstlisting}

The prefix, \texttt{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
\texttt{vstd} prefix is recommended.  Note also that in this
document, the \texttt{vr} prefix is used to label, as shorthand, a
type or element name that is defined in the VOResource schema, as in
\xmlel{vr:Resource}.



As recommend by the VOResource standard, the
StandardsRegExt schema sets \verb|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
\xmlel{xsi:type} attribute.



\subsection{Summary of Metadata Concepts}

The StandardsRegExt extension defines two new types of resources which
are specifically for independently documented standards:

\begin{description}
\item[\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
       \xmlel{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.
\item[\xmlel{vstd:ServiceStandard}] This resource type, which extends from
       \texttt{vstd:Standard}, is specifically for describing a
       standard service protocol (e.g. Simple Cone Search).  It
       differs from \xmlel{vstd:Standard} in that it also allows
       one to describe specific constraints on the service interface
       via its
       \xmlel{interface}
       element.


\end{description}

\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}


\subsection{Defining Enumerations of Identifiers }
\label{sect:keys}

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 \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 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 \emph{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 \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, \verb|#| -- to the IVOA identifier for the resource
description that defines the key:
$$
\hbox{\emph{ivoa-identifier}\verb|#|\emph{key-name}},
$$
where \emph{ivoa-identifier} is the resource's IVOA identifier and
\emph{key-name} is the name of a key defined in that resource.
Consistent with the URI standard, the
\emph{key-name} must not contain a pound (\verb|#|) sign.



For example, we consider a resource description with an IVOA
identifier given by
\nolinkurl{ivo://ivoa.net/std/QueryProtocol} that
defines a a key named \texttt{case-insensitive}; the URI
identifying this key would be:
$$
\hbox{\nolinkurl{ivo://ivoa.net/std/QueryProtocol#case-insensitive}}.
$$

Note that registry references in the sense of \emph{IVOA Identifiers 2}
(i.e., the part in front of the hash character) 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
\citet{2017ivoa.spec.0524T}.  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:



\begin{itemize}

\item  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.

\item  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.

\item  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.

\end{itemize}

\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 VOResource
metadata.  This could be done by extending \xmlel{vstd:StandardKey} type.


\section{The StandardsRegExt Metadata}

\subsection{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
\xmlel{xsi:type} attribute to the namespace-qualified type name.
Doing so implies that the semantic meaning of that type applies to the
resource.



\subsubsection{Standard}

The \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 \xmlel{vstd:Standard}
type is intended for standards \emph{other than} standard
protocols (which should use the \xmlel{vstd:ServiceStandard} type
instead).  It extends the generic \xmlel{vr:Resource} type as
follows.



% GENERATED: !schemadoc StandardsRegExt-v1.1.xsd Standard
\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]
<xs:complexType name="Standard" >
  <xs:complexContent >
    <xs:extension base="vr:Resource" >
      <xs:sequence >
        <xs:element name="endorsedVersion"
                  type="vstd:EndorsedVersion"
                  maxOccurs="unbounded" />
        <xs:element name="schema" type="vstd:Schema" minOccurs="0"
                  maxOccurs="unbounded" />
        <xs:element name="deprecated" type="xs:token" minOccurs="0" />
        <xs:element name="key" type="vstd:StandardKey" minOccurs="0"
                  maxOccurs="unbounded" />
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
\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}

% /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 \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 \xmlel{key} elements define terms with special
meaning to the standard; see Sect.~\ref{sect:standardkeys}.

The purpose of the required \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 \xmlel{use} attribute can further help steer the
users to the preferred version.


% GENERATED: !schemadoc StandardsRegExt-v1.1.xsd EndorsedVersion
\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]
<xs:complexType name="EndorsedVersion" >
  <xs:simpleContent >
    <xs:extension base="xs:string" >
      <xs:attribute name="status" default="n/a" >
        <xs:simpleType >
          <xs:restriction base="xs:string" >
            <xs:enumeration value="rec" />
            <xs:enumeration value="pr" />
            <xs:enumeration value="wd" />
            <xs:enumeration value="iwd" />
            <xs:enumeration value="note" />
            <xs:enumeration value="pen" />
            <xs:enumeration value="en" />
            <xs:enumeration value="n/a" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="use" >
        <xs:simpleType >
          <xs:restriction base="xs:string" >
            <xs:enumeration value="preferred" />
            <xs:enumeration value="deprecated" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:extension>
  </xs:simpleContent>
</xs:complexType>
\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]\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]\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}

% /GENERATED

When all versions of the standard are considered deprecated by the
resource publisher, the \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.

\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 \xmlel{<schema>} 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 \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.

% GENERATED: !schemadoc StandardsRegExt-v1.1.xsd Schema
\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]
<xs:complexType name="Schema" >
  <xs:sequence >
    <xs:element name="location" type="xs:anyURI" minOccurs="1"
              maxOccurs="1" />
    <xs:element name="description" type="xs:token" minOccurs="0"
              maxOccurs="1" />
    <xs:element name="example" type="xs:anyURI" minOccurs="0"
              maxOccurs="unbounded" />
  </xs:sequence>
  <xs:attribute name="namespace" type="xs:token" use="required" />
</xs:complexType>
\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}

% /GENERATED

As multiple schemas can be listed in the resource description, the
\textbf{\texttt{namespace}} attribute provides an
identifying label for each \textbf{\texttt{<schema>}}
element.


The main component of the \xmlel{schema}
content is the URL pointing to the schema's definition document, but
it can also provide additional information useful for display.


\subsubsection{ServiceStandard}

The \xmlel{vstd:ServiceStandard} resource type extends
\xmlel{vstd:Standard} to describe more
specifically a standard protocol.  It adds an
\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 \xmlel{vr:Interface}, which is defined in the
VOResource schema.


% GENERATED: !schemadoc StandardsRegExt-v1.1.xsd ServiceStandard
\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]
<xs:complexType name="ServiceStandard" >
  <xs:complexContent >
    <xs:extension base="vstd:Standard" >
      <xs:sequence >
        <xs:element name="interface" type="vr:Interface" minOccurs="0"
                  maxOccurs="unbounded" />
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
\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}

% /GENERATED

% NB: this is a repeat of the above generated comment
Even though the \texttt{vr:Interface} type requires an
\texttt{<accessURL>} child element,
the \texttt{<interface>} element in a
\texttt{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 \texttt{vstd:ServiceStandard} record with the
service resource description for the specific instance.  The intended
process for building that description is as follows:


\begin{enumerate}

\item  The application obtains a VOResource resource record for the
       service instance (e.g. from a registry).

\item  The application extracts the \xmlel{standardID} attribute
       for the desired service capability.

\item  The \xmlel{standardID} is resolved (via a registry) to a
       \xmlel{vstd:ServiceStandard} record for the service.  This
       description would capture the required and optional (but
       standard) components of the service interface.

\item  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 \xmlel{vstd:ServiceStandard}
       record.

\end{enumerate}

The so-called ``simple'' data access layer (DAL) services, such as the
Simple Image Access services \citep{2015ivoa.spec.1223D}, are
registered using the \xmlel{vs:ParamHTTP} interface type
\citep{2021ivoa.spec.1102D}
to describe their interfaces.  This interface
type allows one to list input parameters accepted by the service.
Each parameter can be marked as \emph{required}, \emph{optional},
or \emph{ignored}.  In several DAL standards, there are optional
parameters that implementations may choose to ignore.
When a \xmlel{vstd:ServiceStandard} record contains an interface of type
\xmlel{vs:ParamHTTP}, such ignoreable parameters should have their
\xmlel{use} attribute set to \emph{ignored}.

Applications that consume such
\xmlel{vstd:ServiceStandard} records should thus interpret the
parameters marked \emph{ignored} as \emph{optional} for use by
clients and \emph{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
\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 \xmlel{vstd:ServiceStandard}
record is shown in Appendix~\ref{app:fullrecord}.  It describes the
Simple Image Access Specification and
in particular illustrates the recommended way to list input parameters
defined by the standard.





\subsection{Defining Keys: StandardKey and StandardKeyURI}
\label{sect:standardkeys}

The \xmlel{vstd:StandardKey} type provides the means to
define keys (as described in Sect.~\ref{sect:keys}) within
a VOResource record.

% GENERATED: !schemadoc StandardsRegExt-v1.1.xsd StandardKey
\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]
<xs:complexType name="StandardKey" >
  <xs:sequence >
    <xs:element name="name" type="vstd:fragment" />
    <xs:element name="description" type="xs:token" />
  </xs:sequence>
</xs:complexType>
\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}

% /GENERATED


Defining a key via a \xmlel{key} element within a
VOResource record implies the definition of a unique URI formed
according to the syntax described in Sect.~\ref{sect:keys}
that represents the semantics given by the value of the
\xmlel{description} child element.  Because the URI must
be globally unique, the key name (given by the
\xmlel{name} 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,
\xmlel{vstd:StandardKeyURI}, which defines the legal pattern for
a full standard key identifier (as defined in
Sect.~\ref{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.


\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}

\section{Operational Aspects}
\label{sect:operations}

\subsection{Managment 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
\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 \url{http://rofr.ivoa.net/} for contact information.

The ivoatex package \citep{ivoatexDoc} offers templates for
StandardsRegExt records and recommends keeping these in the respective
standards' source code repositories.


\subsection{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 \citep{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.


\appendix

\section{A Sample Record}
\label{app:fullrecord}

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.

\lstinputlisting[language=XML]{sia-example.vor}

\section{Changes from Previous Versions}

\subsection{Changes since Rec-1.0}

\begin{itemize}
\item Corrected and clarified some wordings.
\item Removed references to \xmlel{vstd:StandardKeyEnumeration} (which is now deprecated)
from this document and associated schema.
Replaced computer language example by HiPS standard definition example.
\item Added en and pen to the list of document types.
\item Adding regulations on record upload and key additions.
\item Requiring new keys to be all-lowercase in order to simplify
comparisons.
\item Ported to ivoatex.  This entailed some re-shuffling the the
previous content.
\item 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).
\item 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).
\end{itemize}

\subsection{Changes since PR-v1.0 20120217:}

\begin{itemize}
\item  none other than date and status.
\end{itemize}

\subsection{Changes since PR-v1.0 20120213:}

\begin{itemize}
\item  added the \xmlel{schema} element to
       \xmlel{vstd:Standard}

\item  updated example for \xmlel{vstd:Standard}

\end{itemize}

\subsection{Changes since PR-v1.0 20111017:}

\begin{itemize}
\item  added Note box that recommends against using
       \xmlel{vstd:StandardKeyEnumeration} to
       describe keys when they are defined by an IVOA standard.

\item  added statement highlighting that \verb|#| signs are
       not allowed in key names.

\item  added \texttt{iwd} and \texttt{note} as allowed values
       for \xmlel{vstd:EndorsedVersion}'s
       \xmlel{status} attribute.

\item  converted a Note box in to a normative paragraph
       that recommends listing optional \xmlel{ParamHTTP}
       parameters as ignored.  Note that there is a related error in
       the VODataService standard: while
       the \texttt{ignored} value is defined in
       the schema, it is not included in the document text.

\item  added sample \xmlel{vstd:ServiceStandard}
       instance record back in as Appendix B

\item  added references to TAP and SIA

\item  fixed various grammatical typos.

\end{itemize}

\subsection{Changes since PR-v1.0 20110921:}

\begin{itemize}

\item  In \xmlel{endorsedVersion}, changed ``prop'' to ``pr''.

\item  various typo corrections

\end{itemize}

\subsection{Changes since PR-v1.0 20110316:}

\begin{itemize}

\item Corrected ampersand representation in schema listing

\item Various typo corrections and clarifications

\end{itemize}

\subsection{Changes since WD-v1.0 20100519:}

\begin{itemize}

\item  Prepped for PR

\item  improved discussion of example in section on the data model

\item  Added standard architecture sub-section

\item  updated in-lined schema (App. 1)

\end{itemize}

\subsection{Changes since WD-v1.0 20100514:}

\begin{itemize}

\item  short name changed from VOStandard to StandardsRegExt

\end{itemize}

\subsection{Changes since WD-v0.4:}

\begin{itemize}

\item  removed App. B. (Sample instance) as examples appear throughout
       the document.

\end{itemize}

\bibliography{ivoatex/ivoabib,ivoatex/docrepo}

\end{document}