Affects Version/s: V4.0_WD01
Fix Version/s: V4.0_WD01
Clarified wording. Note that in-stream errors only apply to responses whose body may be streamed (so wouldn't, for example, apply to 204 No Content)
In the current revision of the Work Product [OData Core Part 1: Protocol, Version 1.0](https://www.oasis-open.org/committees/download.php/47547/odata-core-v1.0-wd01-part1-protocol-2012-11-26.doc) in section 9.3 In-Stream Errors the relevant states and procedures might be specified with more rigor without diving into specific formats or usecases. Currently I have no proposal, since I can't answer some questions of understanding (see below), but am willing to provide one, once these questions have been answered.
Currently section 9.3 "In-Stream Errors" reads:
"In the case that the service encounters an error after sending a success status to the client, the service MUST generate an in-stream error which SHOULD leave the response malformed. Clients MUST assume that any malformed responses are invalid and results SHOULD be discarded.
This specification does not prescribe a particular format for such in-stream errors."
In my understanding the sentence: "[...]the service encounters an error after sending a success status to the client," indicates that the HTTP headers (associated with success) have already been sent to the network interface.
The next part " the service MUST generate an in-stream error which SHOULD leave the response malformed. " tries to be format agnostic. Together with the last sentence in the paragraph "Clients MUST assume that any malformed responses are invalid and results SHOULD be discarded.
" I derive from this, that this magical "in-stream error"-thingie is completely volatile, since the client MUST assume, that the whole response (any info therein!) are invalid and SHOULD throw it away without further inspection.
The recipes for $format=json and any xml like the default atom should be "stop adding to the response body, just flush the pipe. Right?
The last paragraph (in that light) looks a bit lawyer like (to me).
I also am curious, how the service shall generate an in-stream error, in use cases like:
"A Prefer header with a value of return-no-content requests that the service invoke the request but not return content in the response. The service MAY honor this request by returning 204 No Content."(8.4.1 The Prefer Header)
"A service MAY reply to a Data Modification Request with 202 Accepted, indicating that the request has been accepted but has not yet completed. In this case, the response MUST contain a Location header in addition to a Retry-After header, and the response body MUST be empty."(9.1.3 202 Accepted Response Code)
"A service may reply to a Data Modification Request with 204 No Content. In this case, the response body
MUST be empty."(9.1.4 204 No Content Response Code)
These share the body-less response class. So is it expected, that in those cases and where applicable the "body MUST be empty" is changed through say adding a character like '<' to the network pipe to invalidate independant of chosen $format (json, xml.*) and replace this by a "odata malformed body"? But if so, what about a response to say a GET /Entities(1)/Property/$value ? In these cases it may become impossible to invalidate the response body (say for the default type Edm.String)
Maybe the term In-Stream error also contributes to misunderstandings? Which states of error are included for which HTTP operations? Might some of the latter better be excluded or described in an extra paragraph?
Any feedback, help appreciated.