Merge pull request #102 from lmichel/dal-review

Dal review

Author: lmichel

.github/workflows/preview.yml

@@ -18,7 +18,7 @@ on:
     branches:
       - master
       - wd-v1.0
-      - apps-review
+      - dal-review
       - pr-1.0
 
 jobs:

doc/MANGO.tex

@@ -157,7 +157,8 @@ \subsection{Role within the VO Architecture}
 \end{figure}
 
 Fig.~\ref{fig:archdiag} shows the role this document plays within the
-IVOA architecture \citep{2010ivoa.rept.1123A}. This model reuses existing data models like Measure and Coords, and PhotDM. Implementations can use the TAP protocol and distribute data model instances in VOTable. 
+IVOA architecture \citep{2010ivoa.rept.1123A}. This model reuses existing data models like Measure and Coords, and PhotDM.
+Implementations can use DAL protocols (e.g. TAP, Simple Cone Search) and distribute data model instances in VOTable. 
 UCD, VOUnits and Vocabularies are also re-used.  
 
 \section{Representing observed astronomical objects : Use Cases and  Requirements}
@@ -242,22 +243,22 @@ \section{Model Overview}
 \begin{figure}
      \includegraphics[width=1.0\textwidth]{../model/overview.png}
      \caption{Model overview}
-     \label{overview}
+     \label{fig:overview}
 \end{figure}
 
-
-The root class of the model \texttt{MANGOObject} has only
+The model architecture is shown in Fig \ref{fig:overview}. 
+The root class, \texttt{MangoObject}, has only
 one mandatory attribute, an \texttt{identifier}.
 Identifiers should be unique within a collection, e.g. a data table, although 
 this feature is not required by the model.
 
-In addition to its identifier, \texttt{MANGOObject} objects have 2 components:
+In addition to its identifier, \texttt{MangoObject} objects have 2 components:
 
 \begin{itemize}[noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt]
 
-  \item \texttt{dataOrigin} (origin of the \texttt{MANGOObject}) : The structure of this class is based on
+  \item \texttt{dataOrigin} (origin of the \texttt{MangoObject}) : The structure of this class is based on
         the recommendations of the DCP interest group \footnote{https://ivoa.net/documents/DataOrigin/index.html}.
-  \item \texttt{propertyDock} (place holder for all the \texttt{MANGOObject} properties) :
+  \item \texttt{propertyDock} (place holder for all the \texttt{MangoObject} properties) :
         This is an open-ended collection.
         Mango properties inherit from the base class \texttt{Property},
         which contains everything necessary to identify both their nature and their role.
@@ -329,7 +330,7 @@ \subsubsection{MANGO and MIVOT: 2 Strategies for Structuring Tabular Data}
 
 MANGO is used to represent catalogue data which are typically provided in tabular
 form by TAP services \citep{2019ivoa.spec.0927D} 
-or other DAL nodes (one of the reference implementation is based on a Vizier SCS).
+or other DAL nodes (one of the reference implementation is based on a VizieR SCS).
 The linking between MANGO instances and table row elements is provided by MIVOT annotations.
 There are two possible strategies for establishing this mapping:
 

doc/Makefile

@@ -7,7 +7,7 @@ DOCNAME = MANGO
 DOCVERSION = 1.0
 
 # Publication date, ISO format; update manually for "releases"
-DOCDATE = 2025-12-18
+DOCDATE = 2026-01-22
 
 # What is it you're writing: NOTE, WD, PR, REC, PEN, or EN
 DOCTYPE = PR

doc/ivoatexmeta.tex

@@ -1,7 +1,7 @@
 % GENERATED FILE -- edit this in the Makefile
 \newcommand{\ivoaDocversion}{1.0}
-\newcommand{\ivoaDocdate}{2025-12-18}
-\newcommand{\ivoaDocdatecode}{20251218}
+\newcommand{\ivoaDocdate}{2026-01-22}
+\newcommand{\ivoaDocdatecode}{20260122}
 \newcommand{\ivoaDoctype}{PR}
 \newcommand{\ivoaDocname}{MANGO}
 \renewcommand{\ivoaBaseURL}{https://www.ivoa.net/documents/MANGO}

doc/model.tex

@@ -132,13 +132,13 @@ \section{Model: mango }
       \textbf{vodml-id: DataLink.content\_type} \newline
       \textbf{type: \hyperref[sect:ivoa]{ivoa:string}} \newline
       \textbf{multiplicity: 1} \newline
-      mime type of the content the link returns (see DataLink 1.1)
+      Provides the mime type of the content the link returns (see DataLink 1.1)
 
     \subsubsection{DataLink.access\_url}
       \textbf{vodml-id: DataLink.access\_url} \newline
       \textbf{type: \hyperref[sect:ivoa]{ivoa:anyURI}} \newline
       \textbf{multiplicity: 1} \newline
-      contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links.
+      Contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links.
 
     \subsubsection{DataLink.content\_qualifier}
       \textbf{vodml-id: DataLink.content\_qualifier} \newline
@@ -150,7 +150,7 @@ \section{Model: mango }
       \textbf{vodml-id: DataLink.local\_semantics} \newline
       \textbf{type: \hyperref[sect:ivoa]{ivoa:string}} \newline
       \textbf{multiplicity: 1} \newline
-      Allows for identification of corresponding rows for different IDs in the same DataLink service where the combination of semantics, content\_type and content\_qualifier is not sufficient to identify them (see DataLink 1.1).
+      Allows for link identification where the combination of semantics, content\_type and content\_qualifier is not sufficient (see DataLink 1.1).
 
   \subsection{DateTime}
   \label{sect:DateTime}
@@ -178,7 +178,7 @@ \section{Model: mango }
 
 
   \label{sect:EpochPosition}
-    This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coords:spaceSys}. \item The time coordinate system is imported from \texttt{coords:simeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:spaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:spaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item the observation date can be read in a column and therefore change with each data row. I this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EPochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize}
+    This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coordsSpaceSys}. \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item The observation date can be read in a column and therefore change with each data row. In this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize}
 
     \subsubsection{EpochPosition.longitude}
       \textbf{vodml-id: EpochPosition.longitude} \newline
@@ -428,13 +428,13 @@ \section{Model: mango }
 
   \subsection{Property}
   \label{sect:Property}
-    Class holder for a \textit{flavor} of property’ ie: there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself.
+    Class holder for a \textit{flavor} of property, i.e., there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself.
 
     \subsubsection{Property.semantics}
       \textbf{vodml-id: Property.semantics} \newline
       \textbf{type: \hyperref[sect:VocabularyTerm]{mango:VocabularyTerm}} \newline
       \textbf{multiplicity: 0..1} \newline
-      Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties. The semantics field contains a URI for a concept that describes the meaning of the property. This attribute is intended to be machine-readable and to assist automated link selection, presentation, and usage. The value is always interpreted as a URI; relative URIs (Berners-Lee and Fielding et al., 2005) are completed using the base URI of the core DataLink vocabulary, \url{http://www.ivoa.net/rdf/datalink/core}. Terms from this vocabulary must always be written as relative URIs. This means that for concepts from the core vocabulary, the value in the semantics fields always starts with a hash. (datalink1.1). The semantics concept applies to a single property or to the set made of the property and its associated properties (e.g. position and flag).
+      Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties (e.g. position and flag). This attribute is intended to be machine-readable and to assist automated property presentation, and usage. The value is always interpreted as a URI; relative URIs are completed using the base URI of the core UAT vocabulary, \url{http://www.ivoa.net/rdf/uat} (see \ref{sect:VocabularyTerm}).
 
     \subsubsection{Property.description}
       \textbf{vodml-id: Property.description} \newline
@@ -512,7 +512,7 @@ \section{Model: mango }
 
   \subsection{iso}
   \label{sect:iso}
-  Primitive type for observation dates expressed as an ISO Date (e.g. "2025-08-07T09:29:14").
+  Primitive type for observation dates expressed as an ISO-8601 Date (e.g. "2025-08-07T09:29:14").
 
   \subsection{mjd}
   \label{sect:mjd}
@@ -533,9 +533,9 @@ \section{Model: mango }
   \begin{itemize}
 
     \item[\textbf{SMOC}]: \textbf{vodml-id:} FootprintSerialization.SMOC \newline
-          \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored.
+          \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation.
     \item[\textbf{STC-S}]: \textbf{vodml-id:} FootprintSerialization.STC-S \newline
-          \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored.
+          \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). The STC-S space coordinate system overrides the \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation. Although the STC-S standard has been an IVOA draft for many years, it is still used by certain services, which justifies MANGO's support for it.
     \item[\textbf{POLYGON}]: \textbf{vodml-id:} FootprintSerialization.POLYGON \newline
           \textbf{description:} Label indicating that the footprint has been serialized as a polygon as defined in \cite{2017ivoa.spec.0517D} section 3.3.7. Using the polygon serialization requires the space coordinate system to be defined.
   \end{itemize}