Skip to content

Adding text for the json xtype #52

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

Merged
merged 5 commits into from
May 8, 2025
Merged

Adding text for the json xtype #52

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eb46b32
Removing trailing whitespace
msdemlei May 6, 2025
8bb46de
Adding text for the json xtype
msdemlei May 5, 2025
47b9c6a
Merge branch 'main' into add-json-xtype
pdowler May 7, 2025
deffc8e
Simplification of json rules as per Pat's suggestion.
msdemlei May 8, 2025
873c570
Merge branch 'main' into add-json-xtype
pdowler May 8, 2025
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
59 changes: 40 additions & 19 deletions DALI.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ \subsection{Synchronous Execution: DALI-sync}
A concrete DAL service specification will specify zero or more synchronous job
submission resources and whether they are mandatory or optional. It may mandate
a specific resource name to support simple client use, or it can allow the
resource name to be described in the service capability metadata
resource name to be described in the service capability metadata
(Section~\ref{sec:vosi-capabilities}).

\subsection{DALI-examples}
Expand All @@ -289,7 +289,7 @@ \subsection{DALI-examples}
$$

DAL services may implement the /examples resource and include it in the
capabilities described by the VOSI-capabilities resource
capabilities described by the VOSI-capabilities resource
(Section~\ref{sec:vosi-capabilities}); if they
do not, retrieving its URL must yield a 404 HTTP error code.

Expand Down Expand Up @@ -588,6 +588,12 @@ \section{Data Types and Literal Values}
\emph{point}, \emph{circle}, \emph{range}, \emph{polygon}, \emph{moc},
\emph{multipolygon}, \emph{shape}, \emph{uri}, and \emph{uuid} (see below).

A special case is the \emph{json} xtype: It allows publishers to, in
effect, embed complex, structured data in VOTables. Publishers
intending to use it are encouraged to carefully review whether
interoperable and metadata-rich VOTable constructs can be employed
instead.

In the following, where we say \verb|datatype="char"| we also allow the VOTable
\verb|datatype="unicodeChar"|. Where we say \verb|arraysize="*"| we also allow
providers to be more explicit by using a fixed size (e.g. \verb|20|) or fixed
Expand Down Expand Up @@ -769,7 +775,7 @@ \subsection{Point}

Coordinate values are not limited to fall within a defined valid range; this is a change from
DALI 1.1 where equatorial coordinates were explicitly limited. Software may have
to perform range reduction in some coordinate systems (for example, spherical coordinates) in
to perform range reduction in some coordinate systems (for example, spherical coordinates) in
order to correctly interpret or use the coordinate values. Coordinate values are more likely to
work as expected if they are expressed in the simplest form and do not require range reduction.
For example, in spherical coordinates, \verb|362.0 2.0| is equivalent to \verb|2.0 2.0|, but the
Expand Down Expand Up @@ -825,11 +831,11 @@ \subsection{Range}
\noindent
includes values from 10 to 11 (coordinate1) and from 20 to 21 (coordinate2).

Valid coordinate value limits are specified by \verb|xtype="point"| above.
This range form is used as part of the value of the POS parameter in
\citep{2015ivoa.spec.1223D} and \citep{2017ivoa.spec.0517B} (see also "shape" below).
Valid coordinate value limits are specified by \verb|xtype="point"| above.
This range form is used as part of the value of the POS parameter in
\citep{2015ivoa.spec.1223D} and \citep{2017ivoa.spec.0517B} (see also "shape" below).
For example, a range can span the meridian (longitude 0): 359 1 -1 1 is interpreted
as the small (2x2 degree) coordinate range from 359 across the meridian to 1 degree
as the small (2x2 degree) coordinate range from 359 across the meridian to 1 degree
longitude.

Range-valued service parameters may include additional metadata like minimum and
Expand Down Expand Up @@ -864,7 +870,7 @@ \subsection{Polygon}
10.0 10.0 10.2 10.0 10.2 10.2 10.0 10.2
\end{verbatim}

Valid coordinate value limits are specified by \verb|xtype="point"| above.
Valid coordinate value limits are specified by \verb|xtype="point"| above.
Vertices must be ordered such that the polygon
winding direction is counter-clockwise (when viewed from the origin toward the
sky) as described in \citep{2007ivoa.spec.1030R}.
Expand Down Expand Up @@ -946,7 +952,7 @@ \subsection{Shape}
polygon 10.0 10.0 10.2 10.0 10.2 10.2 10.0 10.2
\end{verbatim}

The interpretation and constraints on the coordinate values are as specified
The interpretation and constraints on the coordinate values are as specified
for the individual xtypes above.

The shape xtype provides a compatible description of the POS parameter in
Expand Down Expand Up @@ -1003,29 +1009,43 @@ \subsection{UUID}
datatype="char" arraysize="*" xtype="uuid"
\end{verbatim}

UUID values \citep{std:RFC4122} are serialised using the canonical ascii (hex)
UUID values \citep{std:RFC4122} are serialised using the canonical ascii (hex)
representation, for example: e0b895ca-2ee4-4f0f-b595-cbd83be40b04.

\subsection{JSON}

For complex data blobs that are not intended to be queriable, publishers
may choose to store them as serialised JSON \citep{std:JSON} strings in
VOTables. Note that in general, an appropriate VOTable serialisation
(e.g., as a \xmlel{GROUP} for a \xmlel{PARAM} or as unrolled
\xmlel{FIELD}\/s or a separate table for table cells) is preferred.

\xmlel{PARAM}\/s and \xmlel{FIELD}\/s containing JSON values should be
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could probably be simplified and restated in the style I ended up using for the other xtypes. maybe:

JSON values serialised in VOTable or described in service parameters should have the following VOTable type metadata:

\begin{verbatim}
datatype="char" arraysize="*" xtype="uri"
\end{verbatim}

The general allowance for unicodeChar and more specific arraysize would apply as it does elsewhere.

marked up with a \xmlel{datatype} of \verb|char| or \verb|unicodeChar|,
with variable or fixed \xmlel{arraysize} and an \xmlel{xtype} of
\verb|json|.


\subsection{Unsupported Types}

Support for any specific \xmlel{xtype} in implementations (client or service) is specified in
the service standard document. However, support for a specific \xmlel{xtype} as input (params
and uploaded content) should generally be considered optional. Implementations should
be able to read and write the underlying data type without knowing the semantics added
by the \xmlel{xtype}. In cases where understanding the meaning of an \xmlel{xtype} is required (for
example, the POS param in SODA) and a service does not support the serialized value,
the service should issue an error message that starts with the following text with the
and uploaded content) should generally be considered optional. Implementations should
be able to read and write the underlying data type without knowing the semantics added
by the \xmlel{xtype}. In cases where understanding the meaning of an \xmlel{xtype} is required (for
example, the POS param in SODA) and a service does not support the serialized value,
the service should issue an error message that starts with the following text with the
most specific \xmlel{xtype} noted:
\begin{verbatim}
unsupported-xtype: {xtype} [optional detail here]
\end{verbatim}
and may include additional detail where noted. For example, the value of the SODA POS parameter
is a \verb|xtype="shape"|, but if the implementation does not support the "range" construct, it
is a \verb|xtype="shape"|, but if the implementation does not support the "range" construct, it
would respond (minimally) with:
\begin{verbatim}
unsupported-xtype: range
\end{verbatim}
This behaviour will allow for new \xmlel{xtype}s to be introduced and for \verb|xtype="shape"|
This behaviour will allow for new \xmlel{xtype}s to be introduced and for \verb|xtype="shape"|
to be extended to include additional subtypes in the future.

\section{Parameters}
Expand Down Expand Up @@ -1128,7 +1148,7 @@ \subsubsection{RESPONSEFORMAT}
In some cases, the specification for a specific format may be parameterised
(e.g., the media type may include optional semi-colon and additional key-value
parameters). A DAL service must accept a RESPONSEFORMAT parameter indicating a
format that the service supports and should fail (Section~\ref{sec:response-error})
format that the service supports and should fail (Section~\ref{sec:response-error})
where the RESPONSEFORMAT parameter specifies a format not supported by the service
implementation.

Expand Down Expand Up @@ -1561,7 +1581,8 @@ \subsection{PR-DALI-1.2}
\begin{itemize}
\item clarified that truncation indicated by OVERFLOW can occur independent of
MAXREC
\item added new xtypes: hms, dms, moc, multipolygon, range, shape, uri, uuid
\item added new xtypes: hms, dms, moc, multipolygon, range, shape, uri,
uuid, json
\item changed VOSI-availability to optional
\item changed VOSI-capability so it is only required for registered services
\item clarified use of VOTable serialisation for numbers and boolean
Expand Down