TAP 1.0/1.1 inconsistency: error document format
Patrick Dowler
pdowler.cadc at gmail.com
Fri Oct 10 18:50:12 CEST 2025
Error handling is hard. Specification is probably harder.
This sounds fine to me, with one caveat. If we are talking about an
async error document nominally returned by accessing the UWS job, then
all the kinds of errors that could be captured there are from inside
the service and it is feasible to provide those in any chosen form (eg
VOTable for an invalid TAP query using default output format, ot
text/plain if the caller asked for tsv, etc). But: there are other
kinds of errors that happen outside the service-specific code and it's
easy to forget about those because they are not really an issue for
async... they are for any sync DAL service though. Some of these
other errors are covered by other work (eg A&A things will be covered
by AuthVO) and some are just low-level infrastructure (eg you get a
503 response with a fragment of html from a front-end haproxy service
because it cannot forward the request to the back end)... or some
error handling behaviour of a kubernetes ingress controller outputs
text/plain or application/json or something like that.
So I am just a little uneasy about saying "must" and having that be a
compliance issue and/or having that prohibit some good implementation
choices we haven't considered. The TAP-1.0 language used the phrase
"a TAP error" which was (iirc) supposed to mean the subset of errors
that happen inside the TAP service code itself (so most but not all
possible errors)... that was vague and misunderstood and the fix was
to defer to DALI (which came after TAP-1.0), but the idea was a little
more flexible than "must".
I am finding it really hard to tweak this text from Mark to convey
that. Just changing "must" to "should" is too far... but we can't say
"should+" or "must - epsilon" :-)
"An error document describing errors in use of the DAL service
protocol must be a VOTable document [ref] if the client is
expecting a VOTable response; in other cases it should usually
be a plain text document."
Maybe we do have to clarify the kinds of errors where it is "must":
invalid job description, error executing job, ... (with some
examples).
Should we also give some examples where it is not strictly "must":
auth related errors, ...
and clearly without being definitive in either list
I think it is important to address this so I would like to get some
improvement into DALI-1.2 before we go to RFC (which is otherwise
ready to go)...
--
Patrick Dowler
Canadian Astronomy Data Centre
Victoria, BC, Canada
On Fri, 10 Oct 2025 at 06:11, Gregory MANTELET
<gregory.mantelet at astro.unistra.fr> wrote:
>
> Mark,
>
> I prefer your version because of the change from "may" to "must".
>
> However, I'd prefer something saying that VOTable is currently the only
> standard format defined by the IVOA in order to convey errors. It must always
> be supported. So, if no format is explicitly requested or if the asked one is not
> supported, a VOTable format should be returned by default. On the contrary,
> if the one asked by the user is supported by the service, the error may be
> returned in this format. This way, a generic client knows that it can rely on
> a unique format (whatever happen): VOTable, in this case.
>
> That could maybe be written as such in DALI:
>
> "An error document describing errors in use of the DAL
> service protocol must be a VOTable document. If supported,
> other formats may be used when explicitly asked by a client.
> If a format is not supported, the service must fallback to
> the VOTable format."
>
>
> I do not really know how to write that in a correct english way, but I hope you
> get my idea. Then, is it a good idea? Is it to strict? I don't know.
>
> Anyway, what I do not like with saying VOTable or plain text is that it is too
> restrictive. Besides, there are probably more than one way to write an error in
> a plain text document (e.g. just the raw error message, a message + an error
> code, a message + more details, ...). At least, if we mention the plain text
> document, we should probably say that it is limited just to the raw error
> message ; no structure or other kind of information is expected.
>
> Moreover, explicitly giving another error format will probably lead to
> a future where one would ask to update this sentence in order to add
> another format (e.g. JSON), and then another one. If the new formats are
> standardized by the IVOA, it is fine, but otherwise, I think we should probably
> avoid this.
>
> Cheers,
> Grégory
>
>
> On 10/10/2025 09:56, Mark Taylor wrote:
>
> Pat,
>
> I generally agree with that. So a fix in DALI could look like
> changing text in the DALI 1.2 current WD section 5.2 from:
>
> "An error document describing errors in use of the DAL service
> protocol may be a VOTable document [ref] or a plain text document."
>
> to
>
> "An error document describing errors in use of the DAL service
> protocol must be a VOTable document [ref] if the client is
> expecting a VOTable response; in other cases it should usually
> be a plain text document."
>
> The phrase before the semicolon would supply what I've been
> complaining about here. The second part could be written more
> prescriptively, but I've put "should usually" instead of "must"
> to leave open the possibility of JSON or whatever that somebody
> mentioned, I don't know if that's really a good idea or should
> be tightened up.
>
> Although I agree that text/plain is generally easier for clients,
> what's not easier is having to examine the content-type and adjust
> the parsing on the basis of that - you want to know what to expect.
>
> Relevant: since I brought this up the Rubin service has now been
> changed to work as expected (error document is VOTable not plain text),
> which I believe is how all other services do it, so in practice this
> isn't so much of a problem for me (I'm probably not going to make
> code changes unless it comes up again).
>
> Mark
>
> On Thu, 9 Oct 2025, Patrick Dowler wrote:
>
> In my view the TAP-1.1 text is about as good/correct as possible;
> TAP-1.0 was too strict given that we allowed other output formats. The
> main problem is that DALI-1.1 is too vague, but I'd also hate for this
> to become too complicated.
>
> essentially:
> if request is VOTable: error response should be VOTable
> if request is csv or tsv: error response in text/plain should be fine
> if request is parquet (aka VOParquet): error response is ???
>
> We currently use text/plain in the last case (prototype) and I don't
> see any other choice as viable... to be clear, I think even this is
> too much to write in DALI because other services are working with say
> xml and json serialisation formats.
>
> I don't want to go so far as to say it was a mistake to ever put error
> messages into VOTable, but to be honest text/plain is almost always
> easier and better for the client...
>
> So the fix is nominally in DALI, TAP-1.2 could make a more careful
> statement aligning with DALI... if we can agree on it we can get it
> into 1.2
>
> --
> Patrick Dowler
> Canadian Astronomy Data Centre
> Victoria, BC, Canada
>
> On Thu, 9 Oct 2025 at 07:47, Grégory Mantelet
> <gregory.mantelet at astro.unistra.fr> wrote:
>
> Hi Pat, Mark,
>
> As web client developer, I indeed appreciate when I can have something else than a XML
> document to parse in case of query error. I already have the possibility to get some errors in
> JSON, and apparently Rubin already accept text errors.
>
> On the other hand, I'd also understand if a service cannot supply the error in multiple formats.
> It is not always easy or possible to do. Because of this, I agree with the approach stating
> that the error documents should be provided, as much as possible, in the requested format.
> Then, we should probably say that the fallback standard format must be VOTable. This way,
> it is a safe format that a generic client can rely on. So, in a word, I agree.
>
> Anyway, I am a bit lost. Where do you plan to apply a fix?
> DALI, TAP, UWS?
> If DALI, is it expected in the upcoming DALI-1.2?
>
> Cheers,
> Grégory
>
>
> On 17/09/2025 18:12, Mark Taylor via dal wrote:
>
> The impossible-to-provide-VOTable point doesn't apply in this context.
> TAP 1.1 sec 3.3 does talk about errors in the use of the HTTP protocol,
> which would lead to non-VOTable error responses, but the case I'm
> talking about here is an error document retrieved from the UWS
> error document endpoint /async/<jobid>/error:
>
> "Error documents should be in a format that matches the requested format
> where possible; see DALI for details. If the error document is being
> retrieved from the /async/<jobid>/error resource (specified by UWS)
> after an asynchronous query, the HTTP status code should be 200."
>
> So where a VOTable result is implicitly or explicitly requested
> it is possible to supply a VOTable response; the TAP 1.0->1.1
> inconsistency is the "should" which used to be a "must".
>
>
> On Wed, 17 Sep 2025, Patrick Dowler wrote:
>
> At this point it has been written/advertised that way for years, so we
> should consider whether it is something to fix or just something to
> accept and adapt to... I know it is not always possible to adhere to
> the strict "error must be VOTable" because some errors happen before
> handling the request gets anywhere near the code that can feasibly
> write a VOTable.
> --
> Patrick Dowler
> Canadian Astronomy Data Centre
> Victoria, BC, Canada
>
> On Wed, 17 Sept 2025 at 02:51, Mark Taylor <m.b.taylor at bristol.ac.uk> wrote:
>
> It might be the spirit, but between TAP 1.1 and DALI 1.1 the text does
> seem to allow a plain text error document, which is what Rubin are
> currently doing, though I haven't encountered it in other services.
>
> So I think that means that clients and validators have to be prepared
> for that (topcat and taplint currently are not; I don't know about
> other TAP clients).
>
> Unless we consider this Erratum fodder?
>
> On Mon, 15 Sep 2025, Patrick Dowler wrote:
>
> iirc, it was deliberate to change from "must be VOTable" to be able to
> play nice with other formats, so it probably should have been as close
> to "must be in the requested format" as possible. But of course, not
> all tabular output formats can carry error messages, so it gets kind
> of tricky in the details.
>
> The spirit is still definitely that if the client expects a VOTable
> response they get that for both success and error, but the DALI quote
> shown is much too vague... I think that is where the
> clarification/detail is needed.
>
> --
> Patrick Dowler
> Canadian Astronomy Data Centre
> Victoria, BC, Canada
>
> On Mon, 15 Sept 2025 at 06:41, Mark Taylor via dal <dal at ivoa.net> wrote:
>
> Hi DAL.
>
> Following a taplint query by Stelios, I've just noticed the following
> inconsistency between TAP 1.0 and TAP 1.1 as regards the format of
> UWS error documents resulting from failed async TAP queries:
>
> TAP 1.0 Sec 2.7.3:
> "Error documents for TAP errors must be VOTable documents;
> any result-format specified in the request is ignored."
>
> TAP 1.1 Sec 3.3:
> "Error documents should be in a format that matches the requested
> format where possible; see DALI for details."
>
> DALI 1.1 Sec 4.2:
> "An error document describing errors in use of the DAL service
> protocol may be a VOTable document (...) or a plain text document."
>
> For an expected VOTable result, this is effectively a downgrade of a
> MUST to a SHOULD for VOTable as the format of the error document.
>
> So a TAP 1.0 client will expect a VOTable error document from a failed
> async TAP query, but may get tripped up by receiving instead a plain
> text error document. This change is not explicitly noted in
> Appendix A of TAP 1.1 "Changes from TAP-1.0 to TAP-1.1",
> though A.1 says, somewhat misleadingly, "Removed text that duplicates
> material from DALI.".
>
> This looks to me like an oversight since it is (from the client's
> point of view) a backwardly incompatible behaviour change from TAP 1.0
> to TAP 1.1.
>
> Has anybody come across this before, or remember whether it was
> deliberate?
>
> Mark
>
> --
> Mark Taylor Astronomical Programmer Physics, Bristol University, UK
> m.b.taylor at bristol.ac.uk https://www.star.bristol.ac.uk/mbt/
>
> --
> Mark Taylor Astronomical Programmer Physics, Bristol University, UK
> m.b.taylor at bristol.ac.uk https://www.star.bristol.ac.uk/mbt/
>
> --
> Mark Taylor Astronomical Programmer Physics, Bristol University, UK
> m.b.taylor at bristol.ac.uk https://www.star.bristol.ac.uk/mbt/
>
>
> --
> Mark Taylor Astronomical Programmer Physics, Bristol University, UK
> m.b.taylor at bristol.ac.uk https://www.star.bristol.ac.uk/mbt/
>
>
More information about the dal
mailing list