diff --git a/Makefile b/Makefile index f0adb99..38b9bfb 100644 --- a/Makefile +++ b/Makefile @@ -4,13 +4,13 @@ DOCNAME = VOResource # count up; you probably do not want to bother with versions <1.0 -DOCVERSION = 1.2 +DOCVERSION = 1.3 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2025-04-16 +DOCDATE = 2025-10-31 # What is it you're writing: NOTE, WD, PR, or REC -DOCTYPE = REC +DOCTYPE = WD # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex @@ -35,7 +35,7 @@ ivoatex/Makefile: git submodule update --init STILTS ?= stilts -SCHEMA_FILE=VOResource-v1.2.xsd +SCHEMA_FILE=VOResource-v1.3.xsd # These tests need stilts >3.4 and xmlstarlet test: @@ -47,3 +47,6 @@ test: @$(STILTS) xsdvalidate \ schemaloc="http://www.ivoa.net/xml/VOResource/v1.0=$(SCHEMA_FILE)" \ test-data/valid-record.xml + @$(STILTS) xsdvalidate \ + schemaloc="http://www.ivoa.net/xml/VOResource/v1.0=$(SCHEMA_FILE)" \ + test-data/discontinued-record.xml diff --git a/VOResource-v1.2.xsd b/VOResource-v1.3.xsd similarity index 94% rename from VOResource-v1.2.xsd rename to VOResource-v1.3.xsd index 80edfd9..2c79f8d 100644 --- a/VOResource-v1.2.xsd +++ b/VOResource-v1.3.xsd @@ -6,10 +6,10 @@ xmlns:vm="http://www.ivoa.net/xml/VOMetadata/v0.1" elementFormDefault="unqualified" attributeFormDefault="unqualified" - version="1.2"> + version="1.3-wd1"> @@ -200,22 +200,31 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> - resource is believed to be currently maintained, and its - description is up to date (default). + The resource is available and maintained by the + publisher (default). - resource is apparently not being maintained at the present. + The resource is temporarily offline but is expected to + resume operations at some later date; publishers in this + case could publish an estimate when that will happen in a + date element with a role of Available. Note that inactive + resources do not show up in RegTAP searchable registries. - resource publisher has explicitly deleted the resource. + This status could be used for resources permanently + unavailable if VOResource metadata should still be + available via OAI-PMH; in the current VO, there is + probably no reason to ever do that, and deleted + records also do not show up in RegTAP searchable + registries. @@ -566,8 +575,8 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> maxOccurs="unbounded"> - Deprecated as a child element. Use the name - attribute's altIdentifier attribute instead. + Deprecated as a child element. Use the name + attribute's altIdentifier attribute instead. @@ -577,8 +586,8 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> - An IVOA identifier for the contact (typically when it is - an organization). + Deprecated. Use the ivo-id attribute of the name child + instead. @@ -628,8 +637,8 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> maxOccurs="unbounded"> - Deprecated as a child element. Use the name - attribute's altIdentifier attribute instead. + Deprecated as a child element. Use the name + attribute's altIdentifier attribute instead. @@ -639,8 +648,7 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> - An IVOA identifier for the creator (typically when it is - an organization). + Deprecated. Use the ivo-id attribute of the name child instead. @@ -656,10 +664,10 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> A string indicating what the date refers to. - The value of role should be taken from the vocabulary - maintained at - http://www.ivoa.net/rdf/voresource/date_role. - This includes the traditional and deprecated strings + The value of role should be taken from the vocabulary + maintained at + 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, @@ -701,10 +709,10 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> about the resource. - The content of subject SHOULD be the fragment identifier of - the URI of a concept in the IVOA UAT - (http://www.ivoa.net/rdf/uat/), that is, a string like - “virtual-observatories”. + The content of subject SHOULD be the fragment identifier of + the URI of a concept in the IVOA UAT + (http://www.ivoa.net/rdf/uat/), that is, a string like + “virtual-observatories”. @@ -755,9 +763,9 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> resource. - In order to ensure that users can actually retrieve the - content, the schema enforces that this is an http or https - URI. + In order to ensure that users can actually retrieve the + content, the schema enforces that this is an http or https + URI. @@ -822,12 +830,12 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> “doi” for a Digital Object Identifier - 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. + 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. @@ -868,6 +876,30 @@ For details, see http://ivoa.net/documents/Notes/XMLVers --> + + + + + A resource no longer available but continued by some other + resource. + + + The main purpose of registering a discontinued resource is + so users still find pertinent metadata, in particular an + IsContinuedBy relationship. Hence, DiscontinuedResource + records SHOULD set at least one of those. + + Obviously, DiscontinuedResources cannot have capabilities. + + + + + + + + diff --git a/VOResource.tex b/VOResource.tex index 8e8f75c..98e7dda 100644 --- a/VOResource.tex +++ b/VOResource.tex @@ -31,6 +31,7 @@ \editor{Markus Demleitner} +\previousversion[https://www.ivoa.net/documents/VOResource/20250416]{REC-1.2} \previousversion[https://www.ivoa.net/documents/VOResource/20241015]{PR-1.2-20241015} \previousversion[https://ivoa.net/documents/VOResource/20230105/]{WD-1.2-20230105} \previousversion[https://ivoa.net/documents/VOResource/20180625/]{REC-1.1} @@ -271,7 +272,7 @@ \subsection{The Schema Namespace and Location} 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.2 now, the URL still ends in +Although this schema is in version 1.3 now, the URL still ends in \texttt{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 @@ -282,8 +283,8 @@ \subsection{The Schema Namespace and Location} 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.2 of VOResource must have a \xmlel{version} attribute -with value \texttt{1.2} on their root element (i.e., \xmlel{Resource}). +for version 1.3 of VOResource must have a \xmlel{version} attribute +with value \texttt{1.3} on their root element (i.e., \xmlel{Resource}). Document authors are strongly encouraged to bind this namespace to the \xmlel{vr:} prefix. While in generic XML processing, the concrete @@ -466,7 +467,7 @@ \subsubsection{Dates and Times} timezone marker. Such timestamps are to be interpreted as if they had a trailing Z. -% GENERATED: !schemadoc VOResource-v1.2.xsd UTCTimestamp +% GENERATED: !schemadoc VOResource-v1.3.xsd UTCTimestamp \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -499,7 +500,7 @@ \subsubsection{Dates and Times} VOResource and extensions can employ the \xmlel{vr:UTCDateTime} type. -% GENERATED: !schemadoc VOResource-v1.2.xsd UTCDateTime +% GENERATED: !schemadoc VOResource-v1.3.xsd UTCDateTime \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -981,9 +982,30 @@ \subsection{The Base Resource Type} minimally compliant resource description; this requirement is enforced by the VOResource schema definition. +\begin{admonition}{Note} +The VOResource \xmlel{status} attribute in the \xmlel{vr:Resource} type +somewhat overlaps with OAI-PMH's idea of the record's life cycle. In +particular, at least when VOResource metadata is consumed through +RegTAP, there is no difference between setting \xmlel{status} to +\verb|deleted| over publishing an \xmlel{oai:deletedRecord} for the +identifer; the former will let you keep publish VOResource metadata +\emph{through OAI-PMH}, which the latter does not because +\xmlel{oai:deletedRecords} do not admit \xmlel{oai:metadata} +elements. However, there is no use case for that in the current VO, and +hence publishers should exclusively use deleted records on the OAI-PMH +level rather than set \xmlel{status} to \verb|deleted|. + +Having a \xmlel{status} of \verb|inactive| will again purge the metadata +from RegTAP instances and hence will be indistinguishable from deletion to +the VO public. Operators may want to use that status code internally, +however, to temporarily hide malfunctioning services without deleting +their records from internal metadata stores. + +\end{admonition} + \goodbreak -% GENERATED: !schemadoc VOResource-v1.2.xsd Resource +% GENERATED: !schemadoc VOResource-v1.3.xsd Resource \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1069,14 +1091,23 @@ \subsection{The Base Resource Type} \item[Allowed Values]\hfil \begin{longtermsdescription}\item[active] - resource is believed to be currently maintained, and its - description is up to date (default). + The resource is available and maintained by the + publisher (default). \item[inactive] - resource is apparently not being maintained at the present. + The resource is temporarily offline but is expected to + resume operations at some later date; publishers in this + case could publish an estimate when that will happen in a + date element with a role of Available. Note that inactive + resources do not show up in RegTAP searchable registries. \item[deleted] - resource publisher has explicitly deleted the resource. + This status could be used for resources permanently + unavailable if VOResource metadata should still be + available via OAI-PMH; in the current VO, there is + probably no reason to ever do that, and deleted + records also do not show up in RegTAP searchable + registries. \end{longtermsdescription} \end{description} @@ -1242,7 +1273,7 @@ \subsubsection{Identity Metadata} metadata. The \xmlel{vr:ShortName} definition enforces the 16-character limit on shortNames. -% GENERATED: !schemadoc VOResource-v1.2.xsd ShortName +% GENERATED: !schemadoc VOResource-v1.3.xsd ShortName \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1276,7 +1307,7 @@ \subsubsection{Identity Metadata} % /GENERATED -% GENERATED: !schemadoc VOResource-v1.2.xsd IdentifierURI +% GENERATED: !schemadoc VOResource-v1.3.xsd IdentifierURI \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1325,7 +1356,7 @@ \subsubsection{Curation Metadata} -% GENERATED: !schemadoc VOResource-v1.2.xsd Curation +% GENERATED: !schemadoc VOResource-v1.3.xsd Curation \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1447,7 +1478,7 @@ \subsubsection{Curation Metadata} For entities registered in some other way -- in particular, DOIs or ORCIDs --, resource names can give \xmlel{altIdentifier}-s. -% GENERATED: !schemadoc VOResource-v1.2.xsd ResourceName +% GENERATED: !schemadoc VOResource-v1.3.xsd ResourceName \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1513,7 +1544,7 @@ \subsubsection{Curation Metadata} -% GENERATED: !schemadoc VOResource-v1.2.xsd Creator +% GENERATED: !schemadoc VOResource-v1.3.xsd Creator \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1545,8 +1576,7 @@ \subsubsection{Curation Metadata} \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] - An IVOA identifier for the creator (typically when it is - an organization). + Deprecated. Use the ivo-id attribute of the name child instead. \item[Occurrence] optional @@ -1709,7 +1739,7 @@ \subsubsection{Curation Metadata} relationships between the terms (except for mapping the deprecated VOResource 1.0 terms to the modern DataCite Metadata ones). -% GENERATED: !schemadoc VOResource-v1.2.xsd Date +% GENERATED: !schemadoc VOResource-v1.3.xsd Date \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1777,7 +1807,7 @@ \subsubsection{Curation Metadata} -% GENERATED: !schemadoc VOResource-v1.2.xsd Contact +% GENERATED: !schemadoc VOResource-v1.3.xsd Contact \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -1811,8 +1841,8 @@ \subsubsection{Curation Metadata} \begin{description} \item[Type] an IVOA Identifier URI: vr:IdentifierURI \item[Meaning] - An IVOA identifier for the contact (typically when it is - an organization). + Deprecated. Use the ivo-id attribute of the name child + instead. \item[Occurrence] optional @@ -1897,7 +1927,7 @@ \subsubsection{General Content Metadata} defined by the \xmlel{vr:Content} complex type. -% GENERATED: !schemadoc VOResource-v1.2.xsd Content +% GENERATED: !schemadoc VOResource-v1.3.xsd Content \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2108,7 +2138,7 @@ \subsubsection{General Content Metadata} \xmlel{format}. -% GENERATED: !schemadoc VOResource-v1.2.xsd Source +% GENERATED: !schemadoc VOResource-v1.3.xsd Source \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2207,7 +2237,7 @@ \subsubsection{General Content Metadata} up-to date list of the legal terms in HTML, turtle, or RDF-X formats, please refer to \url{http://www.ivoa.net/rdf/voresource/relationship_type}. -% GENERATED: !schemadoc VOResource-v1.2.xsd Relationship +% GENERATED: !schemadoc VOResource-v1.3.xsd Relationship \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2297,7 +2327,7 @@ \subsubsection{Resource Record Quality with validationLevel} a different \xmlel{validatedBy} value, to reflect the code assigned by different organisations. -% GENERATED: !schemadoc VOResource-v1.2.xsd Validation +% GENERATED: !schemadoc VOResource-v1.3.xsd Validation \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2341,7 +2371,7 @@ \subsubsection{Resource Record Quality with validationLevel} % /GENERATED -% GENERATED: !schemadoc VOResource-v1.2.xsd ValidationLevel +% GENERATED: !schemadoc VOResource-v1.3.xsd ValidationLevel \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2410,16 +2440,23 @@ \subsubsection{Resource Record Quality with validationLevel} % /GENERATED -\subsection{Resource Type Extensions: Organisation and Service} +\subsection{Resource Type Extensions} -The VOResource schema defines two extensions of the base -\xmlel{vr:Resource} type for describing two specific types of +The VOResource schema defines three extensions of the base +\xmlel{vr:Resource} type. Two of them describe specific types of resources: \xmlel{vr:Organisation} and \xmlel{vr:Service}. In addition to providing more refined semantic meanings over \xmlel{vr:Resource}, they add additional metadata for describing the resource which do not necessarily apply in the generic case. +The last resource type defined by VOResource, +\xmlel{vr:DiscontinuedResource} allows publishers to +provide a certain amount of persistence even in the presence of major +changes in their data holding. + +The following subsections will introduce these resource types in more +detail. \subsubsection{The Organisation Resource Type} @@ -2444,7 +2481,7 @@ \subsubsection{The Organisation Resource Type} \xmlel{instrument}: -% GENERATED: !schemadoc VOResource-v1.2.xsd Organisation +% GENERATED: !schemadoc VOResource-v1.3.xsd Organisation \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2530,7 +2567,7 @@ \subsubsection{The Organisation Resource Type} \subsubsection{The Service Resource Type} -The \xmlel{vr:Service} resource type is used to describe a service--a resource +The \xmlel{vr:Service} resource type is used to describe a service -- a resource that actually does something -- in the sense defined by the RM: @@ -2547,7 +2584,7 @@ \subsubsection{The Service Resource Type} invoked. -% GENERATED: !schemadoc VOResource-v1.2.xsd Service +% GENERATED: !schemadoc VOResource-v1.3.xsd Service \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2642,7 +2679,7 @@ \subsubsection{The Service Resource Type} usage limitations, citation recommendations, etc., directed at VO users in the first \xmlel{rights} element. -% GENERATED: !schemadoc VOResource-v1.2.xsd Rights +% GENERATED: !schemadoc VOResource-v1.3.xsd Rights \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2715,7 +2752,7 @@ \subsubsection{The Service Resource Type} different capability of the service. -% GENERATED: !schemadoc VOResource-v1.2.xsd Capability +% GENERATED: !schemadoc VOResource-v1.3.xsd Capability \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -2861,7 +2898,7 @@ \subsubsection{The Service Resource Type} use of its \xmlel{xsi:type} attribute and typical values thereof, is discussed sect.~\ref{sect:servicemodel}. -% GENERATED: !schemadoc VOResource-v1.2.xsd Interface +% GENERATED: !schemadoc VOResource-v1.3.xsd Interface \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -3053,7 +3090,7 @@ \subsubsection{The Service Resource Type} \xmlel{mirrorURL} admits a \xmlel{title} attribute: -% GENERATED: !schemadoc VOResource-v1.2.xsd MirrorURL +% GENERATED: !schemadoc VOResource-v1.3.xsd MirrorURL \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -3105,7 +3142,7 @@ \subsubsection{The Service Resource Type} defined as a complex type but with empty content: -% GENERATED: !schemadoc VOResource-v1.2.xsd SecurityMethod +% GENERATED: !schemadoc VOResource-v1.3.xsd SecurityMethod \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -3177,7 +3214,7 @@ \subsubsection{The Service Resource Type} service. -% GENERATED: !schemadoc VOResource-v1.2.xsd WebBrowser +% GENERATED: !schemadoc VOResource-v1.3.xsd WebBrowser \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -3218,7 +3255,7 @@ \subsubsection{The Service Resource Type} \xmlel{vr:WebService} is the second \xmlel{vr:Interface} sub-type available from the VOResource schema: -% GENERATED: !schemadoc VOResource-v1.2.xsd WebService +% GENERATED: !schemadoc VOResource-v1.3.xsd WebService \begin{generated} \begingroup \renewcommand*\descriptionlabel[1]{% @@ -3287,10 +3324,58 @@ \subsubsection{The Service Resource Type} services. It is thus unlikely that modern services will use this interface. See sect.~\ref{sect:servicemodel} for details. + +\subsubsection{The DiscontinuedResource Resource Type} + +The VO by itself provides no persistence features: IVOA identifiers are +defined and managed by publishers, and when publishers decide to +withdraw metadata, it is gone. This is appropriate for a collection of +metadata of active services; there is also no need to replicate +established PID schemes, in particular DataCite. + +However, sometimes it is desirable to provide links to newer resources +that supercede existing resources \emph{within} the Virtual Observatory, +in particular in workflows using IVOA identifiers. This can be effected +by a \vorent{relationship} declaration using a relationship type of +\vocterm{IsContinuedBy}. + +When the effort of maintaining the original, superceded resource is +non-negligible, or if distributing data within the resource is +scientifically undesirable, its publishers may decide to shut it down. +If they consequently delete the old resource's registry record, the +identifier will no longer resolve in searchable registries, and there +would be no record to hold the \vocterm{IsContinuedBy} relationship. +Rather than deleting the record, the publisher could just remove all +capabilities from the existing record. But since such records could +also be the result of plain oversights, this seems somewhat too implicit. + +Hence, for this situation, VOResource since version 1.3 offers the +\vorent{vr:DiscontinuedRe\-source} type; this has exactly the content +model of a plain \vorent{vr:Resource}, such that basic metadata is +preserved. But its type indicates that clients should move on to some +resource given by relationships. Therefore, records of this type SHOULD +provide at least one \vorent{relationship} with a type of +\vocterm{IsContinuedBy}. Clients should indicate these redirect(s) to +their users. + +Since the content model of discontinued resources is that of basic +\xmlel{vr:Resource}, we do not repeat it here. See +Sect.~\ref{sect:restype} for details. + \appendix \section{Change History} +\subsection{Changes from REC-1.3} + +\begin{itemize} +\item Added a \xmlel{DiscontinuedResource} record type. +\item Deprecated the \xmlel{ivo-id} attributes of \xmlel{Creator} +and \xmlel{Contact}. +\item Clarifying that the publisher sets the \xmlel{status} attribute. +\end{itemize} + + \subsection{Changes from PR-1.2} \begin{itemize} diff --git a/test-data/discontinued-record.xml b/test-data/discontinued-record.xml new file mode 100644 index 0000000..92cf489 --- /dev/null +++ b/test-data/discontinued-record.xml @@ -0,0 +1,47 @@ + + + + The Old Schoolyard + old-schoolyard + ivo://ivoa-school/old-yard + + + The IVOA VO school + + Riese, A. + + 2024-10-16 + + IVOA Registry WG + registry@ivoa.net + + + + + astronomy-education + + The old schoolyard had nice trees and all, but we used + way too much water on them. Thus, we built a new + schoolyard, which you will find at ivo://ivoa-school/new-yard. + + https://ivoa.net/blog/sustainability + Other + General + + IsContinuedBy + The new IVOA schoolyard + + + +