Re: proposal to have sequential / grouped messages in soap output

Karim A. wrote:
> A grouped soap response would be something like:
>
> <m:error>
>     <m:message>
>         no document type declaration; implying &quot;&lt;!DOCTYPE HTML
>         SYSTEM&gt;&quot;
>    </m:message>
>    <m:messageid>344</m:messageid>
>    <m:explanation> ...</m:explanation>
>    <m:occurences>
>         <m:position>
>           <m:line>...</m:line>
>           <m:col>...</m:col>
>        </m:position>
>
>         <m:position>
>           <m:line>...</m:line>
>           <m:col>...</m:col>
>        </m:position>
>         ...
>         <m:position>
>           <m:line>...</m:line>
>           <m:col>...</m:col>
>        </m:position>
>    </m:occurences>
> </m:error>
>   
Actually, each sub-element in the group would contain the line, col, 
source, and message.

The challenge with grouping using a group container element, (from a 
consistency point of view) is that grouping breaks up the message -- 
messagetext (group version), messageid, explanation, and feedbackurl go 
with the group, while line, col, source, and message go with each 
occurrence.  So the structure must be something like:

<m:messagegroups count="25">
  <m:messagegroup>
    <m:groupmessagetext>end tag for X which is not 
finished</m:groupmessagetext>
    <m:messageid>73</m:messageid>
    <m:explanation><![CDATA[...]]></m:explanation>
    <m:feedbackurl>http://validator.w3.org/feedback....</m:feedbackurl>
    <m:messageoccurances count="1">
      <m:messageoccurance>
        <m:messagetext>end tag for "UL" which is not 
finished</m:messagetext>
        <m:line>...</m:line>
        <m:col>...</m:col>
        <m:source line="210" col="23"><![CDATA[...]]></m:source> (or 
break this into source, line, and col)
      </m:messageoccurance>
    </m:messageoccurances>
  </m:messagegroup>
  <m:messagegroup>
    ...
  </m:messagegroup>

  ...

</m:messagegroups>


This example is for structure -- not naming.  When it comes to naming, 
do you call the grouping element the 'message' or do you call each 
occurrence the 'message'?  Probably better to name them both something 
different (as I did above) to make it clear the the developer that 
neither is a 1-to-1 match with 'message' as used in the non-grouped 
(sequential) ordering.

Now, if you want to keep some sort of consistency (grouped output vs. 
sequential use the same markup), I see two options:

1.)  Use something like the above example for both grouping AND 
sequential.  So, sequential output would wrap each message in a 'group' 
of one element.  And, so it's the groups that are ordered sequentially 
(which I think that they are anyway -- even in 'grouped' mode).
2.)  Do away with two 'modes' in the SOAP output, and only give the 
sequential ordering.  But, give the developer enough information to 
group them himself.  In this case, you'd probably do something like:

    <m:message type="error" messageid="127">
      <m:messagetext>required attribute "ACTION" not 
specified.</m:messagetext>
      <m:groupmessagetext>required attribute X not 
specified.</m:messagetextgeneric>
      <m:explanation><![CDATA[...]]></m:explanation>
      <m:source line="210" col="23"><![CDATA[...]]></m:source>
      <m:feedbackurl>http://validator.w3.org/feedback....</m:feedbackurl>
    </message>

That way, I could parse all my messages and find the ones with the same 
'groupmessagetext' ("required attribute X not specified." in the above 
example).  These I could group together and  build my own grouped 
output.  I lean towards this implementation (#2) since we're developers 
and should be able to do our own grouping -- and with the added 
'groupmessagetext', it should be trivial.

BTW, I can already hear Karim:  "duplicating the groupmessagetext for 
every message wastes bandwidth!"  :-P   but it seems like an OK tradeoff 
for the simplicity offered by this method.

> Where <m:error> is a direct child of <m:errorlist> of
> the current implementation.
>
> (Do the same thing for warnings)
>
> This way, we can group similar errors/warnings and be able
> to retrieve ALL positions where they occured.
>   
I firmly believe that we need to do away with errorlist and warninglist 
in favor of a general messagelist (or just 'messages' if we can make 
'count' a 'messages' attribute).  Otherwise, it is impossible to 
sequentially order with errors and warnings intermixed.  And we NEED 
them all to have the same container type (not <m:error> and 
<m:warning>)  since parsing to get the errors and warnings intermixed is 
tough if they are a different class of object.

Oh, and by the way, we NEED to get the sequential stuff up and running.  
I have noticed that there are messages that reference the 'previous' or 
'next' message.  For example, message #25 (an error) includes the 
explanation: "This is usually a cascading error caused by a an undefined 
entity reference or use of an unencoded ampersand (&) in an URL or body 
text. See the previous message for further details."  The previous 
message in this case is a warning -- the two do go together.

And we also NEED the info bit up because, for example in message #68 
(also an error) states that "The next message, "|start tag was here|" 
points to the particular instance of the tag in question); the 
positional indicator points to where the validator expected you to close 
the tag."  And, of course, the next message (start tag was here) is an 
info message.

We need 'em all and we need 'em intermixed.

>> In the default output for the soap api, all errors (ordered sequentially by
>> occurrence) and all warnings (ordered sequentially by occurrence) are
>> segregated into separate containers.  This seems like a third (more useless)
>> mode that is its own creation -- closest to sequential mode of the web api
>> if anything.
>>     
>
> Why useless? :)
>   
A true sequential ordering has 'error', 'warning', and 'info' 
intermixed.  It is hard (if not impossible) to recreate this structure 
from 3 separate lists (especially, as I point out above, when an error 
message may reference the 'next' or 'previous' message which is a 
warning or info).
> I do use it myself, and have no problem with it... or maybe just the
> redundancy in messages and explanations in the output.
> But my app is living well with it ;-)
>   
I am too, but I'm not really giving my users the full benefit because 
the errors and warnings aren't working together for properly.  And, of 
course, adding 'info' would require you to change your app -- so why not 
change it to something that gets maximum benefit.
> If you change that, all my work (a hard work) will be vain :(
> So, please, keep it that way, and add a second template
> and a second way of generating output using this template...
>   
I agree that we shouldn't 'force' anyone to upgrade.  I prefer to leave 
the current implementation running and offer another 
template/api/version/whatever with all the new goodness.  Can we do this 
Oliver?

-Chris