idnits 2.17.1 draft-ietf-jmap-quotas-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 February 2022) is 802 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP R.C. Cordier, Ed. 3 Internet-Draft Linagora Vietnam 4 Intended status: Standards Track 7 February 2022 5 Expires: 11 August 2022 7 JMAP for Quotas 8 draft-ietf-jmap-quotas-03 10 Abstract 12 This document specifies a data model for handling quotas on accounts 13 with a server using JMAP. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on 11 August 2022. 32 Copyright Notice 34 Copyright (c) 2022 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 39 license-info) in effect on the date of publication of this document. 40 Please review these documents carefully, as they describe your rights 41 and restrictions with respect to this document. Code Components 42 extracted from this document must include Revised BSD License text as 43 described in Section 4.e of the Trust Legal Provisions and are 44 provided without warranty as described in the Revised BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 49 1.1. Notational conventions . . . . . . . . . . . . . . . . . 2 50 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.3. Addition to the capabilities object . . . . . . . . . . . 3 52 1.3.1. urn::ietf::params::jmap::quota . . . . . . . . . . . 3 53 1.4. Data types . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.4.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.4.2. ResourceType . . . . . . . . . . . . . . . . . . . . 4 56 1.5. Push . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.1. Quota/get . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.2. Quota/changes . . . . . . . . . . . . . . . . . . . . . . 5 60 2.3. Quota/query . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.4. Quota/queryChanges . . . . . . . . . . . . . . . . . . . 6 62 2.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.5.1. Fetching quotas . . . . . . . . . . . . . . . . . . . 6 64 2.5.2. Requesting latest quota changes . . . . . . . . . . . 7 65 3. Security considerations . . . . . . . . . . . . . . . . . . . 8 66 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 67 4.1. JMAP Capability Registration for "quota" . . . . . . . . 8 68 5. Normative References . . . . . . . . . . . . . . . . . . . . 8 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 71 1. Introduction 73 JMAP ([RFC8620] - JSON Meta Application Protocol) is a generic 74 protocol for synchronising data, such as mails, calendars or 75 contacts, between a client and a server. It is optimised for mobile 76 and web environments, and aims to provide a consistent interface to 77 different data types. 79 This specification defines a data model for handling quotas over 80 JMAP, allowing you to read and explain quota information. 82 This specification does not address quota administration, which 83 should be handled by other means. 85 1.1. Notational conventions 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14 [RFC2119] [RFC8174] when, and only when, they appear in all 91 capitals, as shown here. 93 Type signatures, examples and property descriptions in this document 94 follow the conventions established in section 1.1 of [RFC8620]. Data 95 types defined in the core specification are also used in this 96 document. 98 Servers MUST support all properties specified for the new data types 99 defined in this document. 101 1.2. Terminology 103 The same terminology is used in this document as in the core JMAP 104 specification. 106 The term Quota (with that specific capitalization) is used to refer 107 to the data type defined in this document and instance of that data 108 type. 110 1.3. Addition to the capabilities object 112 The capabilities object is returned as part of the JMAP Session 113 object; see [RFC8620], section 2. 115 This document defines one additional capability URI. 117 1.3.1. urn::ietf::params::jmap::quota 119 This represents support for the Quota data type and associated API 120 methods. Servers supporting this specification MUST add a property 121 called urn::ietf::params::jmap::quota to the capabilities object. 123 The value of this property is an empty object in both the JMAP 124 session capabilities property and an account's accountCapabilities 125 property. 127 1.4. Data types 129 In addition to the standard JSON data types, a couple of additional 130 data types are common to the definition of Quota objects and 131 properties. 133 1.4.1. Scope 135 The *Scope* is a String from an enumeration defined list of values, 136 handled by the server. 138 It explains the entities this value applies to. Values for the 139 *Scope* are: 141 * account: Applies for this account 143 * domain: All accounts of this domain share this part of the quota 145 * global: All accounts of this server share this part of the quota 147 1.4.2. ResourceType 149 The *ResourceType* is a String from an enumeration defined list of 150 values, handled by the server. 152 A resource type is like an unit of measure for the quota usage. 153 Values for the *ResourceType* are: 155 * count: The quota is measured in number of data type objects. For 156 example, a quota can have a limit of 50 Mail objects. 158 * octets: The quota is measured in size (in octets). For example, a 159 quota can have a limit of 25000 octets. 161 1.5. Push 163 Servers MUST support the JMAP push mechanisms, as specified in 164 [RFC8620] Section 7, to receive notifications when the state changes 165 for the Quota type defined in this specification. 167 2. Quota 169 The quota is an object that displays the limit set to an account 170 usage as well as the current usage in regard to that limit. 172 The quota object MUST contain the following fields: 174 * *id*: Id The unique identifier for this object. It should respect 175 the JMAP ID datatype defined in section 1.2 of [RFC8620] 177 * *resourceType*: ResourceType The resource type of the quota. 179 * *used*: UnsignedInt The current usage of the defined quota. 180 Computation of this value is handled by the server. 182 * *limit*: UnsignedInt The hard limit set by this quota. Objects in 183 scope may not be created or updated if we reach this limit. It 184 should be higher than the warnLimit and the softLimit. 186 * *scope*: Scope The Scope of this quota. 188 * *name*: String The name of the quota object. Useful for managing 189 quotas and use queries for searching. 191 * *datatypes*: String[] A list of all the data types values that are 192 applying to this quota. This allows to assign quotas to separated 193 or shared data types. This MAY include data types the client does 194 not recognise. Clients MUST ignore any unknown data type in the 195 list. 197 The quota object MAY contain the following field: 199 * *warnLimit*: UnsignedInt|null The warn limit set by this quota 200 object. It can be used to send a warning to an entity about to 201 reach the hard limit soon, but with no action taken yet. If set, 202 it should be lower than the softLimit and the limit. 204 * *softLimit*: UnsignedInt|null The soft limit set by this quota 205 object. It can be used to still allow some operations, but 206 refusing some others. What is allowed or not is up to the server. 207 If set, it should be higher than the warnLimit but lower than the 208 limit. 210 * *description*: String|null Arbitrary free, human readable, 211 description of this quota. Might be used to explain where the 212 limit comes from and explain the entities and data types this 213 quota applies to. 215 2.1. Quota/get 217 Standard "/get" method as described in [RFC8620] section 5.1. The 218 ids argument may be null to fetch all at once. 220 2.2. Quota/changes 222 Standard "/changes" method as described in [RFC8620] section 5.2 but 223 with one extra argument to the response: 225 * *updatedProperties*: String[]|null If only the "used" Quota 226 properties has changed since the old state, this will be the list 227 of properties that may have changed. If the server is unable to 228 tell if only "used" has changed, it MUST just be null. 230 Since "used" frequently changes but other properties are generally 231 only changed rarely, the server can help the client optimise data 232 transfer by keeping track of changes to Quota usage separate from 233 other state changes. The updatedProperties array may be used 234 directly via a back-reference in a subsequent Quota/get call in the 235 same request, so only these properties are returned if nothing else 236 has changed. 238 Servers MAY decide to add other properties to the list that they 239 judge changing frequently. 241 2.3. Quota/query 243 This is a standard "/query" method as described in [RFC8620], 244 Section 5.5. 246 A *FilterCondition* object has the following properties, any of which 247 may be omitted: 249 * *name*: String The Quota _name_ property contains the given 250 string. 252 * *scopes*: Scope[] The Quota _scope_ property must be in this list 253 to match the condition. 255 * *resourceTypes*: ResourceType[] The Quota _resourceType_ property 256 must be in this list to match the condition. 258 * *datatypes*: String[] The Quota _datatypes_ property must contain 259 the elements in this list to match the condition. 261 A Quota object matches the FilterCondition if and only if all of the 262 given conditions match. If zero properties are specified, it is 263 automatically true for all objects. 265 The following Quota properties MUST be supported for sorting: 267 * *name* 269 * *used* 271 2.4. Quota/queryChanges 273 This is a standard "/queryChanges" method as described in [RFC8620], 274 Section 5.6. 276 2.5. Examples 278 2.5.1. Fetching quotas 280 Request fetching all quotas related to an account : 282 [[ "Quota/get", { 283 "accountId": "u33084183", 284 "ids": null 285 }, "0" ]] 287 With response : 289 [[ "Quota/get", { 290 "accountId": "u33084183", 291 "state": "78540", 292 "list": [{ 293 "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", 294 "resourceType": "count", 295 "used": 1056, 296 "warnLimit": 1600, 297 "softLimit": 1800, 298 "limit": 2000, 299 "scope": "account", 300 "name": "bob@example.com", 301 "description": "Personal account usage", 302 "datatypes" : [ "Mail", "Calendar", "Contact" ] 303 }, { 304 "id": "3b06df0e-3761-4s74-a92f-74dcc963501x", 305 "resourceType": "size", 306 ... 307 }, ...], 308 "notFound": [] 309 }, "0" ]] 311 2.5.2. Requesting latest quota changes 313 Request fetching the changes for a specific quota: 315 [[ "Quota/changes", { 316 "accountId": "u33084183", 317 "sinceState": "10824", 318 "maxChanges": 20 319 }, "0" ], 320 [ "Quota/get", { 321 "accountId": "u33084183", 322 "#ids": { 323 "resultOf": "0", 324 "name": "Quota/changes", 325 "path": "/updated" 326 }, 327 "#properties": { 328 "resultOf": "0", 329 "name": "Quota/changes", 330 "path": "/updatedProperties" 331 } 332 }, "1" ]] 334 With response: 336 [[ "Quota/changes", { 337 "accountId": "u33084183", 338 "oldState": "10824", 339 "newState": "10826", 340 "hasMoreChanges": false, 341 "created": [], 342 "updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"], 343 "destroyed": [] 344 }, "0" ], 345 [ "Quota/get", { 346 "accountId": "u33084183", 347 "state": "10826", 348 "list": [{ 349 "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", 350 "used": 1246 351 }], 352 "notFound": [] 353 }, "1" ]] 355 3. Security considerations 357 All security considerations of JMAP ([RFC8620]) apply to this 358 specification. 360 4. IANA Considerations 362 4.1. JMAP Capability Registration for "quota" 364 IANA will register the "quota" JMAP Capability as follows: 366 Capability Name: urn:ietf:params:jmap:quota 368 Specification document: this document 370 Intended use: common 372 Change Controller: IETF 374 Security and privacy considerations: this document, section 4. 376 5. Normative References 378 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 379 Requirement Levels", BCP 14, RFC 2119, 380 DOI 10.17487/RFC2119, March 1997, 381 . 383 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 384 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 385 May 2017, . 387 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 388 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 389 2019, . 391 Author's Address 393 René Cordier (editor) 394 Linagora Vietnam 395 5 Dien Bien Phu 396 Hanoi 397 10000 398 Vietnam 400 Email: rcordier@linagora.com 401 URI: https://linagora.vn