idnits 2.17.1 draft-ietf-jmap-quotas-02.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 (23 August 2021) is 970 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 23 August 2021 5 Expires: 24 February 2022 7 JMAP for Quotas 8 draft-ietf-jmap-quotas-02 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 24 February 2022. 32 Copyright Notice 34 Copyright (c) 2021 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 Simplified BSD License text 43 as described in Section 4.e of the Trust Legal Provisions and are 44 provided without warranty as described in the Simplified 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 . . . . . . . . . . . . . . . . . . . 7 62 2.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 63 2.5.1. Fetching quotas . . . . . . . . . . . . . . . . . . . 7 64 2.5.2. Requesting latest quota changes . . . . . . . . . . . 7 65 3. Security considerations . . . . . . . . . . . . . . . . . . . 8 66 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 4.1. JMAP Capability Registration for "quota" . . . . . . . . 9 68 5. Normative References . . . . . . . . . . . . . . . . . . . . 9 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. The value of this property in the JMAP session capabilities 121 property is an empty object. 123 The value of this property in an account's accountCapabilities 124 property is an object that MUST contain the following information on 125 server capabilities and permissions for that account: 127 * *quotaIds:* "Id[]" (default: "[]") A list of quota ids bound to 128 that account, or "[]" if that account has no quota restrictions. 130 1.4. Data types 132 In addition to the standard JSON data types, a couple of additional 133 data types are common to the definition of Quota objects and 134 properties. 136 1.4.1. Scope 138 The *Scope* is a "String" from an enumeration defined list of values, 139 handled by the server. 141 It explains the entities this value applies to. Some custom 142 specifications might provide some additional values. If the client 143 does not specify custom scope specifications in the "using" parameter 144 of the request, the server should respond the JSON value "null", 145 instead of answering a scope value that the client does not support. 146 Standard values are: 148 * "account": Applies for this account 150 * "domain": All accounts of this domain share this part of the quota 152 * "global": All accounts of this server share this part of the quota 154 1.4.2. ResourceType 156 The *ResourceType* is a "String" from an enumeration defined list of 157 values, handled by the server. 159 A resource type is like an unit of measure for the quota usage. Some 160 custom specifications might provide some additional values. If the 161 client does not specify custom resource type specifications in the 162 "using" parameter of the request, the server should respond the JSON 163 value "null", instead of answering a resource type value that the 164 client does not support. Standard values are: 166 * "count": The quota is measured in number of data type objects. 167 For example, a quota can have a limit of 50 "Mail" objects. 169 * "size": The quota is measured in size (in "bytes"). For example, 170 a quota can have a limit of 25000 "bytes". 172 1.5. Push 174 Servers MUST support the JMAP push mechanisms, as specified in 175 [RFC8620] Section 7, to receive notifications when the state changes 176 for the Quota type defined in this specification. 178 2. Quota 180 The quota is an object that displays the limit set to an account 181 usage as well as the current usage in regard to that limit. 183 The quota object MUST contain the following fields: 185 * *id*: "Id" The unique identifier for this object. It should 186 respect the JMAP ID datatype defined in section 1.2 of [RFC8620] 188 * *resourceType*: "ResourceType" The resource type of the quota. 190 * *used*: "UnsignedInt" The current usage of the defined quota. 191 Computation of this value is handled by the server. 193 * *limit*: "UnsignedInt" The hard limit set by this quota object. 194 No more outgoing and ingoing objects should be allowed if we reach 195 this limit. It should be higher than the "warnLimit" and the 196 "softLimit". 198 * *scope*: "Scope" The "Scope" of this quota. 200 * *name*: "String" The name of the quota object. Useful for 201 managing quotas and use queries for searching. 203 * *datatypes*: "String[]" A list of all the data types values that 204 are applying to this quota. This allows to assign quotas to 205 separated or shared data types. This MAY include data types the 206 client does not recognise. Clients MUST ignore any unknown data 207 type in the list. 209 The quota object MAY contain the following field: 211 * *warnLimit*: "UnsignedInt|null" The warn limit set by this quota 212 object. It can be used to send a warning to an entity about to 213 reach the hard limit soon, but with no action taken yet. If set, 214 it should be lower than the "softLimit" and the "limit". 216 * *softLimit*: "UnsignedInt|null" The soft limit set by this quota 217 object. It can be used to still allow some operations, but 218 refusing some others. What is allowed or not is up to the server. 219 If set, it should be higher than the "warnLimit" but lower than 220 the "limit". 222 * *description*: "String|null" Arbitrary free, human readable, 223 description of this quota. Might be used to explain where the 224 limit comes from and explain the entities and data types this 225 quota applies to. 227 2.1. Quota/get 229 Standard "/get" method as described in [RFC8620] section 5.1. The 230 ids argument may be "null" to fetch all at once. 232 2.2. Quota/changes 234 Standard "/changes" method as described in [RFC8620] section 5.2 but 235 with one extra argument to the response: 237 * *updatedProperties*: "String[]|null" If only the "used" Quota 238 properties has changed since the old state, this will be the list 239 of properties that may have changed. If the server is unable to 240 tell if only "used" has changed, it MUST just be null. 242 Since "used" frequently changes but other properties are generally 243 only changed rarely, the server can help the client optimise data 244 transfer by keeping track of changes to Quota usage separate from 245 other state changes. The updatedProperties array may be used 246 directly via a back-reference in a subsequent Quota/get call in the 247 same request, so only these properties are returned if nothing else 248 has changed. 250 Servers MAY decide to add other properties to the list that they 251 judge changing frequently. 253 2.3. Quota/query 255 This is a standard "/query" method as described in [RFC8620], 256 Section 5.5. 258 A *FilterCondition* object has the following properties, any of which 259 may be omitted: 261 * *name*: "String" The Quota _name_ property contains the given 262 string. 264 * *scopes*: "Scope[]" The Quota _scope_ property must be in this 265 list to match the condition. 267 * *resourceTypes*: "ResourceType[]" The Quota _resourceType_ 268 property must be in this list to match the condition. 270 * *datatypes*: "String[]" The Quota _datatypes_ property must 271 contain the elements in this list to match the condition. 273 A Quota object matches the FilterCondition if and only if all of the 274 given conditions match. If zero properties are specified, it is 275 automatically true for all objects. 277 The following Quota properties MUST be supported for sorting: 279 * *name* 281 * *used* 283 2.4. Quota/queryChanges 285 This is a standard "/queryChanges" method as described in [RFC8620], 286 Section 5.6. 288 2.5. Examples 290 2.5.1. Fetching quotas 292 Request fetching all quotas related to an account : 294 [[ "Quota/get", { 295 "accountId": "u33084183", 296 "ids": null 297 }, "0" ]] 299 With response : 301 [[ "Quota/get", { 302 "accountId": "u33084183", 303 "state": "78540", 304 "list": [{ 305 "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", 306 "resourceType": "count", 307 "used": 1056, 308 "warnLimit": 1600, 309 "softLimit": 1800, 310 "limit": 2000, 311 "scope": "account", 312 "name": "bob@example.com", 313 "description": "Personal account usage", 314 "datatypes" : [ "Mail", "Calendar", "Contact" ] 315 }, { 316 "id": "3b06df0e-3761-4s74-a92f-74dcc963501x", 317 "resourceType": "size", 318 ... 319 }, ...], 320 "notFound": [] 321 }, "0" ]] 323 2.5.2. Requesting latest quota changes 325 Request fetching the changes for a specific quota: 327 [[ "Quota/changes", { 328 "accountId": "u33084183", 329 "sinceState": "10824", 330 "maxChanges": 20 331 }, "0" ], 332 [ "Quota/get", { 333 "accountId": "u33084183", 334 "#ids": { 335 "resultOf": "0", 336 "name": "Quota/changes", 337 "path": "/updated" 338 }, 339 "#properties": { 340 "resultOf": "0", 341 "name": "Quota/changes", 342 "path": "/updatedProperties" 343 } 344 }, "1" ]] 346 With response: 348 [[ "Quota/changes", { 349 "accountId": "u33084183", 350 "oldState": "10824", 351 "newState": "10826", 352 "hasMoreChanges": false, 353 "created": [], 354 "updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"], 355 "destroyed": [] 356 }, "0" ], 357 [ "Quota/get", { 358 "accountId": "u33084183", 359 "state": "10826", 360 "list": [{ 361 "id": "2a06df0d-9865-4e74-a92f-74dcc814270e", 362 "used": 1246 363 }], 364 "notFound": [] 365 }, "1" ]] 367 3. Security considerations 369 All security considerations of JMAP ([RFC8620]) apply to this 370 specification. 372 4. IANA Considerations 374 4.1. JMAP Capability Registration for "quota" 376 IANA will register the "quota" JMAP Capability as follows: 378 Capability Name: "urn:ietf:params:jmap:quota" 380 Specification document: this document 382 Intended use: common 384 Change Controller: IETF 386 Security and privacy considerations: this document, section 4. 388 5. Normative References 390 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 391 Requirement Levels", BCP 14, RFC 2119, 392 DOI 10.17487/RFC2119, March 1997, 393 . 395 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 396 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 397 May 2017, . 399 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 400 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 401 2019, . 403 Author's Address 405 René Cordier (editor) 406 Linagora Vietnam 407 5 Dien Bien Phu 408 Hanoi 409 10000 410 Vietnam 412 Email: rcordier@linagora.com 413 URI: https://linagora.vn