Subject: [Jmap] Review of draft-ietf-jmap-core-06

From: Stephan Bosch <[email-masked]>
Date: Mon, 30 Jul 2018 17:34:17 +0200

Hi,

Here are some of the comments and suggestions I collected while reading 
draft-ietf-jmap-core-06. I haven't followed the discussions and 
developments much lately, so there could be some stuff there (design 
choices) that is obvious to everyone else, but not to me. Some comments 
may therefore be redundant.

Text from the document itself is pasted here as-is. My comments are 
prefixed with "-> ".

Regards,

Stephan.

## Section 1.1:

"Foo" - Any name that is not a native JSON type means an object
       for which the properties (and their types) are defined elsewhere
       within this document.
-> What about "Date" and "UTCDate"? These are just strings and not objects.

## Section 1.2:

-> Should we define a separate special "Size" Number type for size 
values? Otherwise,
the >= 0 requirement for size values needs to be restated everywhere 
(which it
currently isn't).

## Section 1.7:

-> Is HTTPS required for JMAP? According to Section 7.1, yes. So, that 
should probably be
mentioned here as well.

## Section 2:

o  *accounts*: "String[Account]"
-> Some of this text may fit better in Section 1.5.2.

Servers MAY advertise vendor-specific JMAP  extensions. To avoid 
conflict, the
identifiers for these MUST be a URI beginning with a domain owned by the 
vendor.
-> What exactly would this normally look like? A URN? An HTTP URL? Maybe 
add one
in the example for clarity. At reference to Section 3.3 for finding details.

(see "Making an API request")
-> why not just use a numeric Section reference?

o     *downloadUrl*: "String" The URL endpoint to use when downloading
       files (see the Download section of this spec), in [RFC6570] URI
       Template (level 1) format.  The URL MUST contain variables called
       "blobId", MAY contain a variables called "accountId" and SHOULD
       contain a variable called "name".
-> What do these variables mean? Refer to the relevant section(s).

-> How long is a client supposed to cache the session data? What if e.g. the
API URLs need to change while clients are active? Should we add a TTL 
field so
that clients will use the new session data, or do we expect them to only 
reread
the session data when errors occur?

## Section 3.2:

*createdIds*: "String[String]" (optional)
-> Very long description for this field. Maybe create a separate section 
on how
the createdIds feature works in general? Other parts of the 
specification can
point to that section as well.

## Section 3.3:

-> Why is this not discussed earlier? I'd expect this in Section 1.

## Section 3.5:

-> Some arguments are marked explicitly as "(optional)". What exacly 
does that
mean? Isn't the mere fact that these have a default or "|null" in their
specification the same?

## Section 3.6:

-> Please clarify the difference between request-level and method-level 
errors
in a short introduction.

## Section 3.6.1:

    Every JSON "problem details" object MUST include a "type" member 
with a URI
    either one of the following values, or a value defined in a future 
RFC, or a
    value beginning with a domain owned by the vendor.
-> What exactly would this normally look like? A URN? An HTTP URL? Maybe 
add one
in the example for clarity. Refer to Section 3.3 for clarity.

## Section 3.6.2:

    Further possible errors for a particular method are specified in the
    method descriptions.
    Further general errors MAY be defined in future RFCs.  Should a
    client receive an error type it does not understand, it MUST treat it
    the same as the "serverFail" type.
-> Next section actually defines "resultReference", which was not listed 
here.
-> Shouldn't that be called e.g. "invalidResultReference" instead?

## Section 3.7:

-> Would it be useful to add the ability for a client to make the server 
omit
(specific) responses for a method? I.e. have certain response data 
available only for
references from other methods but not return it to the client? This 
could save some
effort on sending/parsing data that the client doesn't really need to see.

-> Can result references also yield arrays of objects or only arrays of 
strings
(as in the example)? If yes, this could maybe be used to make some really
stupid/abusive requests that copy objects between contexts (accounts), 
without
using the proper copy methods. What to do with that?

-> Can there be duplicate method responses? I.e., can there be 
ambiguities in
reference resolution?

## Section 4.3:

       Any server-set properties MAY be included in the patch if their
       value is identical to the current server value (before applying
       the patches to the object).  Otherwise, the update MUST be
       rejected with an _invalidProperties_ SetError.
-> The SetError concept is not yet explained at this point.

    The server MAY skip an update (rejecting it with a "willDestroy"
    SetError) if that object is destroyed in the same /set request.
-> The SetError concept is not yet explained at this point.

    The following SetError types are defined and may be returned for set
    operations on any record type where appropriate:
-> What about a generic temporary failure? "tryLater" ?
-> What a bout a "tooBig" error?

## Section 4.4:

-> How is/could the complexity of filters limited by the server? What 
error should be
returned if such limit is exceeded? Should the client be able to know 
the limits from
querying some session data?

-> How would queryState be implemented; some hash of all results?