Skip to content

Use ASCL to reference software #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
msdemlei wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Use ASCL to reference software #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 40 additions & 4 deletions DocRegExt.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,12 +270,28 @@ \section{The DocRegExt Schema}
relationship\_type\footnote{\url{https://www.ivoa.net/rdf/voresource/relationship_type}}
defines what terms are legal in the declaration of relationships.
Document records should preferably use \vocterm{Cites} and
in particular declare relationships to tools. If these are not
registered, use the name of their binary as the name of the related
resource; this will very typically be lowercase-only. Tutorials
in particular declare relationships to tools. For VO-registered
services or standards, these relationships should provide the services' ivoids.
Tutorials
specifically introducing one or more services should define
\vocterm{IsSupplementTo} relationships to these services.

Client-side software or libraries do not have Registry records. To
reliably identify software, DocRegExt recommends the use of
ASCL\footnote{\url{https://www.ascl.net}} identifiers. These should be
used in the \verb|relatedResource| element's \verb|altIdentifier|
attribute. For instance, to declare that a tutorial uses the Cassis
client, it would say:

\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
<relationship>
<relationshipType>Cites</relationshipType>
<relatedResource>Specflow</relatedResource>
<relatedResource altIdentifier="ascl:1402.013"
>Cassis</relatedResource>
</relationship>
\end{lstlisting}

Document-typed resource records should contain a \vorent{date} element
with a \vorent{role} of \emph{Inspected}. This should correspond to the
last time that the current editor has made sure the tutorial or use case
Expand Down Expand Up @@ -409,6 +425,19 @@ \section{Locating Texts using RegTAP}
language.
\end{itemize}

To locate texts defining relationships to specific software tools, use
the relationship table's alt\_identifier column, for instance like this:

\begin{lstlisting}[language=SQL]
SELECT ivoid, res_title, related_name FROM
rr.resource
NATURAL JOIN rr.relationship
WHERE
res_type='doc:document'
and related_alt_identifier='ascl:1112.019'
\end{lstlisting}


The downside of not defining an extra table for the documents is that
the query patterns in RegTAP are somewhat clumsy. For instance, to list
the English and Italian titles of all texts available in Italian, one
Expand Down Expand Up @@ -509,7 +538,14 @@ \section{A versioned repository for tutorials}

\section{Changes}

\subsection{Changes from WD-1.0}
\subsection{Changes from PR-1.0-2025-11-02}

\begin{itemize}
\item Recommending the usage of ASCL identifiers to declare
relationships to software.
\end{itemize}

\subsection{Changes from WD-1.0-20230426}

None.

Expand Down
6 changes: 3 additions & 3 deletions dfbs-example.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ identification of misclassified objects from reference databases.</description>
<contentLevel>Amateur</contentLevel>
<relationship>
<relationshipType>Cites</relationshipType>
<relatedResource>TOPCAT</relatedResource>
<relatedResource>Aladin</relatedResource>
<relatedResource>astropy</relatedResource>
<relatedResource altIdentifier="ascl:1101.010">TOPCAT</relatedResource>
<relatedResource altIdentifier="ascl:1112.019">Aladin</relatedResource>
<relatedResource altIdentifier="ascl:1304.002">astropy</relatedResource>
<relatedResource ivo-id="ivo://cds.vizier/iii/227">General Catalog of galactic Carbon stars, 3d Ed.</relatedResource>
<relatedResource ivo-id="ivo://byu.arvo/tap">ArVO Byurakan TAP service</relatedResource>
<relatedResource ivo-id="ivo://cds.simbad/tap">SIMBAD TAP query engine</relatedResource>
Expand Down
1 change: 0 additions & 1 deletion m1distance-example.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ may be gained from very simple arguments and geometry.</description>
<contentLevel>General</contentLevel>
<relationship>
<relationshipType>Cites</relationshipType>
<relatedResource>The ALADIN image server</relatedResource>
<relatedResource>Aladin</relatedResource>
</relationship>
</content>
Expand Down