Matrix-doc: Ambiguous behaviour when messages field is not provided in calls to PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId}

[anoadragon453]

Currently the spec defines the messages field in the JSON body of requests to PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId} as not required. It's not really clear what the homeserver should do when messages is not provided.

Indeed, there isn't anything for the homeserver to do when messages is not provided, and thus not including message is a bit pointless.

I feel that we should mark messages as a required field. It doesn't really make sense to define a default message.

Note that Synapse currently Internal Server Errors when messages is not provided, though this is fixed by https://github.com/matrix-org/synapse/pull/8975.

[turt2live]

I'm pretty sure it's just a documentation error and the field is supposed to be required.

[anoadragon453]

Thank you. In that case, have a pr: https://github.com/matrix-org/matrix-doc/pull/2928

[turt2live]

well, we also need to dredge up the history to figure out if that's actually the case :p

[anoadragon453]

After some dredging I discovered that this bit of spec was originally introduced in https://github.com/matrix-org/matrix-doc/pull/386. That PR is a spec doc implementation of https://docs.google.com/document/d/1v8lxwKi1y074ggYYAjZTHN2EJYBFPtnot2nM3vVWTR0/edit.

From reading both, I believe that it was intended for messages to always be provided. I don't see any discussion or a clear reason as to why it should have been optional.

[turt2live]

Yea, that seems fair. The approving reviews on the PR also help justify the decision imo.