Re: SPARQL 1.1 Protocol: Format of fault messages

* Richard Cyganiak <richard@cyganiak.de> [2010-10-03 19:36+0100]
> On 3 Oct 2010, at 17:03, Eric Prud'hommeaux wrote:
> >I read that as you're OK with the SOAP binding specifying a SOAP fault
> >which is different from the HTTP bindings, so <malformed-query/> stays
> >as is.
> 
> I don't know what a SOAP fault is. I'm just concerned with the HTTP
> bindings.
> 
> >>Saying that you SHOULD use a certain format leaves enough wiggle
> >>room for implementors to innovate, IMO.
> >
> >Sure, but we'd also like to encourage a backwards-compatible
> >extensibility model which allows me to have a great new idea without
> >breaking all the old code which e.g. reports errors to humans.
> >>
> >
> >>I have no objection against also proposing alternative response
> >>formats, as long as one option is clearly highlighted as the “no-
> >>brainer” option.
> >
> >And I'm interested in making sure that the alternatives subsume the
> >no-brainer in a way that the no-brainer parser can use.
> 
> Fair points.
> 
> >>And RDFa would be better than a magic class name.
> >
> >I'm afraid of demanding a generic RDFa parser for consumers of error
> >messages.
> 
> I see your point. But I'm afraid of even demanding an XHTML parser.
> In reality, too much XHTML ends up as tag soup.

I think the XML parser they use for the SPARQL Results will be fine.
If they were using DOM to parse, they can getElementById; if they're
using SAX, they can:

public void startElement(String namespaceURI, String localName, 
                         String qName, Attributes atts) throws SAXException {
    userMessage = false;
    for (int att = 0; att < atts.getLength(); att++) {
 if (atts.getLocalName(att) == "id" &&
     atts.getValue(att) == "malformedQueryFault") {
     userMessage = true;
 } 
    }
}

public void characters(char[] ch, int start, int length) throws SAXException {
    if (userMessage)
 ...

Either way, I think that the additional client code required to get
the user message is between 1 and 10 lines. For user code, they
already have some way to entity-encode text so it's basically
    print(template.top + entityEncode(errorMessage) + template.bottom);


> How about this:
> 
> [[
> A malformedQueryFault response SHOULD be a text/plain document
> containing a human-readable representation of the error. For
> example:
> 
>    HTTP/1.1 400 Bad Request
>    Content-Type: text/plain
>    Content-Length: 37
> 
>    Parse error at [5:17], unexpected ' '
> 
> Conformant implementations MAY convey the error message using
> other formats than text/plain. If they do so, or include more
> content besides the one-line error message in a text/plain
> response, then they MUST include a one-line human-readable
> representation of the error as an X-Malformed-Query-Fault HTTP
> header:
> 
>    HTTP/1.1 400 Bad Request
>    Content-Type: application/xhtml+xml

+1 to inlcuding the header in the example. We can just use text/html
and every browser on the planet will handle it.


>    X-Malformed-Query-Fault: Parse error at [5:17], unexpected ' '

Interesting, I could see doing this if the client's error-parsing
burden were higher, but I've pretty much convinced myself (above)
that it's easy (especially compared to getting at headers when I'm
running as a CGI, servlet, webkit client, etc.).


>    <?xml version="1.0" encoding="UTF-8"?>
>    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN"
> "http://www.w3.org/MarkUp/DTD/xhtml.dtd">
>    <html xmlns="http://www.w3.org/1999/xhtml">
>      <head>
>        <title>Malformed Query</title>
>      </head>
>      <body>
>        <h1>Malformed Query</h1>
>        <pre id="malformedQueryFault">Parse error at [5:17],
> unexpected ' '</pre>
>      </body>
>    </html>
> ]]
> 
> 
> Advantages:
> 
> 1. Anyone can still do anything, as long as they include one HTTP header
> 2. Machine-readability is *always* given

but via heuristics; I have to have two handlers.


> 3. Backwards compatible: If a client checks for presence of the
> header, and if absent checks for a text/plain body, then it will
> always get the message.

My first interpretation was that you should give plain text, but if
you weren't content with that, maybe something like this HTML here...
I now understand that this is to encourage exactly one of these two
alternatives.

While this does allow me to convey structured info while still giving
nice-to-read info to the primitive clients, I don't think that the
text/plain avoids much effort. The clients will still need to
implement both and the servers have a trivial amount of work to do to
implement the XHTML. I think the net work is lower, and the protocol
is simpler, if the only SHOULD is the XHTML alternative.



> Best,
> Richard
> 
> 
> 
> 
> >(Of course, I'm happy to see that practice flourish on its
> >own.) Class was a poor choice, how about ID? New proposal:
> >
> >[[
> >A malformedQueryFault response SHOULD be an XHTML document in which an
> >element with an XML ID of <code>malformedQueryFault</code> conveys a
> >human-readable representation of the error. For example:
> >
> > <?xml version="1.0" encoding="UTF-8"?>
> > <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN"
> >"http://www.w3.org/MarkUp/DTD/xhtml.dtd">
> > <html xmlns="http://www.w3.org/1999/xhtml">
> >   <head>
> >     <title>Malformed Query</title>
> >   </head>
> >   <body>
> >     <h1>Malformed Query</h1>
> >     <pre id="malformedQueryFault">Parse error at [5:17],
> >unexpected ' '</pre>
> >   </body>
> > </html>
> >
> >Other HTML elements in the response do not change the interpretation
> >of the element with the XML ID of <code>malformedQueryFault</code>/
> >]]
> >
> >
> >>Best,
> >>Richard
> >
> >-- 
> >-ericP
> 

-- 
-ericP

Received on Sunday, 3 October 2010 20:09:16 UTC