Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Which content-type to use for SSE? #347

Open
relu91 opened this issue Jan 31, 2024 · 4 comments
Open

Which content-type to use for SSE? #347

relu91 opened this issue Jan 31, 2024 · 4 comments
Labels
Has Use Case Potential The use case can be extracted and explained

Comments

@relu91
Copy link
Member

relu91 commented Jan 31, 2024

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 #342 (comment)_

@egekorkan egekorkan changed the title Which content-type to use for SEE? Which content-type to use for SSE? Jan 31, 2024
@lu-zero
Copy link
Contributor

lu-zero commented Jan 31, 2024

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
Copy link
Member

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
Copy link
Contributor

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.

@lu-zero lu-zero added the Has Use Case Potential The use case can be extracted and explained label Feb 1, 2024
@benfrancis
Copy link
Member

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Has Use Case Potential The use case can be extracted and explained
Projects
None yet
Development

No branches or pull requests

4 participants