==================== VOResource: an XML Encoding Schema for Resource Metadata ==================== Official bibliographic entry for published version :cite:p:`2025ivoa.spec.0416D`. :Status: VOResource 1.3 WD 2025-10-31 .. role:: raw-latex(raw) :format: latex .. .. _`VOResource:acknowledgments`: Acknowledgments =============== This document has been developed with support from the National Science Foundation’s Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), and from the European Commission’s Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON). Funding for the 2016 update was provided by BMBF grant GAVO-2014, grant number 05A14VHA. .. _`VOResource:conformance-related-definitions`: 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 :cite:p:`std:RFC2119`. The *Virtual Observatory (VO)* is a general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The `International Virtual Observatory Alliance (IVOA) `__ is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. .. _`VOResource:syntax-notation-using-xml-schema`: Syntax Notation Using XML Schema ================================ The eXtensible Markup Language, or XML, is document syntax for marking textual information with named tags and is defined by :cite:t:`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`. The XML Schema of VOResource is available from the IVOA document repository [1]_ at any time. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity. Where the content of the pieces of schema embedded in this text diverges from the schema document in the IVOA document repository, the version in the schema repository is authoritative. References to specific elements and types defined in the VOResource schema include the namespaces prefix :raw-latex:`\xmlel{vr}` as in :raw-latex:`\xmlel{vr:Resource}` (a type defined in the VOResource schema). For more details on the intended interpretation, refer to sect. :ref:`VOResource:sect:namespace`. .. _`VOResource:introduction`: 1 Introduction ============== The IVOA recommendation “Resource Metadata for the Virtual Observatory” :cite:p:`2007ivoa.spec.0302H`, hereafter referred to as the RM, defines metadata terms for describing resources. The RM defines a resource as: …VO element that can be described in terms of who curates or maintains it and which can be given a name and a unique identifier. Just about anything can be a resource: it can be an abstract idea, such as sky coverage or an instrumental setup, or it can be fairly concrete, like an organisation or a data collection. This definition is consistent with its use in the general Web community as “anything that has an identity” :cite:p:`std:RFC3986`. We expand on this definition by saying that it is also describable. The resource metadata are, then, the terms and concepts that describe a resource in general. The RM defines the terms as well as describes reasonable or allowed values; it does not, however, describe how the terms and values should be encoded. This is because resource metadata may be encoded in several different formats, depending on the context. The present document provides a concrete encoding of the resulting metadata model on XML suitable for embedding into OAI-PMH responses. .. raw:: latex \begin{admonition}{Note} The term ``VOResource'' is used to denote two different concepts within the IVOA community. The first refers specifically to the core XML schema defined by this document. The second refers more broadly to the core schema plus the set of legal extensions. In this document, use of the name ``VOResource'' corresponds to the first meaning. Reference to the broader set of schemas will be indicated explicitly with the annotating phrase, ``and its legal extensions.'' \end{admonition} In addition to concepts and structures laid down in the RM, VOResource also acknowledges other (though mostly related) metadata schemes. Of particular importance here is the metadata scheme employed by DataCite, which at the time of writing is at version 4.6 :cite:p:`std:DataCite46`. This, in particular, concerns the alignment of the vocabularies for date roles and relationships. The primary intended use of VOResource is to provide an XML interchange format for use with resource registries. A registry is a repository of resource descriptions and is employed by users and applications to discover resources. VOResource can be used to pass descriptions from publishers to registries and then from registries to applications. Another intended use is as a language for services to describe themselves directly. VOResource may be used in other ways, in whole or in part, using the standard XML mechanisms (e.g., import, include). The VOResource schema provides XML encoding for core metadata from the RM that (with a few exceptions) can apply to all resources; however, it is recognized that a full and useful description of a *specific* resource will require additional metadata that is relevant only to a resource of its type. Thus, the VOResource schema has been especially designed to be extended. The model for doing this is described in sect. :ref:`VOResource:sect:extending`. .. _`VOResource:sect:role`: 1.1 Role within the VO Architecture ----------------------------------- .. container:: float :name: VOResource:fig:archdiag .. raw:: latex \centering |image1| Fig. :ref:`VOResource:fig:archdiag` shows the role VOResource plays within the IVOA architecture :cite:p:`2021ivoa.spec.1101D`. VOResource depends on the following other IVOA standards: Resource Metadata, v1.12 The RM :cite:p:`2007ivoa.spec.0302H` provides the central concepts and structures mapped here into an XML schema. There are relationships to the following other IVOA standards: Registry Interfaces The Registry Interfaces :cite:p:`2018ivoa.spec.0723D` standard describes how registries exchange VOResource records, and it provides a :raw-latex:`\xmlel{vr:Resource}`-typed element to hold them within XML data (VOResource itself has no global elements). VOResource extensions VOResource lays the foundations upon which description schemes for concrete resources are built in various VOResource extensions. At the time of writing, recommendations have been passed for the description of VO Standards :cite:p:`2012ivoa.spec.0508H`, various “simple” data discovery protocols :cite:p:`2017ivoa.spec.0530P`, generic data services :doc:`ref <../VODataService/VODataService>`, and TAP services :cite:p:`2012ivoa.spec.0827D`. The Registry Interfaces standard also contains a VOResource extension. RegTAP The Registry Relational Schema :cite:p:`2019ivoa.spec.1011D` gives a relational mapping of the models discussed here. VOSI The VO support interfaces :cite:p:`2017ivoa.spec.0524G` re-use the service model developed here to facilitate service self-description. Vocabularies VOResource contains several controlled vocabularies that are maintained and can be used as per :cite:t:`2023ivoa.spec.0206D`. .. _`VOResource:sect:model`: 2 The VOResource Data Model =========================== The primary use for VOResource, of course, is to describe a resource using the metadata concepts defined in the RM. Here is an example of a VOResource document describing an organisation, the Radio Astronomy Imaging Group at the National Center for Supercomputing Applications. .. code:: xml :number-lines: 2 NCSA Radio Astronomy Imaging NCSA-RAI ivo://rai.ncsa/RAI National Center for Supercomputing Applications Crutcher, Richard http://rai.ncsa.uiuc.edu/rai.jpg 1993-01-01 Plante, R. rplante@ncsa.uiuc.edu radio-astronomy astronomy-software astronomy-web-services search-for-extraterrestrial-intelligence The Radio Astronomy Imaging Group at the National Center for Supercomputing Applications is focused on applying high-performance computing to astronomical research. Our projects include the NCSA Astronomy Digital Image Library, the BIMA Data Archive, the BIMA Image Pipeline, and the National Virtual Observatory. http://rai.ncsa.uiuc.edu/ Organisation Research Berkeley-Illinois-Maryland Array (BIMA) Combined Array for Research in Millimeter Astronomy (CARMA) This example illustrates some important components of a VOResource record: #. the VOResource namespace (line 3), #. the specific type of resource indicated by the value of the :raw-latex:`\xmlel{xsi:type}` attribute as discussed in sect. :ref:`VOResource:sect:derivedtypes` (line 2), #. the location of the schema documents used by this description (lines 6–9) – this is to facilitate document validation –, #. values for the three main types of core metadata: identity (lines 17–19), curation (lines 21–36), and content (lines 38–54), #. a reference to another resource is made by providing that resource’s IVOA identifier (line 22), #. string values can be padded with spaces for easier readability (e.g., lines 22–24), #. extension metadata specific to the type of resource (lines 56–59). Actual services obviously need additional metadata defining the modalities of service access. In VOResource, such information is typically encapsulated in :raw-latex:`\xmlel{vr:Capa\-bility}`-typed elements. This document only provides a generic base class for them, deferring the definition of more useful subclasses to VOResource extensions like VODataService :doc:`ref <../VODataService/VODataService>` or SimpleDALRegExt :cite:p:`2017ivoa.spec.0530P`. .. _`VOResource:sect:namespace`: 2.1 The Schema Namespace and Location ------------------------------------- The VOResource schema namespace URI is .. math:: \hbox{\nolinkurl{http://www.ivoa.net/xml/VOResource/v1.0}}\,\,. The namespace URI has been chosen to allow it to be resolved as a URL to the XML Schema document that defines the VOResource schema. Applications may assume that the namespace URI is so resolvable. Although this schema is in version 1.3 now, the URL still ends in ``v1.0``. This is to avoid unnecessarily breaking existing clients relying on the namespace as defined by version 1.0 of this specification. As laid out in the IVOA schema versioning policies :cite:p:`2018ivoa.spec.0529H`, although minor versions should never have been part of namespace URIs, for namespaces defined before this note they cannot be dropped despite their potential for confusion. Clients should in general not care about minor versions of schemas. To cover the rare cases in which such information is necessary, instance documents for version 1.3 of VOResource must have a :raw-latex:`\xmlel{version}` attribute with value ``1.3`` on their root element (i.e., :raw-latex:`\xmlel{Resource}`). Document authors are strongly encouraged to bind this namespace to the :raw-latex:`\xmlel{vr:}` prefix. While in generic XML processing, the concrete prefix used is irrelevant as long as the namespace URI mapped is the one given by this specification, in the Virtual Observatory context uniform, per-major-version prefixes are viewed as helping interoperability. This is particularly true when prefixes appear in attribute values (e.g., of :raw-latex:`\xmlel{xsi:type}`), as non-schema aware XML processors cannot URI-normalize such occurrences. Also, non-XML-aware software (e.g., ADQL engines) will use these prefixes rather than the full namespace URIs. Authors of instance documents that use the VOResource schema may choose to provide a location for VOResource XML Schema document using the :raw-latex:`\xmlel{xsi:schemaLo\-cation}` attribute; the choice of the location value is the choice of the author. In general, the use of :raw-latex:`\xmlel{xsi:schemaLocation}` is recommended by this specification with a namespace URI given as the location as illustrated in the example above, unless the application prefers otherwise. :: xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0 http://www.ivoa.net/xml/VOResource/v1.0" The VOResource XML schema sets :raw-latex:`\xmlel{elementFormDefault}` to unqualified. This means that instance documents must not bind the empty namespace in any element containing VOResource elements, as XML element names in VOResource must be interpreted outside of any namespace. Conversely, the VOResource namespace prefix must not be used to qualify tag names of VOResource elements. In general, namespace prefixes in VOResource are only used to qualify type names given as values to the :raw-latex:`\xmlel{xsi:type}` attribute in VOResource (see next section). VOResource extensions should also set ``elementFormDefault="unqualified"`` for consistency. .. _`VOResource:sect:core`: 2.2 The Core Structural and Semantic Model ------------------------------------------ The VOResource schema only defines global types; it does not define any global elements (often referred to as root elements). It is the responsibility of the application to define the root element of the VOResource-employing documents it operates on. Typically, the root element is defined in a separate application-specific schema. The type of an application document’s root element is not assumed to be any particular type defined in the VOResource schema (nor any of its legal extensions). In fact, it need not be of a type from the VOResource at all; rather, VOResource types may appear anywhere in the document. The IVOA Registry Interface standard :cite:p:`2018ivoa.spec.0723D`, for example, at the time of writing includes a small schema that defines a global element :raw-latex:`\xmlel{ri:Resource}` of base type :raw-latex:`\xmlel{vr:Resource}`. It is primarily intended as the child of :raw-latex:`\xmlel{oai:metadata}` in OAI-PMH responses :cite:p:`std:oaipmh`, the protocol used for VOResource record exchange by Registry Interface-compliant Registries. Note that even :raw-latex:`\xmlel{ri:Resource}`-typed elements will still use :raw-latex:`\xmlel{xsi:type}` to indicate the actual resource type. .. raw:: latex \begin{admonition}{Note} In the example instance document at the beginning of section~\ref{sect:model}, the root element \xmlel{resource} is not defined in any schema. Nevertheless, this document is still legal and verifiable XML. This is because the element's type is explicitly specified with the \xmlel{xsi:type} attribute. \end{admonition} Applications describe a single resource using an element of the type :raw-latex:`\xmlel{vr:Resource}` or a legal derivation of it. The content of this element is referred to as the **core VOResource metadata** and can be grouped into four categories (corresponding to the sections 3.1, 3.2, 3.3, and 4 of the RM): - identity metadata: the :raw-latex:`\xmlel{title}`, :raw-latex:`\xmlel{shortName}`, and :raw-latex:`\xmlel{identifier}` elements; - curation metadata: the contents of the :raw-latex:`\xmlel{curation}` element; - general content metadata: the contents of the :raw-latex:`\xmlel{content}` element; - metadata quality flags: the :raw-latex:`\xmlel{validationLevel}` element. These elements are defined in more detail in sect. :ref:`VOResource:sect:metadata`. .. _`VOResource:naming-convention`: 2.2.1 Naming Convention ~~~~~~~~~~~~~~~~~~~~~~~ VOResource uses the following conventions for names of elements and types: - all global types it defines have names that are capitalized. (This practice would extend to global elements, if they existed in the VOResource.) - Locally defined elements begin with a lower-case character. - For all types and element names that are made up of multiple words, such as :raw-latex:`\xmlel{shortName}`, upper-case letters are used to demarcate the start of appended word (the “camel” format). - Names that include abbreviations, such as :raw-latex:`\xmlel{IdentifierURI}`, all letters in the abbreviation are capitalized. It is recommended that this convention be followed in other schemas that either use the VOResource schema (via an :raw-latex:`\xmlel{xsd:import}` or :raw-latex:`\xmlel{xsd:include}`) or extend it. .. _`VOResource:string-values`: 2.2.2 String Values ~~~~~~~~~~~~~~~~~~~ Many of the elements in VOResource that are meant to have string or URI values are defined as being of the type :raw-latex:`\xmlel{xs:token}`. This allows authors of VOResource instance documents to pad string and URI values with spaces and include carriage returns to improve readability. The definition of these types will cause an XML Schema-compliant parser to replace tab, line feed, and carriage return characters with simple spaces, then replace multiple sequential occurrences of spaces with a single space, and then remove all leading and trailing spaces. The :raw-latex:`\xmlel{description}` children of resources and capabilities, on the other hand, are of type :raw-latex:`\xmlel{xs:string}`, which means that even schema-aware processors will preserve whitespace. This is intended to allow simple markup like paragraphs (empty lines) in the descriptions, which may be little texts. Since in VO practice, constructs like simple ASCII tables sometimes appear in such descriptions, clients are encouraged to not reflow descriptions and display them in a fixed-with font. .. _`VOResource:language-and-transliteration`: 2.2.3 Language and Transliteration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Several VOResource elements contain natural language (e.g., :raw-latex:`\xmlel{description}` or :raw-latex:`\xmlel{title}`). In order to ensure reliable discovery, in core VOResource, these elements must contain English text, with US spelling strongly preferred; technically, an :raw-latex:`\xmlel{xml:lang}` value of ``en-US`` is implied. Registry extensions may allow :raw-latex:`\xmlel{xml:lang}` attributes on elements. If they do, such elements must be repeatable, and an element without :raw-latex:`\xmlel{xml:lang}` (and hence, ``en-US`` implied) should be required for global discoverability. The requirements on :raw-latex:`\xmlel{xml:lang}` from the XML specification :cite:p:`std:XML` apply. Additionally, in VOResource documents BCP 47 language identifiers must be written in lowercase. Several VOResource elements contain names. Again, for reliable global discoverability, such names must be given in (common) English transliteration where their original form uses non-Latin scripts. Latin letters with diacritics are allowed, but Registry components are generally expected to treat them equivalent to their base letters. .. _`VOResource:dates-and-times`: 2.2.4 Dates and Times ~~~~~~~~~~~~~~~~~~~~~ All VOResource elements and attributes that contain dates must be interpreted as UTC dates and must be encoded in compliance with ISO8601 :cite:p:`std:iso8601` standard Date and Time Format. The :raw-latex:`\xmlel{vr:UTCTimestamp}` type provides a special restriction of the format that requires inclusion of date and time, but enforces the use of the UTC timezone. The time format to be used by VOResource (designed to coincide with what the OAI-PMH transport protocol mentioned above defines) therefore requires timestamps like .. math:: \hbox{\texttt{2008-02-22T12:22:34Z}}, where optional fractional seconds are allowed. See the schema documentation for the actual regular expression pattern. For historical reasons, VOResource also allows a form without any timezone marker. Such timestamps are to be interpreted as if they had a trailing Z. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:UTCTimestamp} Type Schema Documentation} \noindent{\small A timestamp that is compliant with ISO8601 and fixes the timezone indicator, if present, to {"}Z{"} (UTC). VOResource writers should always include the timezone marker. VOResource readers must interpret timestamps without a timezone marker as UTC. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:UTCTimestamp} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} Where day granularity might suffice for some instance documents, VOResource and extensions can employ the :raw-latex:`\xmlel{vr:UTCDateTime}` type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:UTCDateTime} Type Schema Documentation} \noindent{\small A date stamp that can be given to a precision of either a day (type xs:date) or seconds (type xs:dateTime). Where only a date is given, it is to be interpreted as the span of the day on the UTC timezone if such distinctions are relevant. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:UTCDateTime} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} .. _`VOResource:sect:altidform`: 2.2.5 Alternate Identifiers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ While registered resources should be referenced with their IVOA identifiers in order to allow simple and uniform resolution, other identifier schemes are frequently useful in order to have machine-readable references to entities not registered (e.g., authors) or also resolvable using external resolvers. Prime examples for such identifiers are DOIs and ORCIDs. VOResource keeps such identifiers in :raw-latex:`\xmlel{altIdentifier}` elements (for resources and creators, which can have multiple such identifiers) or attributes (for elements of type :raw-latex:`\xmlel{vr:ResourceName}`, which for simplicity are only allowed one alternate identifier each). In order to not bind the Registry to any single resolver, we prefer non-http URI forms for such identifiers. Where the originators of the identifier scheme strongly urges the use of http URIs directly pointing to a resolver, we adopt these conventions. The following identifier schemes are recognised by VOResource in this version: doi A digital object identifier. These always use the doi URI schema rather the http schema. Hence, in VO resource records, ``doi:10.5072/7273288`` must be used rather than ``https://doi.org/10.5072/7273288`` or any of its variants. orcid An open researcher and contributor id. In accordance with ORCID’s instructions [2]_, ORCIDs must be given as HTTPS URIs using orcid.org’s infrastructure, for instance https://orcid.org/0000-0001-2345-6789. bibcode A bibliographic code as used by ADS and CDS :cite:p:`1995ASSL..203..259S`. These must be used with an ad-hoc URI scheme of ``bibcode``, as in ``bibcode:2008ivoa.spec.0222P``. ROR id An identifier for an organisation (and hence suitable in elements like :raw-latex:`\vorent{publisher}` or records of type :raw-latex:`\vorent{vr:Organisation}`) taken from the Research Organization Registry [3]_. In accordance with their 2024 preferences, ROR identifiers in VOResource always use the browser-resolvable URL form with an https schema, such as ``https://ror.org/04rcqnp59``. This regulation stays in place for VOResource even if upstream reconsiders this preference. Other schemes may be used in :raw-latex:`\xmlel{altIdentifier}`-s. .. _`VOResource:voresource-semantics`: 2.2.6 VOResource Semantics ~~~~~~~~~~~~~~~~~~~~~~~~~~ All VOResource types and elements have an associated semantic meaning which is given in the first :raw-latex:`\xmlel{xsd:documentation}` node within the type or element’s definition in the schema. The meaning associated with a type is generic, indicating the kind of information the type provides. The semantics that are delivered by a VOResource instance document, however, are those associated with VOResource elements. The meaning of a VOResource element can be thought of as having two parts: the generic meaning of the set of information it contains as defined by its type, and a specific meaning describing the context in which that information applies. Because all VOResource elements are locally defined (in the XML Schema sense), they do not have an absolute meaning, but rather have a meaning tied to the thing being described by that element as represented by the enclosing type. Here are three examples that illustrate the semantics communicated by VOResource entities: #. The :raw-latex:`\xmlel{vr:Curation}` type describes the curation of a resource. The :raw-latex:`\xmlel{curation}` element describes curation of the specific resource described by the enclosing :raw-latex:`\xmlel{vr:Resource}` type and identified by its :raw-latex:`\xmlel{identifier}` element. #. The :raw-latex:`\xmlel{vr:ResourceName}` type is a generic reference to another resource. The :raw-latex:`\xmlel{publisher}` element gives a reference to the publisher of the specific resource being described which may itself be a registered resource described elsewhere. #. The :raw-latex:`\xmlel{title}` element gives the title of the resource being described by the enclosing :raw-latex:`\xmlel{vr:Resource}` type and identified by its :raw-latex:`\xmlel{identifier}` element. The :raw-latex:`\xmlel{title}` element’s type, :raw-latex:`\xmlel{xs:token}` (a restriction on :raw-latex:`\xmlel{xsd:string}`), has no inherent meaning associated with it. Additional semantics are transmitted through the use of derived types using the :raw-latex:`\xmlel{xsi:type}` attribute. In the sample instance document above, the use of the XSI type ``vr:Organisation`` means that the resource being described is specifically an organisation as defined by the :raw-latex:`\xmlel{vr:Organisation}` type. This type provides additional metadata that are not part of the core resource metadata. The semantics associated with the use of :raw-latex:`\xmlel{xsi:type}` is described further in the next subsection. .. _`VOResource:sect:derivedtypes`: 2.2.7 Refined Semantics with Derived Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a resource is described with an element explicitly of the type :raw-latex:`\xmlel{vr:Resource}`, it is being described in the most generic sense. The metadata presented in this type, including both free text values and controlled vocabulary, can give some sense of what type of resource is being described and what it might be used for. However, the most useful descriptions of resources will not explicitly use the :raw-latex:`\xmlel{vr:Resource}` type; rather, they will use types that are derived from :raw-latex:`\xmlel{vr:Resource}`. Defining derived :raw-latex:`\xmlel{vr:Resource}` types accomplishes two things: #. it sharpens the semantic meaning of the resource description by indicating what specific type of resource it is, and #. it *may* allow additional metadata not part of the core but specific to that type of resource. The VOResource schema defines two types derived from :raw-latex:`\xmlel{vr:Resource}`: :raw-latex:`\xmlel{vr:Orga\-nisation}` and :raw-latex:`\xmlel{vr:Service}`. The :raw-latex:`\xmlel{vr:Organisation}` adds metadata describing the astronomical facilities such as telescopes that are associated with the organisation it describes. The :raw-latex:`\xmlel{vr:Service}` type adds an element called :raw-latex:`\xmlel{capability}` which describes the service’s interface as well as information regarding its behavior. Extension of the :raw-latex:`\xmlel{vr:Resource}` type is a key way in which derivation is used in VOResource to provide refined resource descriptions. Two other important parent types in the schema are :raw-latex:`\xmlel{vr:Capability}` and :raw-latex:`\xmlel{vr:Interface}`; these are extended to provide more refined descriptions of services (see sect. :ref:`VOResource:sect:servicemodel`). The motivation for extending these types is the same as for :raw-latex:`\xmlel{vr:Resource}`: to provide more specific semantic meaning through the derived type’s name, and to provide additional, specialized metadata that is not part of the parent type. Note, however, that in general, a derived type need not alter the content model of its base type. This allows derived types to add more specific meaning without adding any additional metadata. As described in sect. :ref:`VOResource:sect:core`, it is intended that derived :raw-latex:`\xmlel{vr:Resource}`, :raw-latex:`\xmlel{vr:Capability}` and :raw-latex:`\xmlel{vr:Interface}` types be invoked in instance documents using the :raw-latex:`\xmlel{xsi:type}` attribute (as illustrated in the sample document above). This method illustrates a polymorphism for resource metadata in that any place where an element of parent type is expected, the derived type may be inserted. The use of :raw-latex:`\xmlel{xsi:type}` illustrates both what specific type is being inserted in as well as what it is being inserted in for. That is, as in our example, the *resource* being described is an *organisation*. The other mechanism for polymorphism provided by XML Schema is substitution groups. Invoking derived :raw-latex:`\xmlel{vr:Resource}` types via elements in a substitution group is discouraged because it is less obvious from looking at the instance document that a substitution is being made. .. _`VOResource:sect:servicemodel`: 2.2.8 The Service Data Model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vr:Service}` type extends the core :raw-latex:`\xmlel{vr:Resource}` metadata data by adding the :raw-latex:`\xmlel{capability}` element (see sect. :ref:`VOResource:sect:serviceelements`). This element is used to describe a major functionality of the service, usually accessible through a single service endpoint URL. In particular, it is used to describe support for an IVOA service standard (e.g. Simple Image Access Protocol). A service resource record may have multiple child :raw-latex:`\xmlel{capability}` elements, each describing a different major functionality; however, these capabilities should be related in an obvious, logical way (they would hardly share their core VOResource metadata otherwise). The :raw-latex:`\xmlel{capability}` element, through its type :raw-latex:`\xmlel{vr:Capability}`, describes the behavior of service capability and how to access it. The latter is described by a child :raw-latex:`\xmlel{interface}` element. As for the behavior, the base :raw-latex:`\xmlel{vr:Capability}` type only provides a :raw-latex:`\xmlel{description}` element that can contain human-readable text on what this capability provides. More structured behavioral information must be provided through specialized :raw-latex:`\xmlel{vr:Capability}` extensions. In particular, a service standard (e.g. Simple Image Access Protocol) or an ancillary standard built upon the service standard will define an extension of :raw-latex:`\xmlel{vr:Capability}` that adds additional metadata that can describe the service’s behavior in relation to the standard. The added metadata can describe limitations of the service implementation or indicate support for optional features. As a rough guideline, whenever the standard has a SHOULD or MAY in the sense of RFC2119 and clients have no other way to discover the choices of a concrete service implementation, a respective declaration should be considered for the capability or the interface elements defined by the registry extension. The specific :raw-latex:`\xmlel{vr:Capability}` type is invoked using the :raw-latex:`\xmlel{xsi:type}` mechanism described in sect. :ref:`VOResource:sect:namespace`. Here is an example for assigning a specialized Capability type for a standard service capability. In this example, it is assumed that :raw-latex:`\xmlel{ExampleCapType}` extension type is defined in a separate schema document, the target namespace of which is being bound to the :raw-latex:`\xmlel{ex:}` prefix in the capability element itself (it could, of course, be bound in some enclosing element just as well): .. code:: xml ... Note that the :raw-latex:`\xmlel{xsi:type}` and the :raw-latex:`\xmlel{standardID}` can vary independently of each other. There is no requirement to use a given capability type for an endpoint conforming to a certain standard, as indicated by the capability’s :raw-latex:`\xmlel{standardID}`. Conversely, it may make sense to re-use a certain capability type in a different standard. Historically, several VOResource extension types have had fixed :raw-latex:`\xmlel{standardID}`s. This is now discouraged, as it needlessly limits the applicability of the encoded metadata models. If the service capability being described does not conform to any standard or if the standard does not require any specialized capability metadata for describing an implementation’s behavior, then :raw-latex:`\xmlel{vr:Capability}` can be used as-is, possibly with the appropriate :raw-latex:`\xmlel{standardID}`. Each :raw-latex:`\xmlel{capability}` element can contain one or more child :raw-latex:`\xmlel{interface}` elements, each describing how the capability can be accessed. The :raw-latex:`\xmlel{interface}` element’s type, :raw-latex:`\xmlel{vr:Interface}`, is abstract; thus, the :raw-latex:`\xmlel{interface}` element must be accompanied by an :raw-latex:`\xmlel{xsi:type}` attribute that indicates a :raw-latex:`\xmlel{vr:Interface}` extension type. The VOResource schema defines two :raw-latex:`\xmlel{vr:Interface}` extension types: :raw-latex:`\xmlel{vr:WebBrowser}`, for describing an interface access via web browser, and :raw-latex:`\xmlel{vr:WebService}`, for accessing a service described by a Web Service Description Language (WSDL) document. In today’s VO, the latter interface type has almost vanished with the general move away from SOAP-based architectures. VO standard capabilities currently typically use interface types defined in VODataService. [4]_ As an example, a simple, browser-based interface could be declared with an untyped capability like this (this assumes the :raw-latex:`\xmlel{vr}` prefix has been bound in an ancestor element): .. code:: xml http://example.org/browser-service Note that for less trivial interfaces, in particular :raw-latex:`\xmlel{vs:ParamHTTP}`, the parameters accepted should be declared in the interface element. When a :raw-latex:`\xmlel{capability}` contains more than one :raw-latex:`\xmlel{interface}`, each :raw-latex:`\xmlel{interface}` should be interpreted as an alternative interface for accessing essentially the same underlying capability. The interfaces can differ in their overall type (e.g. :raw-latex:`\xmlel{vr:WebBrowser}`, :raw-latex:`\xmlel{vr:WebService}`) or in the supported input parameters or output products. When a standard capability is being described (i.e., there is a :raw-latex:`\xmlel{standardID}` attribute), then at least one of the :raw-latex:`\xmlel{interface}` elements should describe an interface required by the standard. The :raw-latex:`\xmlel{role}` attribute is used to mark the standard interfaces (typically with the value “std”). All other interfaces are considered non-standard alternatives. To best support real-world discovery strategies, it is recommended to avoid having non-standard interfaces in capabilities with well-known :raw-latex:`\xmlel{standardID}`s. Another way :raw-latex:`\xmlel{interface}`s inside the same :raw-latex:`\xmlel{capability}` element can be used is if a standard forsees different versions of a protocol within the same capability. Different interfaces can then be distinguished by different values of the interface’s :raw-latex:`\xmlel{version}` attribute. Previous versions of this document in effect recommended this pattern for VO standards. While this pattern can still be employed, most VO standards that actually have different versions distinguish their endpoints by different standard identifiers, as described in section 4.2 of IVOA Identifiers 2.0 :cite:p:`2016ivoa.spec.0523D`. In these cases – where the :raw-latex:`\xmlel{capability}`’s :raw-latex:`\xmlel{standardID}` attribute already uniquely determines the protocol spoken –, the specification of :raw-latex:`\xmlel{version}` on :raw-latex:`\xmlel{interface}` elements is optional (although encouraged). .. _`VOResource:sect:extending`: 2.3 Extending the VOResource Schema ----------------------------------- A schema made up only of global type definitions provides great flexibility for extension. Any global type defined in the VOResource schema may be used as the base of a derived type defined in another schema. The schema containing the derived types must declare its own namespace URI or default to the null namespace; it must not adopt the VOResource namespace URI. The application must then define what schemas, identified by their namespace URIs, are supported and/or required. A **VOResource extension** is an XML Schema document whose primary purpose is to define new types derived from those defined in the VOResource schema for use in resource descriptions. It is recommended that VOResource extensions follow the definition styles used by the core VOResource. In particular: - *Provide semantic definitions of all types and elements within the first :raw-latex:`\xmlel{xsd:do\-cumentation}` element inside the type or element definition.* Subsequent documentation elements may provide additional comments or discussion. - *Avoid the use of :raw-latex:`\xmlel{xsd:choice}` elements.* VOResource does not use the choice structure because it does not map readily into any object-oriented software language structure. Choices are handled instead as multiple derived types that can be inserted in place of a parent type; for examples, see the :raw-latex:`\xmlel{vs:VOTableType}` and :raw-latex:`\xmlel{vs:SimpleDataType}` defintions in VODataService 1.1 :cite:p:`2010ivoa.spec.1202P`. - *Avoid the use of substitution groups*. VOResource prefers instead the use of :raw-latex:`\xmlel{xsi:type}` which are (with a few exceptions) functionally equivalent to substitution groups in terms of structure; however, :raw-latex:`\xmlel{xsi:type}` serves as an obvious flag in the instance document that a substitution has been made. - *Choose semantically meaningful names for derived types.* When the derived type appears in the pattern ````, choose a *derivedType* name such that the sentence, “a *derivedType* is a kind of *elname*” makes natural and obvious sense. For example, “an *Organisation* is a kind of *resource*.” - *Follow the VOResource naming conventions*. There are two types of derivation that are particularly important to the VOResource data model: derivation of the :raw-latex:`\xmlel{vr:Resource}` type, used to define specific types of resources, and the derivation of service metadata elements. .. _`VOResource:sect:definingresourcetypes`: 2.3.1 Defining New Resource Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Derivation of :raw-latex:`\xmlel{vr:Resource}` to define new kinds of resources should be done by extension (i.e., using :raw-latex:`\xmlel{xsd:extension}`) rather than restriction. It is not required that the derived type change the content model from that of the :raw-latex:`\xmlel{vr:Resource}` base type; in this case, the purpose of the derivation is only to sharpen the semantic meaning of the resource description. In VOResource itself, this mechanism is used to derive :raw-latex:`\xmlel{vr:Organisation}` and :raw-latex:`\xmlel{vr:Service}`. .. _`VOResource:sect:serviceelements`: 2.3.2 Defining New Service Capabilities and Interfaces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As described in sect. :ref:`VOResource:sect:servicemodel`, a service standard will often define a new :raw-latex:`\xmlel{vr:Capability}` extension type to allow implementations to describe how they support the standard. This definition of the :raw-latex:`\xmlel{vr:Capability}` extension should be done in a schema document with a namespace identifier that is dedicated to that standard (hereafter referred to as *the standard’s extension schema*). The extension type should include elements representing the applicable Capability metadata described in section 5.2 of the RM (e.g. *Service.MaxReturnRecords*, *Service.MaxReturnSize*) but can also include other concepts that are specific to that standard. An extension schema can define new interface types, though not necessarily in the context of any specific standard service capability. The basic :raw-latex:`\xmlel{vr:Interface}` type provides only :raw-latex:`\xmlel{accessURL}`, :raw-latex:`\xmlel{mirrorURL}`, and :raw-latex:`\xmlel{security\-Method}` as child elements. A derived :raw-latex:`\xmlel{vr:Interface}` type must indicate in the documentation how the :raw-latex:`\xmlel{accessURL}` should be interpreted and used. The derived type may also include other added metadata describing how to use the service (e.g., a description of the input arguments). If the interface extension type is expected to be referenced by a standard service capability, then it is recommended that the additional metadata be optional unless the metadata is absolutely required by clients in order to invoke the service. Examples for extension schemas can be found in the IVOA Document Repository. [5]_ Sect. :ref:`VOResource:sect:role` enumerates the ones in Recommendation state at the time of writing. In VOResource itself, the mechanism can be inspected in the derivation of :raw-latex:`\xmlel{vr:WebBrowser}` and :raw-latex:`\xmlel{vr:WebService}`. .. _`VOResource:sect:metadata`: 3 The VOResource Metadata ========================= This section enumerates the types and elements defined in the VOResource schema. .. _`VOResource:sect:restype`: 3.1 The Base Resource Type -------------------------- A resource, as defined by the RM, is any entity or component of a VO application that is describable and identifiable by an IVOA Identifier. A resource is described using VOResource by an element of the type :raw-latex:`\xmlel{vr:Resource}` or one of its legal extensions. The schema definition (below) includes elements that encode the identity, curation, and general content metadata for a resource (see sections 3.1 through 3.3 of the RM). The RM states that certain metadata are required in a minimally compliant resource description; this requirement is enforced by the VOResource schema definition. .. raw:: latex \goodbreak .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Resource} Type Schema Documentation} \noindent{\small Any entity or component of a VO application that is describable and identifiable by an IVOA Identifier. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Resource} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Resource} Attributes} \begingroup\small\begin{bigdescription} \item[created] \begin{description} \item[Type] string \item[Meaning] The UTC date and time this resource metadata description was created. \item[Occurrence] required \item[Comment] This timestamp must not be in the future. This time is not required to be accurate; it should be at least accurate to the day. Any non-significant time fields should be set to zero. \end{description} \item[updated] \begin{description} \item[Type] string \item[Meaning] The UTC date this resource metadata description was last updated. \item[Occurrence] required \item[Comment] This timestamp must not be in the future. This time is not required to be accurate; it should be at least accurate to the day. Any non-significant time fields should be set to zero. \end{description} \item[status] \begin{description} \item[Type] string with controlled vocabulary \item[Meaning] a tag indicating whether this resource is believed to be still actively maintained. \item[Occurrence] required \item[Allowed Values]\hfil \begin{longtermsdescription}\item[active] resource is believed to be currently maintained, and its description is up to date (default). \item[inactive] resource is apparently not being maintained at the present. \item[deleted] resource publisher has explicitly deleted the resource. \end{longtermsdescription} \end{description} \item[version] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] The VOResource XML schema version against which this instance was written. Implementors should set this to the value of the version attribute of their schema's root (xs:schema) element. Clients may assume version 1.0 if this attribute is missing. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Resource} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{validationLevel}] \begin{description} \item[Type] \xmlel{vr:ValidationLevel} with optional attributes \item[Meaning] A numeric grade describing the quality of the resource description, when applicable, to be used to indicate the confidence an end-user can put in the resource as part of a VO application or research study. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] See vr:Validation for an explanation of the allowed levels. \item[Comment] Note that when this resource is a Service, this grade applies to the core set of metadata. Capability and interface metadata, as well as the compliance of the service with the interface standard, is rated by validationLevel tag in the capability element (see the vr:Service complex type). \end{description} \item[Element \xmlel{title}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] the full name given to the resource \item[Occurrence] required \end{description} \item[Element \xmlel{shortName}] \begin{description} \item[Type] string \item[Meaning] A short name or abbreviation given to the resource. \item[Occurrence] optional \item[Comment] This name will be used where brief annotations for the resource name are required. Applications may use it to refer to this resource in a compact display. \item[Comment] One word or a few letters is recommended. No more than sixteen characters are allowed. \end{description} \item[Element \xmlel{identifier}] \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] Unambiguous reference to the resource conforming to the IVOA standard for identifiers \item[Occurrence] required \end{description} \item[Element \xmlel{altIdentifier}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A reference to this resource in a non-IVOA identifier scheme, e.g., DOI or bibcode. See the VOResource specification for syntax constraints on these identifiers. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{curation}] \begin{description} \item[Type] composite: \xmlel{vr:Curation} \item[Meaning] Information regarding the general curation of the resource \item[Occurrence] required \end{description} \item[Element \xmlel{content}] \begin{description} \item[Type] composite: \xmlel{vr:Content} \item[Meaning] Information regarding the general content of the resource \item[Occurrence] required \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Note that the :raw-latex:`\xmlel{vr:Resource}` attributes (:raw-latex:`\xmlel{created}`, :raw-latex:`\xmlel{updated}`, :raw-latex:`\xmlel{status}`) represent a special class of metadata: they describe the resource metadata contained within the :raw-latex:`\xmlel{vr:Resource}` itself as opposed to the resource being described. Also note that with OAI-PMH 2.0, VOResource records that would have a :raw-latex:`\xmlel{status}` of ``deleted`` should not occur since OAI-PMH mandates that :raw-latex:`\xmlel{oai:metadata}` is empty for deleted records, and VOResource’s :raw-latex:`\xmlel{status}` essentially is a refinement of OAI-PMH’s :raw-latex:`\xmlel{status}`. Having VOResource records with :raw-latex:`\xmlel{status}` set to ``deleted`` might still be useful outside of OAI-PMH. The :raw-latex:`\xmlel{version}` attribute of an :raw-latex:`\xmlel{vr:Resource}` element gives the version of the schema it was written against, as prescribed in the IVOA Note “XML Schema Versioning Policies” :cite:p:`2018ivoa.spec.0529H`. If missing, the value of this attribute can be assumed to be 1.0. This attribute should *not* be used to locate the schema file – clients should either consult :raw-latex:`\xmlel{schemaLocation}` or retrieve the latest schema for the :raw-latex:`\xmlel{vr:}` namespace from the IVOA schema repository. The following sections discuss the complex types mentioned in the above definitions. All rules and advice given in the “Comments” portions in the RM definition for the individual items apply. In some details, in particular as regards enumerations of values, this document deviates from RM in content. .. _`VOResource:identity-metadata`: 3.1.1 Identity Metadata ~~~~~~~~~~~~~~~~~~~~~~~ The identity metadata described in the RM (section 3.1) are represented as top-level children of the :raw-latex:`\xmlel{vr:Resource}` type. Two special types, :raw-latex:`\xmlel{vr:ShortName}` and :raw-latex:`\xmlel{vr:IdentifierURI}` are defined to support identity metadata. The :raw-latex:`\xmlel{vr:ShortName}` definition enforces the 16-character limit on shortNames. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ShortName} Type Schema Documentation} \noindent{\small A short name or abbreviation given to something. \par} \noindent{\small This name will be used where brief annotations for the resource name are required. Applications may use to refer to this resource in a compact display. \par} \noindent{\small One word or a few letters is recommended. No more than sixteen characters are allowed. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:ShortName} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:IdentifierURI} Type Schema Documentation} \noindent{\small A reference to a registry record. \par} \noindent{\small This type should only be used if what is referenced must actually be a true Registry record; vr:IdentifierURI does not allow query or fragment parts and is hence not suitable for everything defined by IVOA Identifiers, in particular not standard keys (which are used for versions of standards, for instance) or dataset identifiers. When something does not need to be locked down to a reference to a single registry record, xs:anyURI should be used. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:IdentifierURI} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} .. _`VOResource:curation-metadata`: 3.1.2 Curation Metadata ~~~~~~~~~~~~~~~~~~~~~~~ The curation metadata described in the RM (section 3.2) are bundled together into the :raw-latex:`\xmlel{vr:Resource}` child element :raw-latex:`\xmlel{curation}`. Its content is defined by the :raw-latex:`\xmlel{vr:Curation}` complex type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Curation} Type Schema Documentation} \noindent{\small Information regarding the general curation of a resource \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Curation} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Curation} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{publisher}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] Entity (e.g. person or organisation) responsible for making the resource available \item[Occurrence] required \end{description} \item[Element \xmlel{creator}] \begin{description} \item[Type] composite: \xmlel{vr:Creator} \item[Meaning] The entity/ies (e.g. person(s) or organisation) primarily responsible for creating the content or constitution of the resource. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This is the equivalent of the author of a publication. \end{description} \item[Element \xmlel{contributor}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] Entity responsible for contributions to the content of the resource \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{date}] \begin{description} \item[Type] \xmlel{vr:UTCDateTime} with optional attributes \item[Meaning] Date associated with an event in the life cycle of the resource. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This will typically be associated with the creation or availability (i.e., most recent release or version) of the resource. Use the role attribute to clarify. \end{description} \item[Element \xmlel{version}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] Label associated with creation or availablilty of a version of a resource. \item[Occurrence] optional \end{description} \item[Element \xmlel{contact}] \begin{description} \item[Type] composite: \xmlel{vr:Contact} \item[Meaning] Information that can be used for contacting someone with regard to this resource. \item[Occurrence] required; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:resource-names`: Resource Names ^^^^^^^^^^^^^^ Several of the curation elements (most importantly, :raw-latex:`\xmlel{publisher}` and :raw-latex:`\xmlel{relatedResource}`) make use of the :raw-latex:`\xmlel{vr:ResourceName}` type. This type provides a means of referring to another resource, by name, by its IVOA identifier, or by some other identifier scheme. Not all resources referred to using this type will necessarily be registered and, therefore, will have an IVOA identifier; thus, the identifier (which is encoded as an attribute) is optional. For entities registered in some other way – in particular, DOIs or ORCIDs –, resource names can give :raw-latex:`\xmlel{altIdentifier}`-s. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ResourceName} Type Schema Documentation} \noindent{\small The name of a potentially registered resource. That is, the entity referred to may have an associated identifier. Resources not registered in the VO Registry can be referenced using the altIdentifier attribute. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:ResourceName} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:ResourceName} Attributes} \begingroup\small\begin{bigdescription} \item[ivo-id] \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] The IVOA identifier for the resource referred to. \item[Occurrence] optional \end{description} \item[altIdentifier] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A non-ivoid identifier for the resource referred to, in particular a DOI. See the VOResource specification for syntax constraints on these identifiers. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:the-creator-type`: The Creator Type ^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{creator}` element is defined by the :raw-latex:`\xmlel{vr:Creator}` complex type which bundles together the RM metadata *Creator* and *Creator.Logo*. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Creator} Type Schema Documentation} \noindent{\small The entity (e.g. person or organisation) primarily responsible for creating something \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Creator} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Creator} Attributes} \begingroup\small\begin{bigdescription} \item[ivo-id] \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] Deprecated. Use the ivo-id attribute of the name child instead. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Creator} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] A name of a person or organisation that created the resource's (data) content. \item[Occurrence] required \item[Comment] In citations or acknowledgements, creator names are intended to be used in the author field. Each creator should contain exactly one name, preferably last name first (as in “van der Waals, Johannes Diderik”). Use multiple creator elements for resources created by multiple entities. \end{description} \item[Element \xmlel{logo}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] URL pointing to a graphical logo, which may be used to help identify the information source \item[Occurrence] optional \item[Comment] A logo needs only be provided for the first occurrence. When multiple logos are supplied via multiple creator elements, the application is free to choose which to use. \end{description} \item[Element \xmlel{altIdentifier}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] Deprecated as a child element. Use the name attribute's altIdentifier attribute instead. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The :raw-latex:`\xmlel{Creator}`’s :raw-latex:`\xmlel{name}` should contain exactly one name. Since the creator name is what Registry users use when searching for resources “by author”, it should be set with care. To make sensible collation simple for clients, person names should be formatted last name first wherever appropriate. In collaborative efforts, multiple creator elements should be used, one element per person or organisation involved. Examples for encouraged use of creator include: .. code:: xml van der Waals, Johannes Diderik de Vaucouleurs, G. Zhang Hailong IVOA Registry Working Group While the following uses of creator do not make a resource record technically invalid, they are frowned upon: .. code:: xml Mornilov, V.G., Polkov, I.M., Bakharov, A.I PI: Ita Varajedini All data is downloaded from the <a href=http:... In VOResource 1.1 the :raw-latex:`\xmlel{creator}` and :raw-latex:`\xmlel{contact}` elements received :raw-latex:`\xmlel{altIdentifier}` child elements, mainly to enable inclusion of ORCIDs in VOResource documents. In VOResource version 1.2, the :raw-latex:`\xmlel{vr:ResourceName}` type received an :raw-latex:`\xmlel{altIdentifier}` attribute, and hence an alternate identifier like an ORCID can be communicated through the :raw-latex:`\xmlel{name}` children of :raw-latex:`\xmlel{creator}` and :raw-latex:`\xmlel{contact}`. We hence deprecate the :raw-latex:`\xmlel{altIdentifier}` children in these two elements (but not in :raw-latex:`\xmlel{Resource}` itself). New resource records must use the :raw-latex:`\xmlel{name/@altIdentifier}` attributes to communicate ORCIDs or similar identifiers for persons. .. _`VOResource:dates-and-their-roles`: Dates and Their Roles ^^^^^^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{Date}` element’s type, :raw-latex:`\xmlel{vr:Date}`, is an extension of the :raw-latex:`\xmlel{UTCDateTime}` type that adds an optional attribute called :raw-latex:`\xmlel{role}`. The purpose of the role attribute is to indicate what aspect of the resource the date describes. This allows several :raw-latex:`\xmlel{date}` elements to be provided, each with a different role. The possible values for this attribute are not controlled by the schema. The IVOA, however, defines an RDF vocabulary at http://www.ivoa.net/rdf/voresource/date_role from which the :raw-latex:`\xmlel{role}` terms should be taken if at all possible. At the time of writing, the vocabulary consists of three old-style VOResource 1.0 terms and terms from the DataCite Metadata 4.6 :cite:p:`std:DataCite46`; see the RDF URL for the definitions of the terms. The following identifiers are available at the time of writing (omitting deprecated ones): :raw-latex:`\noindent` *Accepted*, *Available*, *Collected*, *Copyrighted*, *Created*, *ExportRequested*, *Inspected*, *Issued*, *Submitted*, *Updated*, *Valid* Terms can be added to this vocabulary without changes to this specification. Applications are not expected to support semantic relationships between the terms (except for mapping the deprecated VOResource 1.0 terms to the modern DataCite Metadata ones). .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:Date} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Date} Attributes} \begingroup\small\begin{bigdescription} \item[role] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] A string indicating what the date refers to. \item[Occurrence] optional \item[Default] Collected \item[Comment] The value of role should be taken from the vocabulary maintained at \url{http://www.ivoa.net/rdf/voresource/date_role}. This includes the traditional and deprecated strings “creation”, indicating the date that the resource itself was created, and “update”, indicating when the resource was updated last, and the default value, “Collected”, meaning the date is a rough representation of the time coverage of the resource (prefer coverage/temporal to convey this information). The preferred terms from that vocabulary are the DataCite Metadata terms. It is expected that the vocabulary will be kept synchronous with the corresponding list of terms in the DataCite Metadata schema. \item[Comment] Note that this date refers to the resource; dates describing the metadata description of the resource are handled by the “created” and “updated” attributes of the Resource element. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:the-contact-type`: The Contact Type ^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{contact}` element is defined by the :raw-latex:`\xmlel{vr:Contact}` type which bundles together several component pieces of information, including the RM metadata *Contact.Name* and *Contact.Email*. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Contact} Type Schema Documentation} \noindent{\small Information allowing establishing contact, e.g., for purposes of support. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Contact} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Contact} Attributes} \begingroup\small\begin{bigdescription} \item[ivo-id] \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] Deprecated. Use the ivo-id attribute of the name child instead. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Contact} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] the name or title of the contact person. \item[Occurrence] required \item[Comment] This can be a person's name, e.g. “John P. Jones” or a group, “Archive Support Team”. \end{description} \item[Element \xmlel{address}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] the contact mailing address \item[Occurrence] optional \item[Comment] All components of the mailing address are given in one string, e.g. “3700 San Martin Drive, Baltimore, MD 21218 USA”. \end{description} \item[Element \xmlel{email}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] the contact email address \item[Occurrence] optional \end{description} \item[Element \xmlel{telephone}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] the contact telephone number \item[Occurrence] optional \item[Comment] Complete international dialing codes should be given, e.g. “+1-410-338-1234”. \end{description} \item[Element \xmlel{altIdentifier}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] Deprecated as a child element. Use the name attribute's altIdentifier attribute instead. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:general-content-metadata`: 3.1.3 General Content Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The general content metadata described in the RM (section 3.3) are bundled together into the :raw-latex:`\xmlel{vr:Resource}` child element :raw-latex:`\xmlel{content}`. Its content is defined by the :raw-latex:`\xmlel{vr:Content}` complex type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Content} Type Schema Documentation} \noindent{\small Information regarding the general content of a resource \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Content} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Content} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{subject}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] a topic, object type, or other descriptive keywords about the resource. \item[Occurrence] required; multiple occurrences allowed. \item[Comment] The content of subject SHOULD be the fragment identifier of the URI of a concept in the IVOA UAT (\url{http://www.ivoa.net/rdf/uat/}), that is, a string like “virtual-observatories”. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] An account of the nature of the resource \item[Occurrence] required \item[Comment] The description may include but is not limited to an abstract, table of contents, reference to a graphical representation of content or a free-text account of the content. Note that description is xs:string-typed, which means that whitespace is considered significant. Clients should render empty lines as paragraph boundaries and ideally refrain from reflowing material that looks formatted (i.e., is broken to about 80-character lines). \end{description} \item[Element \xmlel{source}] \begin{description} \item[Type] a string with optional attributes \item[Meaning] a bibliographic reference from which the present resource is derived or extracted. \item[Occurrence] optional \item[Comment] This is intended to point to an article in the published literature. An ADS Bibcode is recommended as a value when available. \end{description} \item[Element \xmlel{referenceURL}] \begin{description} \item[Type] string \item[Meaning] URL pointing to a human-readable document describing this resource. \item[Occurrence] required \item[Comment] In order to ensure that users can actually retrieve the content, the schema enforces that this is an http or https URI. \end{description} \item[Element \xmlel{type}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] Nature or genre of the content of the resource. Values for type should be taken from the controlled vocabulary \url{http://www.ivoa.net/rdf/voresource/content_type} \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{contentLevel}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] Description of the content level or intended audience. Values for contentLevel should be taken from the controlled vocabulary \url{http://www.ivoa.net/rdf/voresource/content_level}. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{relationship}] \begin{description} \item[Type] composite: \xmlel{vr:Relationship} \item[Meaning] a description of a relationship to another resource. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The content of :raw-latex:`\xmlel{subject}` should be drawn from the Unified Astronomy Thesaurus (UAT), the concepts of which are identified through human-readable fragments given in the IVOA-flavoured UAT at http://www.ivoa.net/rdf/uat. The details and the rationale of the IVOA’s use of the UAT are discussed in :cite:t:`2022ivoa.spec.0722D`. The content of :raw-latex:`\xmlel{contentLevel}` should conform to the values from a vocabulary. At the time of writing, this vocabulary contained the terms: :raw-latex:`\noindent` *Amateur*, *General*, *Research* For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/content_level. The content of :raw-latex:`\xmlel{type}` should conform to the values from a vocabulary. At the time of writing, this vocabulary contained the terms: :raw-latex:`\noindent` *Animation*, *Archive*, *Artwork*, *Background*, *BasicData*, *Bibliography*, *Catalog*, *Education*, *EPOResource*, *Historical*, *Journal*, *Library*, *Organisation*, *Other*, *Outreach*, *Photographic*, *Press*, *Project*, *Registry*, *Simulation*, *Survey*, *Transformation* For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/content_type. The :raw-latex:`\xmlel{source}` element’s type, :raw-latex:`\xmlel{vr:Source}`, is an extension of the :raw-latex:`\xmlel{xs:token}` type that adds an optional attribute called :raw-latex:`\xmlel{format}`. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:Source} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Source} Attributes} \begingroup\small\begin{bigdescription} \item[format] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] The reference format. Recognized values include “bibcode”, referring to a standard astronomical bibcode (\url{http://cdsweb.u-strasbg.fr/simbad/refcode.html}), and “doi” for a Digital Object Identifier \item[Occurrence] optional \item[Comment] Since format already defines how to interpret source's values, these do not uses any prefixes, HTTP or otherwise. A resource would declare VOResource 1.1 as its source by writing 2018ivoa.spec.0625P with the bibcode format, and writing 10.5479/ADS/bib/2018ivoa.spec.0625P with the doi format. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The :raw-latex:`\xmlel{relationship}` is defined by the :raw-latex:`\xmlel{vr:Relationship}` complex type which bundles together the RM metadata *Relationship* and *RelationshipID*. The nature of the relationship is given by relationshipType. The values of this are taken from a vocabulary that is available in RDF form at http://www.ivoa.net/rdf/voresource/relationship_type. This vocabulary at the time of writing consists of - the terms from VOResource 1.0 (mirror-of, service-for, served-by, derived-from, and related-to); these are guaranteed to remain within VOResource 1.x - selected terms from the DataCite Metadata relationType enumeration. The resulting mix of term styles is an aesthetic defect that may actually lead to the construction of invalid terms. While, for backward compatibility, we will not drop the VOResource 1.0 terms in VOResource 1.x, they should not be used in new records. Instead, resource records should use the terms given as *Preferred* in the vocabulary retrievable at the URL given above. At the time of writing, the full vocabulary consists of these terms (omitting deprecated ones): :raw-latex:`\noindent` *Cites*, *Continues*, *HasPart*, *IsContinuedBy*, *IsDerivedFrom*, *IsIdenticalTo*, *IsNewVersionOf*, *IsPartOf*, *IsPreviousVersionOf*, *IsServedBy*, *IsServiceFor*, *IsSourceOf*, *IsSupplementedBy*, *IsSupplementTo* For definitions of these terms, their relationships, and the complete, up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to http://www.ivoa.net/rdf/voresource/relationship_type. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Relationship} Type Schema Documentation} \noindent{\small A description of the relationship between one resource and one or more other resources. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Relationship} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Relationship} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{relationshipType}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] the named type of relationship \item[Occurrence] required \item[Comment] The value of relationshipType should be taken from the vocabulary at \url{http://www.ivoa.net/rdf/voresource/relationship_type}. \end{description} \item[Element \xmlel{relatedResource}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] the name of resource that this resource is related to. \item[Occurrence] required; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:resource-record-quality-with-validationlevel`: 3.1.4 Resource Record Quality with validationLevel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The RM’s *ResourceValidationLevel* is encoded in the VOResource schema with the :raw-latex:`\xmlel{validationLevel}` element, which can appear in multiple places within a :raw-latex:`\xmlel{vr:Re\-source}` type or sub-type. It may appear zero or more times as direct children of a :raw-latex:`\xmlel{vr:Resource}` type and/or, if the resource is a :raw-latex:`\xmlel{vr:Service}` type or sub-type, zero or more times as the first children of any :raw-latex:`\xmlel{capability}` element. .. raw:: latex \begin{admonition}{Note} \xmlel{validationLevel} is of type \xmlel{vr:Validation}; somewhat confusingly, VOResource also has a type \xmlel{vr:ValidationLevel}. The latter is extended by \xmlel{vr:Validation} with a \xmlel{validatedBy} attribute. The choice of names in this triple certainly is somewhat confusing and can be considered an editorial oversight in version 1.0. However, the effort of changing element and/or type names would seem unproportional to the merely aesthetic benefit in a part of VOResource that is rarely visible to common VO users. \end{admonition} The :raw-latex:`\xmlel{validationLevel}` element’s attribute :raw-latex:`\xmlel{validatedBy}` takes an IVOID as a value. This IVOID must refer to a registered organisation or registry that assigned the numerical value. The :raw-latex:`\xmlel{validationlevel}` element can appear multiple times, each with a different :raw-latex:`\xmlel{validatedBy}` value, to reflect the code assigned by different organisations. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Validation} Type Schema Documentation} \noindent{\small a validation stamp combining a validation level and the ID of the validator. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Validation} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Validation} Attributes} \begingroup\small\begin{bigdescription} \item[validatedBy] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] The IVOA ID of the registry or organisation that assigned the validation level. \item[Occurrence] required \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Schema Documentation} \noindent{\small The allowed values for describing the resource descriptions and interfaces. \par} \noindent{\small See the RM (v1.1, section 4) for more guidance on the use of these values. \par} \vspace{2ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Allowed Values} \begin{longtermsdescription}\item[0] The resource has a description that is stored in a registry. This level does not imply a compliant description. \item[1] In addition to meeting the level 0 definition, the resource description conforms syntactically to this standard and to the encoding scheme used. \item[2] In addition to meeting the level 1 definition, the resource description refers to an existing resource that has demonstrated to be functionally compliant. \item[3] In addition to meeting the level 2 definition, the resource description has been inspected by a human and judged to comply semantically to this standard as well as meeting any additional minimum quality criteria (e.g., providing values for important but non-required metadata) set by the human inspector. \item[4] In addition to meeting the level 3 definition, the resource description meets additional quality criteria set by the human inspector and is therefore considered an excellent description of the resource. Consequently, the resource is expected to operate well as part of a VO application or research study. \end{longtermsdescription} \vspace{1ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} .. _`VOResource:resource-type-extensions-organisation-and-service`: 3.2 Resource Type Extensions: Organisation and Service ------------------------------------------------------ The VOResource schema defines two extensions of the base :raw-latex:`\xmlel{vr:Resource}` type for describing two specific types of resources: :raw-latex:`\xmlel{vr:Organisation}` and :raw-latex:`\xmlel{vr:Service}`. In addition to providing more refined semantic meanings over :raw-latex:`\xmlel{vr:Resource}`, they add additional metadata for describing the resource which do not necessarily apply in the generic case. .. _`VOResource:the-organisation-resource-type`: 3.2.1 The Organisation Resource Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vr:Organisation}` resource type is used to describe an organisation in the sense defined by the RM: An organisation is a specific type of resource that brings people together to pursue participation in VO applications. Organisations can be hierarchical and range greatly in size and scope. At a high level, an organisation could be a university, observatory, or government agency. At a finer level, it could be a specific scientific project space mission, or individual researcher. The Organisation type extends the Resource type by adding two additional elements to the core set of metadata, :raw-latex:`\xmlel{facility}` and :raw-latex:`\xmlel{instrument}`: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Organisation} Type Schema Documentation} \noindent{\small A named group of one or more persons brought together to pursue participation in VO applications. \par} \noindent{\small According to the Resource Metadata Recommendation, organisations “can be hierarchical and range in size and scope. At a high level, an organisation could be a university, observatory, or government agency. At a finer level, it could be a specific scientific project, mission, or individual researcher.” \par} \noindent{\small The main purpose of an organisation as a registered resource is to serve as a publisher of other resources. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Organisation} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Organisation} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{facility}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] the observatory or facility used to collect the data contained or managed by this resource. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{instrument}] \begin{description} \item[Type] string with ID attribute: vr:ResourceName \item[Meaning] the Instrument used to collect the data contain or managed by a resource. \item[Occurrence] optional; multiple occurrences allowed. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The main role of an organisation in the VO (that is, the main reason for describing organisations in a registry) is as a provider or publisher of other resources. In particular, an organisation description in a registry declares the association of an IVOA identifier with the organisation. The organisation can then be referred to in other resource descriptions. For example, an organisation identifier will appear as the publisher identifier of service resource (as illustrated in the opening example in sect. :ref:`VOResource:sect:model`). .. _`VOResource:the-service-resource-type`: 3.2.2 The Service Resource Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :raw-latex:`\xmlel{vr:Service}` resource type is used to describe a service–a resource that actually does something – in the sense defined by the RM: :raw-latex:`\noindent `A service is any VO resource that can be invoked by the user to perform some action on their behalf. The general data model is described in sect. :ref:`VOResource:sect:servicemodel`. The Service type extends the Resource type by adding two elements: :raw-latex:`\xmlel{rights}` which indicates the modalities of service use and access, and :raw-latex:`\xmlel{capability}` which describes how the service behaves and how it is invoked. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Service} Type Schema Documentation} \noindent{\small a resource that can be invoked by a client to perform some action on its behalf. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Service} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Service} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{rights}] \begin{description} \item[Type] a string with optional attributes \item[Meaning] Information about rights held in and over the resource. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] Mainly for compatibility with DataCite, this element is repeatable. Resource record authors are advised that within the Virtual Observatory clients will typically only display and/or use the rights element occurring first and ignore later elements. \end{description} \item[Element \xmlel{capability}] \begin{description} \item[Type] composite: \xmlel{vr:Capability} \item[Meaning] a description of a general capability of the service and how to use it. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This describes a general function of the service, usually in terms of a standard service protocol (e.g. SIA), but not necessarily so. \item[Comment] A service can have many capabilities associated with it, each reflecting different aspects of the functionality it provides. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:declaration-of-copyrights-usage-limitations-and-licenses`: Declaration of copyrights, usage limitations, and licenses ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{rights}` element contains free text, where it is recommended that standard licenses are named and special circumstances like embargoes are mentioned. The :raw-latex:`\xmlel{rightsURI}` attribute can be used to reference the full license text. In order to facilitate automatic identification of usage conditions, it is strongly recommended to use the license URIs [6]_ maintained by the System Package Data Exchange SPDX. While the schema allows multiple :raw-latex:`\xmlel{rights}` elements and thus multiple license URIs, within the VO such use is discouraged. This means that clients that discard information from additional :raw-latex:`\xmlel{rights}` elements are not considered to be in violation of this specifiation. In practice, resource record authors should place all usage limitations, citation recommendations, etc., directed at VO users in the first :raw-latex:`\xmlel{rights}` element. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Rights} Type Schema Documentation} \noindent{\small A statement of usage conditions. This will typically include a license, which should be given as a full string (e.g., Creative Commons Attribution 3.0 International). Further free-text information, e.g., on how to attribute or on embargo periods is allowed. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Rights} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Rights} Attributes} \begingroup\small\begin{bigdescription} \item[rightsURI] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A URI identifier for a license \item[Occurrence] optional \item[Comment] Where formal licenses are available, this URI can reference the full license text. Use SPDX license URIs (\url{https://spdx.org/licenses/}) if at all possible. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} An example could look like this: .. code:: xml The images from the X survey are copyright 2016, the X project. They are published under the creative commons attribution 4.0 international license. If you use this data, please cite doi:10.5072/7273288. Images are under embargo for one year after their addition to the repository. .. _`VOResource:service-capabilities`: Service capabilities ^^^^^^^^^^^^^^^^^^^^ As described in sect. :ref:`VOResource:sect:servicemodel`, multiple :raw-latex:`\xmlel{capability}` elements may appear, each describing a different capability of the service. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Capability} Type Schema Documentation} \noindent{\small a description of what the service does (in terms of context-specific behavior), and how to use it (in terms of an interface) \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Capability} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Capability} Attributes} \begingroup\small\begin{bigdescription} \item[standardID] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A URI identifier for a standard service. \item[Occurrence] optional \item[Comment] This provides a unique way to refer to a service specification standard, such as a Simple Image Access service. The use of an IVOA identifier here implies that a VOResource description of the standard is registered and accessible. \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Capability} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{validationLevel}] \begin{description} \item[Type] \xmlel{vr:ValidationLevel} with optional attributes \item[Meaning] A numeric grade describing the quality of the capability description and interface, when applicable, to be used to indicate the confidence an end-user can put in the resource as part of a VO application or research study. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] See vr:ValidationLevel for an explanation of the allowed levels. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] A human-readable description of what this capability provides as part of the over-all service \item[Occurrence] optional \item[Comment] Use of this optional element is especially encouraged when this capability is non-standard and is one of several capabilities listed. \end{description} \item[Element \xmlel{interface}] \begin{description} \item[Type] composite: \xmlel{vr:Interface} \item[Meaning] a description of how to call the service to access this capability \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] Since the Interface type is abstract, one must describe the interface using a subclass of Interface, denoting it via xsi:type. \item[Comment] Multiple occurences can describe different interfaces to the logically same capability, i.e. data or functionality. That is, the inputs accepted and the output provides should be logically the same. For example, a WebBrowser interface given in addition to a WebService interface would simply provide an interactive, human-targeted interface to the underlying WebService interface. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} The :raw-latex:`\xmlel{capability}` element is sufficient for describing a *custom service capability*, i.e., a service that is particular to one provider and does not conform to a specific standard (be it recognized by the IVOA or some other sub-community). However, service standards will often create a :raw-latex:`\xmlel{vr:Capability}` extension that adds additional metadata that are specific to the behavior of that particular type of service. .. raw:: latex \begin{admonition}{Note} The RM defines three pieces of metadata that may be important for several standard query services: \emph{Service.MaxSearchRadius}, \emph{Service.MaxReturnRecords}, and \emph{Service.MaxReturnSize}. These are examples of service-specific metadata that should be encoded as child elements in a type derived from \xmlel{vr:Capability}. \end{admonition} .. _`VOResource:more-on-interfaces`: More on interfaces ^^^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{interface}` element is of the complex type :raw-latex:`\xmlel{vr:Interface}`; its usage, in particular as regards the mandatory use of its :raw-latex:`\xmlel{xsi:type}` attribute and typical values thereof, is discussed sect. :ref:`VOResource:sect:servicemodel`. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Interface} Type Schema Documentation} \noindent{\small A description of a service interface. \par} \noindent{\small Since this type is abstract, one must use an Interface subclass to describe an actual interface. \par} \noindent{\small Additional interface subtypes (beyond WebService and WebBrowser) are defined in the VODataService schema. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:Interface} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Interface} Attributes} \begingroup\small\begin{bigdescription} \item[version] \begin{description} \item[Type] string: \xmlel{xs:string} \item[Meaning] The version of a standard interface specification that this interface complies with. Most VO standards indicate the version in the standardID attribute of the capability. For these standards, the version attribute should not be used. \item[Occurrence] optional \end{description} \item[role] \begin{description} \item[Type] \xmlel{xs:NMTOKEN} \item[Meaning] A tag name that identifies the role the interface plays in the particular capability. If the value is equal to {"}std{"} or begins with {"}std:{"}, then the interface refers to a standard interface defined by the standard referred to by the capability's standardID attribute. \item[Occurrence] optional \item[Comment] For an interface complying with some registered standard (i.e. has a legal standardID), the role can be matched against interface roles enumerated in standard resource record. The interface descriptions in the standard record can provide default descriptions so that such details need not be repeated here. \end{description} \end{bigdescription}\endgroup \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Interface} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{accessURL}] \begin{description} \item[Type] a URI with optional attributes \item[Meaning] The URL (or base URL) that a client uses to access the service. How this URL is to be interpreted and used depends on the specific Interface subclass \item[Occurrence] required; multiple occurrences allowed. \item[Comment] Although the schema allows multiple occurrences of accessURL, multiple accessURLs are deprecated. Each interface should have exactly one access URL. Where an interface has several mirrors, the accessURL should reflect the “primary” (fastest, best-connected, best-maintained) site, the one that non-sophisticated clients will go to. Additional accessURLs should be put into mirrorURLs. Advanced clients can retrieve the mirrorURLs and empirically determine interfaces closer to their network location. \end{description} \item[Element \xmlel{mirrorURL}] \begin{description} \item[Type] a URI with optional attributes \item[Meaning] A (base) URL of a mirror of this interface. As with accessURL, how this URL is to be interpreted and used depends on the specific Interface subclass \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] This is intended exclusively for true mirrors, i.e., interfaces that are functionally identical to the original interface and that are operated by the same publisher. Other arrangements should be represented as separate services linked by mirror-of relationships. \end{description} \item[Element \xmlel{securityMethod}] \begin{description} \item[Type] composite: \xmlel{vr:SecurityMethod} \item[Meaning] The mechanism the client must employ to authenticate to the service. \item[Occurrence] optional \item[Comment] Services not requiring authentication must provide at least one interface definition without a securityMethod defined. \end{description} \item[Element \xmlel{testQueryString}] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] Test data for exercising the service. \item[Occurrence] optional \item[Comment] This contains data that can be passed to the interface to retrieve a non-empty result. This can be used by validators within test suites. Exactly how agents should use the data contained in the testQueryString depends on the concrete interface class. For interfaces employing the HTTP GET method, however, this will typically be urlencoded parameters (as for the application/x-www-form-urlencoded media type). \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} Exactly how a client uses the value of the :raw-latex:`\xmlel{accessURL}` element depends on the specific type derived from :raw-latex:`\xmlel{vr:Interface}`. Extension schemas that define non-abstract types derived from :raw-latex:`\xmlel{vr:Interface}` MUST provide documentation that explains the exact use of the :raw-latex:`\xmlel{accessURL}`; this documentation should follow the documention conventions described in sect. :ref:`VOResource:sect:core`. In version 1.0, operators of services with multiple mirrors were encouraged to give multiple :raw-latex:`\xmlel{accessURL}` elements. This feature was not used in practice, presumably for concerns users might end up on remote mirrors. Since version 1.1, we therefore deprecate multiple :raw-latex:`\xmlel{accessURL}` within an interface. Access URLs of actual mirrors can now be declared using :raw-latex:`\xmlel{mirrorURL}` elements. As before, neither :raw-latex:`\xmlel{accessURL}` nor :raw-latex:`\xmlel{mirrorURL}` must not point to an installation that is outside the administrative control of the service’s listed publisher; such a mirror should be described in a separate resource record. To aid in user interfaces for mirror selection, :raw-latex:`\xmlel{mirrorURL}` admits a :raw-latex:`\xmlel{title}` attribute: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:MirrorURL} Type Schema Documentation} \noindent{\small A URL of a mirror (i.e., a functionally identical additional service interface) to \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:MirrorURL} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:MirrorURL} Attributes} \begingroup\small\begin{bigdescription} \item[title] \begin{description} \item[Type] string: \xmlel{xs:token} \item[Meaning] A terse, human-readable phrase indicating the function or location of this mirror, e.g., “Primary Backup” or “European Mirror”. \item[Occurrence] optional \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:declaring-access-restrictions`: Declaring access restrictions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{vr:SecurityMethod}` type is defined as a complex type but with empty content: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Type Schema Documentation} \noindent{\small a description of a security mechanism. \par} \noindent{\small This type only allows one to refer to the mechanism via a URI. Derived types would allow for more metadata. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Attributes} \begingroup\small\begin{bigdescription} \item[standardID] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] A URI identifier for a standard security mechanism. \item[Occurrence] optional \item[Comment] This provides a unique way to refer to a security specification standard. The use of an IVOA identifier here implies that a VOResource description of the standard is registered and accessible. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} While this simple element (when the :raw-latex:`\xmlel{standardID}` attribute is provided) may on its own be sufficient to describe the security mechanism used, it is expected that some future VOResource extension schema will define additional types derived from :raw-latex:`\xmlel{vr:SecurityMethod}`. If such a sub-type is available, it may be employed at :raw-latex:`\xmlel{securityMethod}` location within a :raw-latex:`\xmlel{vr:Interface}`-typed element, in which case it should be invoked via a :raw-latex:`\xmlel{xsi:type}` attribute to the :raw-latex:`\xmlel{securityMethod}` element. .. _`VOResource:web-browser-interfaces`: Web browser interfaces ^^^^^^^^^^^^^^^^^^^^^^ :raw-latex:`\xmlel{vr:WebBrowser}` is one of the two :raw-latex:`\xmlel{vr:Interface}` sub-types defined by the VOResource schema. This type indicates that the service is intended to be accessed interactively by a user through a web browser. The :raw-latex:`\xmlel{accessURL}`, then, represents the URL of a web page containing one or more forms used to invoke the service. .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:WebBrowser} Type Schema Documentation} \noindent{\small A (form-based) interface intended to be accesed interactively by a user via a web browser. \par} \noindent{\small The accessURL represents the URL of the web form itself. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:WebBrowser} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting}\endgroup \end{generated} As can be seen in the schema definition above, the :raw-latex:`\xmlel{vr:WebBrowser}` type does not define any additional interface metadata (though other :raw-latex:`\xmlel{vr:Interface}` derivations may). Thus, this type is provided purely for its semantic meaning. :raw-latex:`\xmlel{vr:WebService}` is the second :raw-latex:`\xmlel{vr:Interface}` sub-type available from the VOResource schema: .. raw:: latex \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:WebService} Type Schema Documentation} \noindent{\small A Web Service that is describable by a WSDL document. \par} \noindent{\small The accessURL element gives the Web Service's endpoint URL. \par} \vspace{1ex}\noindent\textbf{\xmlel{vr:WebService} Type Schema Definition} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] \end{lstlisting} \vspace{0.5ex}\noindent\textbf{\xmlel{vr:WebService} Extension Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{wsdlURL}] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} \item[Meaning] The location of the WSDL that describes this Web Service. If not provided, the location is assumed to be the accessURL with {"}?wsdl{"} appended. \item[Occurrence] optional; multiple occurrences allowed. \item[Comment] Multiple occurrences should represent mirror copies of the same WSDL file. \end{description} \end{bigdescription}\endgroup \endgroup \end{generated} .. _`VOResource:legacy-web-service-interfaces`: Legacy web service interfaces ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :raw-latex:`\xmlel{vr:WebService}` interface is one that is described by a Web Service Description Language :cite:p:`booth07` document. This is typically realized as one that employs the Simple Object Access Protocol :cite:p:`std:SOAP`; however, like WSDL, this interface type is not restricted to it. With this interface, the :raw-latex:`\xmlel{vr:accessURL}` must refer to the service endpoint URL. Note that :raw-latex:`\xmlel{vr:WebService}` must *not* be used when no WSDL for the service is available. This is true for all modern VO standard services. It is thus unlikely that modern services will use this interface. See sect. :ref:`VOResource:sect:servicemodel` for details. Appendices ========== .. _`VOResource:change-history`: A Change History ================ .. _`VOResource:changes-from-rec-1.3`: A.1 Changes from REC-1.3 ------------------------ - Deprecated the :raw-latex:`\xmlel{ivo-id}` attributes of :raw-latex:`\xmlel{Creator}` and :raw-latex:`\xmlel{Contact}`. .. _`VOResource:changes-from-pr-1.2`: A.2 Changes from PR-1.2 ----------------------- - Also listing ROR as a recognised identifier type. - Replacing “representative” as vr:Date/@role’s defaut with “Collected” as per the date_role vocabulary. This replacement has alreday been done by RegTAP services since VOResource 1.1. .. _`VOResource:changes-from-rec-1.1`: A.3 Changes from REC-1.1 ------------------------ - Adding an altIdentifier attribute to :raw-latex:`\xmlel{vr:ResourceName}` to let data providers use DOIs when declaring relationships. This also covers what :raw-latex:`\xmlel{role/@altIdentifi\-er}` and :raw-latex:`\xmlel{contact/@altIdentifier}` was created for. These special constructs introduced in version 1.1 are now deprecated again. - We now specify that “using the UAT” from version 1.1 means “use fragments into ``http://www.ivoa.net/rdf/uat/#``”. - Now strongly recommending to use SPDX URIs for rightsURI. - Adding *doi* as a recognised source format. - The schema now requires referenceURLs to have http or https URI schemes. .. _`VOResource:changes-from-pr-20171107`: A.4 Changes from PR-20171107 ---------------------------- - Editoral changes after DAL and Semantics RFC comments. .. _`VOResource:changes-from-pr-20170425`: A.5 Changes from PR-20170425 ---------------------------- - :raw-latex:`\xmlel{interface}` now only allows zero or one :raw-latex:`\xmlel{securityMethod}` elements (rather than zero to unlimited in version 1.0). This is to keep discovery patterns simple in the presence of services requiring authentication. While this is a **potentially incompatible change**, no actual records have ever used multiple security methods, and the change has been agreed upon with the stakeholders at the time of the change. - creator and contact can now have ivo-id attributes (analogous to publisher and contributor); these are intended for when the roles are filled by organizations. - @updated and @created on resource are now vr:UTCTimestamp rather than xs:datetime. There has always been a textual requirement that these are UTC. This is now enforced by the schema. - The schema example for an ORCID used a non-standard URI form. It is now deleted, and the text gives an example for an https URI. .. _`VOResource:changes-from-wd-20170123`: A.6 Changes from WD-20170123 ---------------------------- - Explanation for mismatch between namespace URI and actual version. - :raw-latex:`\xmlel{testQueryString}` has erroneously had multiplicity 0…n. It is now defined as 0…1. - Adopting DataCite 4.0 as upstream, explanation of the relationship between VOResource 1.0 and DataCite terms. - altIdentifier is now allowed on Contact now (mainly for symmetry with Creator). .. _`VOResource:changes-from-wd-20161010`: A.7 Changes from WD-20161010 ---------------------------- - Now recommending the Unified Astronomy Thesaurus instead of the old IAU Thesaurus. - date/role terms are now flat (rather than deprecated terms being specialisations of their successors). .. _`VOResource:changes-from-rec-1.03`: A.8 Changes from REC-1.03 ------------------------- - Adopting DataCite as another “upstream” in addtion to RM. - While we still reference RM, it is now no longer informally authoritative for VOResource (we’d have to change RM before we change VOResource otherwise) - References to the RM terms in the metadata definition dropped (could add support in ivoatex/schemadoc if we want them back). - Adding altIdentifier elements to creator and resource. - Adding a version attribute to vr:Resource for compliance with XML Schema Versioning Policies - The vocabulary of date/@role is now managed as a separate resource; DataCite terms have been added to it, and the old 1.0 terms deprecated. - The vocabulary of relationshipType is now managed as a separate resource; some DataCite terms have been added to it. - Service/rights now is free text rather than the tree-term enumeration. In addition, it now has a rightsURI attribute, DataCite-style. - content/type is now xs:token rather than a special restriction. The vocabulary is now managed as an external resource. Consequently, the vr:Type type vanishes from the XSD. - content/level is now xs:token rather than a special restriction. The vocabulary is now managed as an external resource. Consequently, the vr:ContentLevel type vanishes from the XSD. - New testQueryString and mirrorURL children of interface. - Now discouraging fixing standardID in VOResource extensions. Also, removed indication that capability/@xsi:type should be used for service discovery. - Now allowing a Z timezone marker in UTCTimestamp, indeed discouraging non-timezone use. This is in line with OAI-PMH use. Therefore, while technically changing the schema such that legacy clients might be confused, we do not expect incompatibilites. - resource/description and capability/description are now xs:string to enable simple plain text markup. - Adding language on using capability/@standardID rather than interface/@ver:raw-latex:`\-`sion to distinguish between different protocol versions in the normal case, removed skynode example. - Consequently, removing 1.0 default on interface/@version. - Added advice about the use of creator.name - Removed SOAP/WSDL example and a bit of the accompanying language. - Section 3 needed some refactoring since the schema documentation is now generated from the schema document. To accommodate this, some text manually embedded within the schema documentation had to be moved out of the generated material or removed. - Strongly advising the use of the vr: prefix, removing some duplicated advice regarding prefixes - Removed example for deriving a SIA capability (this is now in the document repository) - Ported document source to :raw-latex:`\ivoatex`. .. _`VOResource:changes-from-v1.02`: A.9 Changes from v1.02 ---------------------- - converted to Recommendation .. _`VOResource:changes-from-v1.01`: A.10 Changes from v1.01 ----------------------- - :raw-latex:`\xmlel{status}` attribute is now required. - added this Change History appendix. .. _`VOResource:changes-from-v1.0`: A.11 Changes from v1.0 ---------------------- - dropped :raw-latex:`\xmlel{PaddedString}`, :raw-latex:`\xmlel{PaddedURI}` and replaced with :raw-latex:`\xmlel{xs:token}`. - made :raw-latex:`\xmlel{Validation}`’s :raw-latex:`\xmlel{validatedBy}` attribute required. - reference citation correction for SOAP, WSDL .. [1] http://www.ivoa.net/xml .. [2] https://support.orcid.org/knowledgebase/articles/116780 .. [3] https://ror.org .. [4] Retrospectively, :raw-latex:`\xmlel{vs:ParamHTTP}` should probably have been part of VOResource itself; changing this now, however, does not seem to be worth the migration effort. .. [5] http://ivoa.net/documents; TAPRegExt or SimpleDALRegExt give starting points. The actual schema files are available from http://ivoa.net/xml. .. [6] https://spdx.org/licenses/ .. |image1| image:: role_diagram.pdf :width: 90.0%