[imps] Another validation result format for review

[Henri Sivonen]

On Sep 12, 2007, at 19:10, Thomas Broyer wrote:

> 2007/9/12, Henri Sivonen:
>> I'd like to enable the use of Validator.nu as a RESTful Web service.
>> To this end, I have designed a Validator.nu-native JSON response  
>> format:
>> http://wiki.whatwg.org/wiki/Validator.nu_JSON_Output
>
> I just skimmed through your two docs and the first comment that came
> to mind is: why is he using types/subtypes rather than a few more
> types?
> type:info, no subtype => type:info
> type:info, subtype:warning => type:warning
> type:error, no subtype => type:error
> type:error, subtype:fatal => type:fatal-error
> type:non-document-error, no subtype => type:non-document-error
> type:non-document-error, subtype:io => type:io-error
> type:non-document-error, subtype:schema => type:schema-error
> type:non-document-error, subtype:internal => type:internal-error

Yeah, that's exactly the current internal flat taxonomy. The reason  
for the design in forward-compatible extensibility. The assumption is  
that the three main types will be cast in concrete, but subtypes may  
be added without breaking client written to the current spec.

It looks cruftier in JSON than in XML, though. :-/

> My second comment is: it seems the "indeterminate" result is dependent
> upon a non-document-error message; couldn't they be merged? I.e.
> there's no type:non-document-error and, if a "non document error"
> happen, the result:indeterminate has specific properties related to
> the "non document error" which leaded to this state. Example in JSON:
> "result": {
>     "type": "indeterminate",
>     "errors": [
>         { "type": "io", "message": "...", "url": "..." }
>     ],
> }

The type of the result is completely redundant. It could be computed  
by the client from the top-level message types.

My initial design didn't have explicit results at all due to this  
redundancy. I introduced explicit results for two reasons:
1) To carry the same human-readable message that you get from the (X) 
HTML output.
2) To make it trivial for clients to query the result format for the  
overall result.

I hesitate merging non-document-errors into results, because the  
results would have to take on locator features (at least url for IO  
errors) that messages already have. However, if potential users of  
the Web service interface don't care about my human-readable  
characterization for the result (they differ for the HTML5 facet and  
for the generic facet—that's all), I'd be happy to zap the  
precomputed result altogether from the XML and JSON formats.

Do people care about the precomputed result and the associated UI- 
level message?

>> I'd appreciate comments on the format--especially from people who can
>> foresee wanting to write clients.
>
> I'm not such a person, but I thought you could nevertheless be
> interested by my comments ;-)

I am. Thank you.

-- 
Henri Sivonen
hsivonen at iki.fi
http://hsivonen.iki.fi/