Which content-type to use for SSE?

[relu91]

In this example form we are using Server-Sent Events

  {
          "href": "properties/result",
          "contentType": "text/event-stream", // should it be application/json ?
          "op": "observeproperty",
          "subprotocol": "sse"
        }

As we all know that is the content-type of the SSE specification, but the SSE payload may contain other textual formats like JSON or even XML. The content-type specified above it is more the content-type of the message structure used to convey the important application data. As with other protocols, the current practice in WoT is to use the content-type more as in indication of what is there for the application, rather than the actual content of what is sent on the wire. We should revisit this issue once we settle the discussion on data mapping.

=== Coming from https://github.com/w3c/wot-binding-templates/issues/342#issuecomment-1918867379_

[lu-zero]

If we decide that we use contentType to signal how to deserialize/serialize the encapsulated data in a protocol/subprotocol that has a fixed outer contentType we should get away with it until we have to describe protocols that have alternatives assuming we do not just force them to be signaled via the subprotocol field itself.

For sse would make sense to use application/json (or application/xml) but we should also note which are the sse restrictions on the payload.

E.g.: subprotocol:sse means http + text/event-stream and the contentType in the form can be repurposed.

for jsonrpc and socketio we would have a similar situation.

[benfrancis]

Note that the HTTP SSE Profile mandates the text/event-stream content type is used in Accept and Content-type HTTP headers.

No contentType member is required in a Form however, because it is implied by the subprotocol member being set to sse.

The HTTP SSE Profile also mandates JSON as a format for serialising data payloads in events.

I think Thing Descriptions currently lack the semantics to describe a sub-content-type, but I do think using application/json as a value for contentType in a Form when the server actually responds with a Content-type header of text/event-stream would be confusing and probably break Consumers.

I am starting to think that there should be a separate SSE Protocol Binding Template document which describes how to use SSE with the Web of Things.

Note that there are examples of content types that contain other content types on the Internet in general (e.g. multipart/mixed), but I don't have a strong opinion on how that should be expressed in a Thing Description.

[egekorkan]

I think Thing Descriptions currently lack the semantics to describe a sub-content-type

There is sort of a way to do this with contentMediaType, example https://w3c.github.io/wot-thing-description/#example-38

In that case, form content type would be text/event-stream and data schema would be JSON if the data in the text is formatted as JSON. We have used this example for the other way, i.e. storing a non-JSON data as a JSON string but the other way around should work. In any case, this needs more hands-on experience and documentation.

I am starting to think that there should be a separate SSE Protocol Binding Template document which describes how to use SSE with the Web of Things.

I agree with this one. It can be part of the HTTP Binding Template but as a separate and clear section.

[benfrancis]

There is sort of a way to do this with contentMediaType, example https://w3c.github.io/wot-thing-description/#example-38

Interesting. That does have the potential for confusion though.

In the HTTP SSE Profile, the type in the data schema of a property or event describes the primitive JSON type of the payload (i.e. the JSON-encoded value inside the data field of an SSE event), which could be a number, boolean, object or array etc. in instead of a string.

The contentMediaType member of StringSchema appears to be intended only to be used with a data schema of type "string".

So if I have a property or event with a numerical value, do I use "number" in the data schema to refer to the data payload or "string" so that I can use the contentMediaType member to say that it's JSON encoded? I personally don't think the latter makes a lot of sense since an EventStream isn't really just a simple "string" value and the data schema should really describe the underlying payload.

Either way no Consumer is going to know to do this without being explicitly programmed to do so, so it needs specifying somewhere, e.g. in a protocol binding document.

I don't mind whether the SSE binding is described inside the HTTP binding document or in a separate one, but it is a bit of a tricky one because it's both a protocol binding (e.g. the Last-Event-ID HTTP header) and payload binding (the text/event-stream content type).