[JMAP] Re: EmailSet - inconsistent behavior with keyword maps?

[Maia McCormick <[e-mail]>]

Hi Neil,

Incredible, thanks for the thorough explanation! This makes a ton of sense,
and has filled in some gaps in my mental models. Much appreciated!

Best,
Maia


On Mon, Dec 29, 2025 at 11:32 PM Neil Jenkins <[e-mail]>
wrote:

> Hi Maia,
>
> The main thing to understand is that an update in /set
> <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> is *patch* to
> the existing object.
>
> To update the $seen flag to TRUE (i.e. to mark a message as unread), both
> of the following syntaxes work:
>
> "update": {"my-message": {"keywords/$seen": true}}  # this works, yay!
> "update": {"my-message": {"keywords": {"$seen": true}}}  # so does this!
>
>
> So these do different things. The first one just patches the keywords
> property, adding the $seen keyword if not already set. The second one
> *replaces* the entire keywords property, so will blat any existing
> keywords. You almost certainly do not want this!
>
> When trying to unset the $seen flag (i.e. when marking a message as
> read), the first syntax works fine, but the second, nested syntax results
> in an error.
>
> # these work fine
> "update": {"my-message": {"keywords/$seen": false}}
>
>
> That one should be an invalidProperties error; that's a bug in whatever
> server you're testing against. This syntax means you are patching the
> object under the keywords property to map the $seen property to false,
> but that's not a valid value according to the spec
> <https://www.rfc-editor.org/rfc/rfc8621.html#page-25>. All properties
> must map to true.
>
> "update": {"my-message": {"keywords/$seen": null}}
>
>
> This will remove the $seen keyword (if set), which is what you want.
>
> # these won't successfully update my message
> "update": {"my-message": {"keywords": {"$seen": false}}}
> "update": {"my-message": {"keywords": {"$seen": null}}}
>
>
> These are invalid, because you're trying to replace the keywords object
> with a value that's not valid according to the spec
> <https://www.rfc-editor.org/rfc/rfc8621.html#page-25>:
>
>    o  keywords: "String[Boolean]" (default: {})
>
>       A set of keywords that apply to the Email.  The set is represented
>       as an object, with the keys being the keywords.  The value for
>       each key in the object MUST be true.
>
>
> Cheers,
> Neil.
>