extra properties in responses

[Ricardo Signes]

The core spec reads:

> ## Vendor-specific extensions
>
> Individual services will have custom features they wish to expose over JMAP.
> This may take the form of extra datatypes and/or methods not in the spec, or
> extra arguments to JMAP methods, or extra properties on existing data types
> (which may also appear in arguments to methods that take property names). To
> ensure compatibility with clients that don’t know about a specific custom
> extension, and for compatibility with future versions of JMAP, the server
> MUST ONLY expose these extensions if the client explicitly opts in. Without
> opt-in, the server MUST follow the spec and reject anything that does not
> conform to it
> as specified.

I'd like to get a clarification here, as this has come up a bit with the JMAP
test suite. My reading is that when returning an object of an existing data
type, no extra (not in spec) properties should be provided unless the client
has expressly opted in to this extension. That is: it is an error to provide a
message's "mood" unless the client has requested the messageMoods extension.

Opting in does not appear to be defined in the spec. My assumption is
that it's something like:

* the client sees an advertised capability
* the client includes arguments in its method calls that indicate that it wants
to take advantage of that capability
* those arguments act as opt-in and the server responds accordingly

Meaning that if you want to get message.mood, you'd need to include "mood" in
the `properties` argument to getMessages. Of course, that means that you'll
need to include every other property, too, and can't just say "all the core
ones plus mood." Maybe that's fine? Or is the intention to have some further
removed mechanism for this?

(This came up because the test suite was written to call out as errors any
unexpected properties, which turned some up.)

--
Ricardo Signes (rjbs)
Research & Development, IC Group

[Neil Jenkins]

On Fri, 10 Feb 2017, at 02:29 AM, Ricardo Signes wrote:

My reading is that when returning an object of an existing

data type, no extra (not in spec) properties should be provided unless the

client has expressly opted in to this extension.

Correct.

Opting in does not appear to be defined in the spec.

Yes, this still needs to be done. Previous versions had various mechanisms, but they all had significant problems so we took them out while we reconsider.

The opt-in could be at the method level, or it could be at the connection level.

Meaning that if you want to get message.mood, you'd need to include

"mood" in the `properties` argument to getMessages.  Of course, that means that

you'll need to include every other property, too, and can't just say "all the

core ones plus mood."

No, if you opt in to an extension that adds a property to the object, then if you don't request a specific set of properties (i.e. you pass `properties: null` to a getFoos method), then all properties are returned including any ones from the extensions you have opted into.

Neil.