[Jmap] Re: Review of draft-ietf-jmap-essential-01

[Joris Baum <[e-mail]>]

Hi Lisa,

Replied inline

On 07.11.24 23:34, Lisa Dusseault wrote:
>
> I did a partial review of draft-ietf-jmap-essential-01.  I will later 
> continue taking notes and drawing connections and going back to reread 
> with new understanding, but I thought it would be more useful for me 
> and for the authors to send what I've got so far (so I don't rathole 
> about something I misunderstand, or about something that is going to 
> change).
>
thanks for taking the time to review! Sending out this mail sounds very 
reasonable indeed :) .

I think all the points you raised at least warrant some rephrasing to 
make it more clear what is intended here.

> Section 2.2 “Shared data shall not be exposed over the API”.  Does 
> "the API" mean this protocol? Is "shall" descriptive? If this is meant 
> to be an explanation of a necessary fact, I would need more 
> explanation to understand because I don't see why shared data would 
> necessarily not be exposed. If it’s meant to be requirements language, 
> that’s not clear.

The idea of the bullet points in Section 2.2 is listing requirements for 
some very basic data portability use cases. The idea of this document to 
make it easy for users to navigate through the JMAP Specs. Starting with 
a very simple/basic use case and allowing the developer to build on that.

* In that sense "API" means the JMAP API using the JMAP Procotol.

* Migrating sharing information between systems can be difficult as 
available sharing features of different systems varies quite a lot. Yes, 
there are some use cases that may require portability of shared data. 
However, for a lot of basic data portability use cases sharing the user 
data is already enough.

> Section 2.2, “Each user has the same set of capabilities” — what set 
> of users are we talking about ?  How does this relate to a session?  
> If it’s THE user of the session, I wouldn’t think it matters. Does a 
> session resource have multiple users in some way?

In JMAP each user typically is linked to a set of accounts. The Session 
Resource lists available accounts and capabilities that a user can use. 
See https://www.rfc-editor.org/rfc/rfc8620.html#section-1.6.2 . Those 
multiple accounts in a JMAP Session Resource signal to the JMAP Client / 
user a) which accounts it has access to b) which accounts to use for 
which capability / data type. E.g. a system might require a JMAP user to 
use a special JMAP Account for file operations.

> Section 2.2 is referenced via footnote [1] anywhere footnote [1] is 
> referenced in the table, e..g.  for /query method Request (accountId) 
> and /query method Response (accountId) .  That footnote says “Can be 
> modeled as a JSON file with only constant values."  How would an 
> accountId be modeled as a JSON file?  Or does this mean that the query 
> method Response (all of it) can be modeled as a JSON file with 
> constant values?  I’m sure you know what you mean here, I’m just not 
> getting it, nor do I understand how that relates to session resources 
> which are the subject of section 2.2.
That is a good find. Its not the value that can be modeled as a JSON 
file with constant values, but rather the Session Resource. That is 
indeed weirdly phrased. The accountId is used inside the Session Resource.
>
> Section 3.2.2 The accountId in the /query method “Can therefore be 
> ignored on the server side”.  I don’t like the idea of ignoring the 
> accountId.  If it’s a wrong accountID or access is forbidden, that 
> should be a bad request.  Why is it different from regular JMAP use 
> anyway?  Don't regular JMAP use cases (not just those profiled for 
> export/import) specify the accountId?
"Ignored" is indeed the wrong word here. Thanks for finding that. The 
idea is to fix accountId to "self" instead of making it a variable 
value. For a scenario as detailed by requirements in Section 2.2. in 
which shared data is not relevant it should be sufficient.
> Section 3: I fail to understand the organization of the nested 
> sections in section 3.  Is section 3.2.2 about Listing resources only 
> required for Exporting Data (but Exporting data is a subsection of 
> 3.1.2 but not 3.2.2 ? ?? )
>
OK that likely also needs some more level of clarity. The idea here is 
that the section organization of Section 3 provides more detail on what 
fields (and which parts) need to be implemented for a certain 
feature-set (likely mixed with word "use case" here). The idea is that 
the table in Section 3.1 provides a first overview about what needs to 
be implemented, and the section headings of 3.2 are referenced from 
within the table. A developer can then first identify what "JMAP Core 
Features" are required in Section 3.1 and in a second step scroll down 
to Section 3.2 to see how they are supposed to implement this.
> I’m trying to understand the various items with footnote [2].  
> Footnote [2] comes on text with several variants
> * “required for listing/paging[2]” e.g. /query method Request
> * “error response for listing/paging[2]”
> * “error response, required for listing/paging [2]” e.g. /get method 
> Request (ids)
> * “constant value for listing/paging[2]”
> * “error response for listing, required for paging[2]”
> Then footnote 2 says “maxObjectsInGet might not be sufficiently high 
> in some products. In this case, /query is required. Similarly, paging 
> might be required in case a query might exceed the limit for the 
> maximum amount of results for /query”
> I don’t understand how to put all this together.  The “in some 
> products” here leads me to believe the requirements are in fact not 
> nailed down as much as they appear.  Who gets to decide whether /query 
> support is required or not for a given server trying to support the 
> export profile?

OK. "some products" is also a misleading wording here. For data 
portability the most vital requirement is not to miss out on any data. 
Therefore:

* maxObjectsInGet in the JMAP Session Resource lists how many objects 
can be retrieved in a single /get request

* If the amount is at least as high as the maximum amount of objects for 
any given data type that any user has on the system, all objects can be 
retrieved in a single /get request.

* /query (which needs "listing" and "paging" as per document) is 
required if maxObjectsInGet is lower than the maximum amount of objects 
for any given data type of any user.

>
> Also I have trouble understanding what the “error response, required 
> for listing/paging” and other variations mean.  I think this table 
> format isn’t clear enough to be normative, and I’m really twisted up 
> by having several parts of the requirements for supporting “/get 
> method Request … “ split into several rows.  It feels like combining 
> “what is required’ along with information that means something other 
> than “what is required” in the same table. I’d really love if there 
> were one table with “Things that can be replied to with only an error 
> response  (but should not make the server blow up)” and another with 
> “Things that actually need to be implemented”.
Mhh.. maybe splitting out the more advanced features like listing, 
paging and attachments would help here? “error response, required for 
listing/paging” is supposed to mean: "Basically just replying with an 
error response is fine. However, if you want to support listing/paging 
then a simple error response is not enough and you actually need to 
implement this part."
>
> Part of my problem with understanding section 3 is the sections called 
> “Listing” and “Paging”.  How do we know if Listing is required?  How 
> do we know if paging is required?
> ISTM that to really apply draft-ietf-jmap-essential-01.html to define 
> how to do export for a given application, we would need to say more 
> about that given application. For example, if we want to use one of 
> these profiles for better interoperability of exporting one’s Contact 
> data, I think there’s hints in this document that it might be fine for 
> the server with Contacts data not to support paging functionality 
> because all of my Contacts can be downloaded at once.  But for better 
> interoperability of exporting a user’s email data, we’d better have 
> quite solid reliable support for paging through vast numbers of results.

Yes. Good point.

I wanted to leave that up to developers to decide if Listing or Paging 
is required for their particular use case. From a basic portability 
point of view, the case I make about maxObjectsInGet should be enough. I 
think this document would benefit from adding more detail on the 
different features and use cases.

> I’m also putting together my mental model which involves RFC8620, 
> RFC8621, draft-ietf-jmap-contacts-10 and this draft.  Client access to 
> server-held email/contacts may have different pressures on ID 
> immutability than export/synch use cases. How does a client tell if a 
> particular draft message with id “Md45b47b4877521042cec0938” is a more 
> recent version of “Mf40b5f831efa7233b9eb1c7f” if the replacement of 
> one by another was originally not requested by this client?  How does 
> a client tell if “Joe Bloggs” is the same contact card that was 
> previously “Joseph Bloggs” ? I assume RFC8620 has been used for synch 
> use cases because many full clients are effectively synch engines, but 
> I’d love to fill in my understanding here. I looked in RFC8620 and 
> draft-ietf-jmap-contacts-10 and may have missed explanations there, 
> but adding export/import use cases sharpens the need to understand how 
> a client can replace one contact or draft with a new contact or draft, 
> since these use cases lead to potentially more clients than just the 
> user's primary software application for a given domain.
Basic import/export functionality should not require advanced syncing 
like you have laid out. Syncing is a quite difficult problem, and I 
would like to keep that out of this very basic import/export version of 
JMAP. I could include a section on using IDs to provide some means for 
duplicate detection. The nice thing is that the full JMAP protocol is 
built from ground-up for syncing. So when syncing data is an important 
feature, I would like to refer to the full JMAP spec instead. Mentioning 
syncing is definitely missing in the spec. Good find.
>
> Thanks
> Lisa

Regards,

Joris


>
> _______________________________________________
> Jmap mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]

-- 
Joris Baum
Tel: [phone]
Fax: [phone]

http://www.audriga.com | http://www.twitter.com/audriga

--------------------------------------------------------------------------
audriga GmbH |  Alter Schlachthof 57  | 76137 Karlsruhe
Sitz der Gesellschaft: Karlsruhe - Amtsgericht Mannheim - HRB 713034
Geschäftsführer: Dr. Frank Dengler, Dr. Hans-Jörg Happel
--------------------------------------------------------------------------