[Gen-art] Genart last call review of draft-ietf-jmap-quotas-06

[Thomas Fossati via Datatracker <[e-mail]>]

Reviewer: Thomas Fossati
Review result: Ready with Issues

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-jmap-quotas-??
Reviewer: Thomas Fossati
Review Date: 2022-11-10
IETF LC End Date: 2022-11-19
IESG Telechat date: Not scheduled for a telechat


The document is generally clear, but at times the prose is a bit too
terse -- and this is from someone who really appreciate terseness :-) I
guess some of that can be fixed at the RFC Editor, but there are some
other places (e.g., §2.1) that may need the author to slightly increase
the precision.  (A JMAP expert is likely to have a completely different
point of view on this. so I'm not going to insist.)
I am flagging a few issues that should be easy to fix.

Major issues
------------

1. In §2, there is no discussion about internationalisation of the
   "description" property.  If this is to be rendered to human eyes,
   there needs to be some way to establish the context in which the
   string is to be consumed (charset, language, direction), and tie
   that into the negotiation capabilities offered by the API

Minor issues
------------

1. The list layout used in §2, §2.2 and §2.3 is a bit confusing.
   Logically, this needs three "columns": name, type, description.
   However, type is somewhat squashed between name and description.
   Why not just reuse the presentation style from RFC8620?

2. I find the name "resource type" a bit misleading.  If this represents
   the unit of measure of the quota limits, why is it called "resource
   type" and not, e.g., "limit unit"?

3. The definition of "used" in §2 does not say which unit is used to
   measure the quota usage, and therefore what things the UnsignedInt is
   counting.

4. In §2.2, the definition of updatedProperties seems wrong:
   "If only the "used" Quota properties has changed since the old state,
   this will be the list of properties that may have changed."
   I have re-read it thrice but I am still unable to understand the
   semantics of the property from just this description.


Editorial suggestions
---------------------

   "allowing you to read and explain quota information."

s/you/a user/

Also, what does "read and explain quota information" mean exactly?

Suggestion:

   "allowing a user to obtain details about a certain quota"

---

   "Servers MUST support all properties specified for the new data types
   defined in this document."

Suggestion:

   "Servers that support the new data types defined in this document
   MUST support all the properties specified for these data types.

---

   "The same terminology is used in this document as in the core JMAP
   specification."

Suggestion:

   "This document reuses the terminology from the core JMAP
   specification."

---

   "In addition to the standard JSON data types"

Suggestion:

   "In addition to the standard JMAP data types"

---

   "The *Scope* is a String from an enumeration defined list of values,"

It's not clear to me what "enumeration defined list of value" means (the
same applies to §1.4.2)

Suggestion:

   "The *Scope* data type is used to represent the entities the Quota
   applies to.  It is defined as a String with values from the following
   set:"

---

   "Applies for this account"

Suggestion:

   "the Quota information apply to this account"

---

   "A resource type is like an unit of measure for the quota usage."

Suggestion:

   "A resource type acts as the unit of measure for the quota usage."

---

   "It should respect the JMAP ID datatype defined in section 1.2 of
   [RFC8620]"

I'd remove this as it looks redundant (§1.1 already says it).

---

   "if we reach this limit."

Suggestion:

   "if this limit is reached"

---

   "It should be higher than the warnLimit and the softLimit."

I think this can be removed entirely. The definitions for warnLimit and
softLimit are a more natural place where to establish the constraints.

---

   "A list of all the data types values that are applying to this
   quota."

Suggestion:

   "A list of all the type names (e.g., Email, Calendar, etc.) to which
   this quota applies"

---

   "to separated data types"

Suggestion:

   "to distinct data types"

---

   "The ids argument may be null to fetch all at once."

Suggestion:

   "If the ids argument is null, then all Quota records are returned"

---

   "Security and privacy considerations: this document, section 4."

It should be "section 3" instead