Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8620

The JSON Meta Application Protocol (JMAP)

Pages: 90
Proposed Standard
Errata
Part 3 of 5 – Pages 29 to 58
First   Prev   Next

Top   ToC   RFC8620 - Page 29   prevText

5. Standard Methods and Naming Convention

JMAP provides a uniform interface for creating, retrieving, updating, and deleting objects of a particular type. For a "Foo" data type, records of that type would be fetched via a "Foo/get" call and modified via a "Foo/set" call. Delta updates may be fetched via a "Foo/changes" call. These methods all follow a standard format as described below. Some types may not have all these methods. Specifications defining types MUST specify which methods are available for the type.

5.1. /get

Objects of type Foo are fetched via a call to "Foo/get". It takes the following arguments: o accountId: "Id" The id of the account to use. o ids: "Id[]|null" The ids of the Foo objects to return. If null, then *all* records of the data type are returned, if this is supported for that data type and the number of records does not exceed the "maxObjectsInGet" limit. o properties: "String[]|null" If supplied, only the properties listed in the array are returned for each Foo object. If null, all properties of the object are returned. The id property of the object is *always* returned, even if not explicitly requested. If an invalid property is requested, the call MUST be rejected with an "invalidArguments" error. The response has the following arguments: o accountId: "Id" The id of the account used for the call.
Top   ToC   RFC8620 - Page 30
   o  state: "String"

      A (preferably short) string representing the state on the server
      for *all* the data of this type in the account (not just the
      objects returned in this call).  If the data changes, this string
      MUST change.  If the Foo data is unchanged, servers SHOULD return
      the same state string on subsequent requests for this data type.
      When a client receives a response with a different state string to
      a previous call, it MUST either throw away all currently cached
      objects for the type or call "Foo/changes" to get the exact
      changes.

   o  list: "Foo[]"

      An array of the Foo objects requested.  This is the *empty array*
      if no objects were found or if the "ids" argument passed in was
      also an empty array.  The results MAY be in a different order to
      the "ids" in the request arguments.  If an identical id is
      included more than once in the request, the server MUST only
      include it once in either the "list" or the "notFound" argument of
      the response.

   o  notFound: "Id[]"

      This array contains the ids passed to the method for records that
      do not exist.  The array is empty if all requested ids were found
      or if the "ids" argument passed in was either null or an empty
      array.

   The following additional error may be returned instead of the "Foo/
   get" response:

   "requestTooLarge": The number of ids requested by the client exceeds
   the maximum number the server is willing to process in a single
   method call.

5.2. /changes

When the state of the set of Foo records in an account changes on the server (whether due to creation, updates, or deletion), the "state" property of the "Foo/get" response will change. The "Foo/changes" method allows a client to efficiently update the state of its Foo cache to match the new state on the server. It takes the following arguments: o accountId: "Id" The id of the account to use.
Top   ToC   RFC8620 - Page 31
   o  sinceState: "String"

      The current state of the client.  This is the string that was
      returned as the "state" argument in the "Foo/get" response.  The
      server will return the changes that have occurred since this
      state.

   o  maxChanges: "UnsignedInt|null"

      The maximum number of ids to return in the response.  The server
      MAY choose to return fewer than this value but MUST NOT return
      more.  If not given by the client, the server may choose how many
      to return.  If supplied by the client, the value MUST be a
      positive integer greater than 0.  If a value outside of this range
      is given, the server MUST reject the call with an
      "invalidArguments" error.

   The response has the following arguments:

   o  accountId: "Id"

      The id of the account used for the call.

   o  oldState: "String"

      This is the "sinceState" argument echoed back; it's the state from
      which the server is returning changes.

   o  newState: "String"

      This is the state the client will be in after applying the set of
      changes to the old state.

   o  hasMoreChanges: "Boolean"

      If true, the client may call "Foo/changes" again with the
      "newState" returned to get further updates.  If false, "newState"
      is the current server state.

   o  created: "Id[]"

      An array of ids for records that have been created since the old
      state.

   o  updated: "Id[]"

      An array of ids for records that have been updated since the old
      state.
Top   ToC   RFC8620 - Page 32
   o  destroyed: "Id[]"

      An array of ids for records that have been destroyed since the old
      state.

   If a record has been created AND updated since the old state, the
   server SHOULD just return the id in the "created" list but MAY return
   it in the "updated" list as well.

   If a record has been updated AND destroyed since the old state, the
   server SHOULD just return the id in the "destroyed" list but MAY
   return it in the "updated" list as well.

   If a record has been created AND destroyed since the old state, the
   server SHOULD remove the id from the response entirely.  However, it
   MAY include it in just the "destroyed" list or in both the
   "destroyed" and "created" lists.

   If a "maxChanges" is supplied, or set automatically by the server,
   the server MUST ensure the number of ids returned across "created",
   "updated", and "destroyed" does not exceed this limit.  If there are
   more changes than this between the client's state and the current
   server state, the server SHOULD generate an update to take the client
   to an intermediate state, from which the client can continue to call
   "Foo/changes" until it is fully up to date.  If it is unable to
   calculate an intermediate state, it MUST return a
   "cannotCalculateChanges" error response instead.

   When generating intermediate states, the server may choose how to
   divide up the changes.  For many types, it will provide a better user
   experience to return the more recent changes first, as this is more
   likely to be what the user is most interested in.  The client can
   then continue to page in the older changes while the user is viewing
   the newer data.  For example, suppose a server went through the
   following states:

                           A -> B -> C -> D -> E

   And a client asks for changes from state "B".  The server might first
   get the ids of records created, updated, or destroyed between states
   D and E, returning them with:

                           state: "B-D-E"
                           hasMoreChanges: true
Top   ToC   RFC8620 - Page 33
   The client will then ask for the change from state "B-D-E", and the
   server can return the changes between states C and D, returning:

                           state: "B-C-E"
                           hasMoreChanges: true

   Finally, the client will request the changes from "B-C-E", and the
   server can return the changes between states B and C, returning:

                           state: "E"
                           hasMoreChanges: false

   Should the state on the server be modified in the middle of all this
   (to "F"), the server still does the same, but now when the update to
   state "E" is returned, it would indicate that it still has more
   changes for the client to fetch.

   Where multiple changes to a record are split across different
   intermediate states, the server MUST NOT return a record as created
   after a response that deems it as updated or destroyed, and it MUST
   NOT return a record as destroyed before a response that deems it as
   created or updated.  The server may have to coalesce multiple changes
   to a record to satisfy this requirement.

   The following additional errors may be returned instead of the "Foo/
   changes" response:

   "cannotCalculateChanges": The server cannot calculate the changes
   from the state string given by the client.  Usually, this is due to
   the client's state being too old or the server being unable to
   produce an update to an intermediate state when there are too many
   updates.  The client MUST invalidate its Foo cache.

   Maintaining state to allow calculation of "Foo/changes" can be
   expensive for the server, but always returning
   "cannotCalculateChanges" severely increases network traffic and
   resource usage for the client.  To allow efficient sync, servers
   SHOULD be able to calculate changes from any state string that was
   given to a client within the last 30 days (but of course may support
   calculating updates from states older than this).
Top   ToC   RFC8620 - Page 34

5.3. /set

Modifying the state of Foo objects on the server is done via the "Foo/set" method. This encompasses creating, updating, and destroying Foo records. This allows the server to sort out ordering and dependencies that may exist if doing multiple operations at once (for example, to ensure there is always a minimum number of a certain record type). The "Foo/set" method takes the following arguments: o accountId: "Id" The id of the account to use. o ifInState: "String|null" This is a state string as returned by the "Foo/get" method (representing the state of all objects of this type in the account). If supplied, the string must match the current state; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, any changes will be applied to the current state. o create: "Id[Foo]|null" A map of a *creation id* (a temporary id set by the client) to Foo objects, or null if no objects are to be created. The Foo object type definition may define default values for properties. Any such property may be omitted by the client. The client MUST omit any properties that may only be set by the server (for example, the "id" property on most object types). o update: "Id[PatchObject]|null" A map of an id to a Patch object to apply to the current Foo object with that id, or null if no objects are to be updated. A *PatchObject* is of type "String[*]" and represents an unordered set of patches. The keys are a path in JSON Pointer format [RFC6901], with an implicit leading "/" (i.e., prefix each key with "/" before applying the JSON Pointer evaluation algorithm). All paths MUST also conform to the following restrictions; if there is any violation, the update MUST be rejected with an "invalidPatch" error:
Top   ToC   RFC8620 - Page 35
      *  The pointer MUST NOT reference inside an array (i.e., you MUST
         NOT insert/delete from an array; the array MUST be replaced in
         its entirety instead).

      *  All parts prior to the last (i.e., the value after the final
         slash) MUST already exist on the object being patched.

      *  There MUST NOT be two patches in the PatchObject where the
         pointer of one is the prefix of the pointer of the other, e.g.,
         "alerts/1/offset" and "alerts".

      The value associated with each pointer determines how to apply
      that patch:

      *  If null, set to the default value if specified for this
         property; otherwise, remove the property from the patched
         object.  If the key is not present in the parent, this a no-op.

      *  Anything else: The value to set for this property (this may be
         a replacement or addition to the object being patched).

      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.

      This patch definition is designed such that an entire Foo object
      is also a valid PatchObject.  The client may choose to optimise
      network usage by just sending the diff or may send the whole
      object; the server processes it the same either way.

   o  destroy: "Id[]|null"

      A list of ids for Foo objects to permanently delete, or null if no
      objects are to be destroyed.

   Each creation, modification, or destruction of an object is
   considered an atomic unit.  It is permissible for the server to
   commit changes to some objects but not others; however, it MUST NOT
   only commit part of an update to a single record (e.g., update a
   "name" property but not a "count" property, if both are supplied in
   the update object).

   The final state MUST be valid after the "Foo/set" is finished;
   however, the server may have to transition through invalid
   intermediate states (not exposed to the client) while processing the
   individual create/update/destroy requests.  For example, suppose
   there is a "name" property that must be unique.  A single method call
Top   ToC   RFC8620 - Page 36
   could rename an object A => B and simultaneously rename another
   object B => A.  If the final state is valid, this is allowed.
   Otherwise, each creation, modification, or destruction of an object
   should be processed sequentially and accepted/rejected based on the
   current server state.

   If a create, update, or destroy is rejected, the appropriate error
   MUST be added to the notCreated/notUpdated/notDestroyed property of
   the response, and the server MUST continue to the next create/update/
   destroy.  It does not terminate the method.

   If an id given cannot be found, the update or destroy MUST be
   rejected with a "notFound" set error.

   The server MAY skip an update (rejecting it with a "willDestroy"
   SetError) if that object is destroyed in the same /set request.

   Some records may hold references to other records (foreign keys).
   That reference may be set (via create or update) in the same request
   as the referenced record is created.  To do this, the client refers
   to the new record using its creation id prefixed with a "#".  The
   order of the method calls in the request by the client MUST be such
   that the record being referenced is created in the same or an earlier
   call.  Thus, the server never has to look ahead.  Instead, while
   processing a request, the server MUST keep a simple map for the
   duration of the request of creation id to record id for each newly
   created record, so it can substitute in the correct value if
   necessary in later method calls.  In the case of records with
   references to the same type, the server MUST order the creates and
   updates within a single method call so that creates happen before
   their creation ids are referenced by another create/update/destroy in
   the same call.

   Creation ids are not scoped by type but are a single map for all
   types.  A client SHOULD NOT reuse a creation id anywhere in the same
   API request.  If a creation id is reused, the server MUST map the
   creation id to the most recently created item with that id.  To allow
   easy proxying of API requests, an initial set of creation id to real
   id values may be passed with a request (see "The Request Object",
   Section 3.3) and the final state of the map passed out with the
   response (see "The Response Object", Section 3.4).

   The response has the following arguments:

   o  accountId: "Id"

      The id of the account used for the call.
Top   ToC   RFC8620 - Page 37
   o  oldState: "String|null"

      The state string that would have been returned by "Foo/get" before
      making the requested changes, or null if the server doesn't know
      what the previous state string was.

   o  newState: "String"

      The state string that will now be returned by "Foo/get".

   o  created: "Id[Foo]|null"

      A map of the creation id to an object containing any properties of
      the created Foo object that were not sent by the client.  This
      includes all server-set properties (such as the "id" in most
      object types) and any properties that were omitted by the client
      and thus set to a default by the server.

      This argument is null if no Foo objects were successfully created.

   o  updated: "Id[Foo|null]|null"

      The keys in this map are the ids of all Foos that were
      successfully updated.

      The value for each id is a Foo object containing any property that
      changed in a way *not* explicitly requested by the PatchObject
      sent to the server, or null if none.  This lets the client know of
      any changes to server-set or computed properties.

      This argument is null if no Foo objects were successfully updated.

   o  destroyed: "Id[]|null"

      A list of Foo ids for records that were successfully destroyed, or
      null if none.

   o  notCreated: "Id[SetError]|null"

      A map of the creation id to a SetError object for each record that
      failed to be created, or null if all successful.

   o  notUpdated: "Id[SetError]|null"

      A map of the Foo id to a SetError object for each record that
      failed to be updated, or null if all successful.
Top   ToC   RFC8620 - Page 38
   o  notDestroyed: "Id[SetError]|null"

      A map of the Foo id to a SetError object for each record that
      failed to be destroyed, or null if all successful.

   A *SetError* object has the following properties:

   o  type: "String"

      The type of error.

   o  description: "String|null"

      A description of the error to help with debugging that includes an
      explanation of what the problem was.  This is a non-localised
      string and is not intended to be shown directly to end users.

   The following SetError types are defined and may be returned for set
   operations on any record type where appropriate:

   o  "forbidden": (create; update; destroy).  The create/update/destroy
      would violate an ACL or other permissions policy.

   o  "overQuota": (create; update).  The create would exceed a server-
      defined limit on the number or total size of objects of this type.

   o  "tooLarge": (create; update).  The create/update would result in
      an object that exceeds a server-defined limit for the maximum size
      of a single object of this type.

   o  "rateLimit": (create).  Too many objects of this type have been
      created recently, and a server-defined rate limit has been
      reached.  It may work if tried again later.

   o  "notFound": (update; destroy).  The id given to update/destroy
      cannot be found.

   o  "invalidPatch": (update).  The PatchObject given to update the
      record was not a valid patch (see the patch description).

   o  "willDestroy": (update).  The client requested that an object be
      both updated and destroyed in the same /set request, and the
      server has decided to therefore ignore the update.
Top   ToC   RFC8620 - Page 39
   o  "invalidProperties": (create; update).  The record given is
      invalid in some way.  For example:

      *  It contains properties that are invalid according to the type
         specification of this record type.

      *  It contains a property that may only be set by the server
         (e.g., "id") and is different to the current value.  Note, to
         allow clients to pass whole objects back, it is not an error to
         include a server-set property in an update as long as the value
         is identical to the current value on the server.

      *  There is a reference to another record (foreign key), and the
         given id does not correspond to a valid record.

      The SetError object SHOULD also have a property called
      "properties" of type "String[]" that lists *all* the properties
      that were invalid.

      Individual methods MAY specify more specific errors for certain
      conditions that would otherwise result in an invalidProperties
      error.  If the condition of one of these is met, it MUST be
      returned instead of the invalidProperties error.

   o  "singleton": (create; destroy).  This is a singleton type, so you
      cannot create another one or destroy the existing one.

   Other possible SetError types MAY be given in specific method
   descriptions.  Other properties MAY also be present on the SetError
   object, as described in the relevant methods.

   The following additional errors may be returned instead of the "Foo/
   set" response:

   "requestTooLarge": The total number of objects to create, update, or
   destroy exceeds the maximum number the server is willing to process
   in a single method call.

   "stateMismatch": An "ifInState" argument was supplied, and it does
   not match the current state.
Top   ToC   RFC8620 - Page 40

5.4. /copy

The only way to move Foo records *between* two different accounts is to copy them using the "Foo/copy" method; once the copy has succeeded, delete the original. The "onSuccessDestroyOriginal" argument allows you to try to do this in one method call; however, note that the two different actions are not atomic, so it is possible for the copy to succeed but the original not to be destroyed for some reason. The copy is conceptually in three phases: 1. Reading the current values from the "from" account. 2. Writing the new copies to the other account. 3. Destroying the originals in the "from" account, if requested. Data may change in between phases due to concurrent requests. The "Foo/copy" method takes the following arguments: o fromAccountId: "Id" The id of the account to copy records from. o ifFromInState: "String|null" This is a state string as returned by the "Foo/get" method. If supplied, the string must match the current state of the account referenced by the fromAccountId when reading the data to be copied; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, the data will be read from the current state. o accountId: "Id" The id of the account to copy records to. This MUST be different to the "fromAccountId". o ifInState: "String|null" This is a state string as returned by the "Foo/get" method. If supplied, the string must match the current state of the account referenced by the accountId; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, any changes will be applied to the current state.
Top   ToC   RFC8620 - Page 41
   o  create: "Id[Foo]"

      A map of the *creation id* to a Foo object.  The Foo object MUST
      contain an "id" property, which is the id (in the fromAccount) of
      the record to be copied.  When creating the copy, any other
      properties included are used instead of the current value for that
      property on the original.

   o  onSuccessDestroyOriginal: "Boolean" (default: false)

      If true, an attempt will be made to destroy the original records
      that were successfully copied: after emitting the "Foo/copy"
      response, but before processing the next method, the server MUST
      make a single call to "Foo/set" to destroy the original of each
      successfully copied record; the output of this is added to the
      responses as normal, to be returned to the client.

   o  destroyFromIfInState: "String|null"

      This argument is passed on as the "ifInState" argument to the
      implicit "Foo/set" call, if made at the end of this request to
      destroy the originals that were successfully copied.

   Each record copy is considered an atomic unit that may succeed or
   fail individually.

   The response has the following arguments:

   o  fromAccountId: "Id"

      The id of the account records were copied from.

   o  accountId: "Id"

      The id of the account records were copied to.

   o  oldState: "String|null"

      The state string that would have been returned by "Foo/get" on the
      account records that were copied to before making the requested
      changes, or null if the server doesn't know what the previous
      state string was.

   o  newState: "String"

      The state string that will now be returned by "Foo/get" on the
      account records were copied to.
Top   ToC   RFC8620 - Page 42
   o  created: "Id[Foo]|null"

      A map of the creation id to an object containing any properties of
      the copied Foo object that are set by the server (such as the "id"
      in most object types; note, the id is likely to be different to
      the id of the object in the account it was copied from).

      This argument is null if no Foo objects were successfully copied.

   o  notCreated: "Id[SetError]|null"

      A map of the creation id to a SetError object for each record that
      failed to be copied, or null if none.

   The SetError may be any of the standard set errors returned for a
   create or update.  In addition, the following SetError is defined:

   "alreadyExists": The server forbids duplicates, and the record
   already exists in the target account.  An "existingId" property of
   type "Id" MUST be included on the SetError object with the id of the
   existing record.

   The following additional errors may be returned instead of the "Foo/
   copy" response:

   "fromAccountNotFound": The "fromAccountId" does not correspond to a
   valid account.

   "fromAccountNotSupportedByMethod": The "fromAccountId" given
   corresponds to a valid account, but the account does not support this
   data type.

   "stateMismatch": An "ifInState" argument was supplied and it does not
   match the current state, or an "ifFromInState" argument was supplied
   and it does not match the current state in the from account.

5.5. /query

For data sets where the total amount of data is expected to be very small, clients can just fetch the complete set of data and then do any sorting/filtering locally. However, for large data sets (e.g., multi-gigabyte mailboxes), the client needs to be able to search/sort/window the data type on the server. A query on the set of Foos in an account is made by calling "Foo/ query". This takes a number of arguments to determine which records to include, how they should be sorted, and which part of the result
Top   ToC   RFC8620 - Page 43
   should be returned (the full list may be *very* long).  The result is
   returned as a list of Foo ids.

   A call to "Foo/query" takes the following arguments:

   o  accountId: "Id"

      The id of the account to use.

   o  filter: "FilterOperator|FilterCondition|null"

      Determines the set of Foos returned in the results.  If null, all
      objects in the account of this type are included in the results.
      A *FilterOperator* object has the following properties:

      *  operator: "String"

         This MUST be one of the following strings:

         +  "AND": All of the conditions must match for the filter to
            match.

         +  "OR": At least one of the conditions must match for the
            filter to match.

         +  "NOT": None of the conditions must match for the filter to
            match.

      *  conditions: "(FilterOperator|FilterCondition)[]"

         The conditions to evaluate against each record.

      A *FilterCondition* is an "object" whose allowed properties and
      semantics depend on the data type and is defined in the /query
      method specification for that type.  It MUST NOT have an
      "operator" property.

   o  sort: "Comparator[]|null"

      Lists the names of properties to compare between two Foo records,
      and how to compare them, to determine which comes first in the
      sort.  If two Foo records have an identical value for the first
      comparator, the next comparator will be considered, and so on.  If
      all comparators are the same (this includes the case where an
      empty array or null is given as the "sort" argument), the sort
      order is server dependent, but it MUST be stable between calls to
      "Foo/query".  A *Comparator* has the following properties:
Top   ToC   RFC8620 - Page 44
      *  property: "String"

         The name of the property on the Foo objects to compare.

      *  isAscending: "Boolean" (optional; default: true)

         If true, sort in ascending order.  If false, reverse the
         comparator's results to sort in descending order.

      *  collation: "String" (optional; default is server-dependent)

         The identifier, as registered in the collation registry defined
         in [RFC4790], for the algorithm to use when comparing the order
         of strings.  The algorithms the server supports are advertised
         in the capabilities object returned with the Session object
         (see Section 2).

         If omitted, the default algorithm is server dependent, but:

         1.  It MUST be unicode-aware.

         2.  It MAY be selected based on an Accept-Language header in
             the request (as defined in [RFC7231], Section 5.3.5) or
             out-of-band information about the user's language/locale.

         3.  It SHOULD be case insensitive where such a concept makes
             sense for a language/locale.  Where the user's language is
             unknown, it is RECOMMENDED to follow the advice in
             Section 5.2.3 of [RFC8264].

         The "i;unicode-casemap" collation [RFC5051] and the Unicode
         Collation Algorithm (<http://www.unicode.org/reports/tr10/>)
         are two examples that fulfil these criterion and provide
         reasonable behaviour for a large number of languages.

         When the property being compared is not a string, the
         "collation" property is ignored, and the following comparison
         rules apply based on the type.  In ascending order:

         +  "Boolean": false comes before true.

         +  "Number": A lower number comes before a higher number.

         +  "Date"/"UTCDate": The earlier date comes first.

      The Comparator object may also have additional properties as
      required for specific sort operations defined in a type's /query
      method.
Top   ToC   RFC8620 - Page 45
   o  position: "Int" (default: 0)

      The zero-based index of the first id in the full list of results
      to return.

      If a negative value is given, it is an offset from the end of the
      list.  Specifically, the negative value MUST be added to the total
      number of results given the filter, and if still negative, it's
      clamped to "0".  This is now the zero-based index of the first id
      to return.

      If the index is greater than or equal to the total number of
      objects in the results list, then the "ids" array in the response
      will be empty, but this is not an error.

   o  anchor: "Id|null"

      A Foo id.  If supplied, the "position" argument is ignored.  The
      index of this id in the results will be used in combination with
      the "anchorOffset" argument to determine the index of the first
      result to return (see below for more details).

   o  anchorOffset: "Int" (default: 0)

      The index of the first result to return relative to the index of
      the anchor, if an anchor is given.  This MAY be negative.  For
      example, "-1" means the Foo immediately preceding the anchor is
      the first result in the list returned (see below for more
      details).

   o  limit: "UnsignedInt|null"

      The maximum number of results to return.  If null, no limit
      presumed.  The server MAY choose to enforce a maximum "limit"
      argument.  In this case, if a greater value is given (or if it is
      null), the limit is clamped to the maximum; the new limit is
      returned with the response so the client is aware.  If a negative
      value is given, the call MUST be rejected with an
      "invalidArguments" error.

   o  calculateTotal: "Boolean" (default: false)

      Does the client wish to know the total number of results in the
      query?  This may be slow and expensive for servers to calculate,
      particularly with complex filters, so clients should take care to
      only request the total when needed.
Top   ToC   RFC8620 - Page 46
   If an "anchor" argument is given, the anchor is looked for in the
   results after filtering and sorting.  If found, the "anchorOffset" is
   then added to its index.  If the resulting index is now negative, it
   is clamped to 0.  This index is now used exactly as though it were
   supplied as the "position" argument.  If the anchor is not found, the
   call is rejected with an "anchorNotFound" error.

   If an "anchor" is specified, any position argument supplied by the
   client MUST be ignored.  If no "anchor" is supplied, any
   "anchorOffset" argument MUST be ignored.

   A client can use "anchor" instead of "position" to find the index of
   an id within a large set of results.

   The response has the following arguments:

   o  accountId: "Id"

      The id of the account used for the call.

   o  queryState: "String"

      A string encoding the current state of the query on the server.
      This string MUST change if the results of the query (i.e., the
      matching ids and their sort order) have changed.  The queryState
      string MAY change if something has changed on the server, which
      means the results may have changed but the server doesn't know for
      sure.

      The queryState string only represents the ordered list of ids that
      match the particular query (including its sort/filter).  There is
      no requirement for it to change if a property on an object
      matching the query changes but the query results are unaffected
      (indeed, it is more efficient if the queryState string does not
      change in this case).  The queryState string only has meaning when
      compared to future responses to a query with the same type/sort/
      filter or when used with /queryChanges to fetch changes.

      Should a client receive back a response with a different
      queryState string to a previous call, it MUST either throw away
      the currently cached query and fetch it again (note, this does not
      require fetching the records again, just the list of ids) or call
      "Foo/queryChanges" to get the difference.
Top   ToC   RFC8620 - Page 47
   o  canCalculateChanges: "Boolean"

      This is true if the server supports calling "Foo/queryChanges"
      with these "filter"/"sort" parameters.  Note, this does not
      guarantee that the "Foo/queryChanges" call will succeed, as it may
      only be possible for a limited time afterwards due to server
      internal implementation details.

   o  position: "UnsignedInt"

      The zero-based index of the first result in the "ids" array within
      the complete list of query results.

   o  ids: "Id[]"

      The list of ids for each Foo in the query results, starting at the
      index given by the "position" argument of this response and
      continuing until it hits the end of the results or reaches the
      "limit" number of ids.  If "position" is >= "total", this MUST be
      the empty list.

   o  total: "UnsignedInt" (only if requested)

      The total number of Foos in the results (given the "filter").
      This argument MUST be omitted if the "calculateTotal" request
      argument is not true.

   o  limit: "UnsignedInt" (if set by the server)

      The limit enforced by the server on the maximum number of results
      to return.  This is only returned if the server set a limit or
      used a different limit than that given in the request.

   The following additional errors may be returned instead of the "Foo/
   query" response:

   "anchorNotFound": An anchor argument was supplied, but it cannot be
   found in the results of the query.

   "unsupportedSort": The "sort" is syntactically valid, but it includes
   a property the server does not support sorting on or a collation
   method it does not recognise.

   "unsupportedFilter": The "filter" is syntactically valid, but the
   server cannot process it.  If the filter was the result of a user's
   search input, the client SHOULD suggest that the user simplify their
   search.
Top   ToC   RFC8620 - Page 48

5.6. /queryChanges

The "Foo/queryChanges" method allows a client to efficiently update the state of a cached query to match the new state on the server. It takes the following arguments: o accountId: "Id" The id of the account to use. o filter: "FilterOperator|FilterCondition|null" The filter argument that was used with "Foo/query". o sort: "Comparator[]|null" The sort argument that was used with "Foo/query". o sinceQueryState: "String" The current state of the query in the client. This is the string that was returned as the "queryState" argument in the "Foo/query" response with the same sort/filter. The server will return the changes made to the query since this state. o maxChanges: "UnsignedInt|null" The maximum number of changes to return in the response. See error descriptions below for more details. o upToId: "Id|null" The last (highest-index) id the client currently has cached from the query results. When there are a large number of results, in a common case, the client may have only downloaded and cached a small subset from the beginning of the results. If the sort and filter are both only on immutable properties, this allows the server to omit changes after this point in the results, which can significantly increase efficiency. If they are not immutable, this argument is ignored. o calculateTotal: "Boolean" (default: false) Does the client wish to know the total number of results now in the query? This may be slow and expensive for servers to calculate, particularly with complex filters, so clients should take care to only request the total when needed.
Top   ToC   RFC8620 - Page 49
   The response has the following arguments:

   o  accountId: "Id"

      The id of the account used for the call.

   o  oldQueryState: "String"

      This is the "sinceQueryState" argument echoed back; that is, the
      state from which the server is returning changes.

   o  newQueryState: "String"

      This is the state the query will be in after applying the set of
      changes to the old state.

   o  total: "UnsignedInt" (only if requested)

      The total number of Foos in the results (given the "filter").
      This argument MUST be omitted if the "calculateTotal" request
      argument is not true.

   o  removed: "Id[]"

      The "id" for every Foo that was in the query results in the old
      state and that is not in the results in the new state.

      If the server cannot calculate this exactly, the server MAY return
      the ids of extra Foos in addition that may have been in the old
      results but are not in the new results.

      If the sort and filter are both only on immutable properties and
      an "upToId" is supplied and exists in the results, any ids that
      were removed but have a higher index than "upToId" SHOULD be
      omitted.

      If the "filter" or "sort" includes a mutable property, the server
      MUST include all Foos in the current results for which this
      property may have changed.  The position of these may have moved
      in the results, so they must be reinserted by the client to ensure
      its query cache is correct.
Top   ToC   RFC8620 - Page 50
   o  added: "AddedItem[]"

      The id and index in the query results (in the new state) for every
      Foo that has been added to the results since the old state AND
      every Foo in the current results that was included in the
      "removed" array (due to a filter or sort based upon a mutable
      property).

      If the sort and filter are both only on immutable properties and
      an "upToId" is supplied and exists in the results, any ids that
      were added but have a higher index than "upToId" SHOULD be
      omitted.

      The array MUST be sorted in order of index, with the lowest index
      first.

      An *AddedItem* object has the following properties:

      *  id: "Id"

      *  index: "UnsignedInt"

   The result of this is that if the client has a cached sparse array of
   Foo ids corresponding to the results in the old state, then:

   fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]

   If it *splices out* all ids in the removed array that it has in its
   cached results, then:

      removed = [ "id2", "id31", ... ];
      fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]

   and *splices in* (one by one in order, starting with the lowest
   index) all of the ids in the added array:

  added = [{ id: "id5", index: 0, ... }];
  fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]

   and *truncates* or *extends* to the new total length, then the
   results will now be in the new state.

   Note: splicing in adds the item at the given index, incrementing the
   index of all items previously at that or a higher index.  Splicing
   out is the inverse, removing the item and decrementing the index of
   every item after it in the array.
Top   ToC   RFC8620 - Page 51
   The following additional errors may be returned instead of the "Foo/
   queryChanges" response:

   "tooManyChanges": There are more changes than the client's
   "maxChanges" argument.  Each item in the removed or added array is
   considered to be one change.  The client may retry with higher max
   changes or invalidate its cache of the query results.

   "cannotCalculateChanges": The server cannot calculate the changes
   from the queryState string given by the client, usually due to the
   client's state being too old.  The client MUST invalidate its cache
   of the query results.

5.7. Examples

Suppose we have a type *Todo* with the following properties: o id: "Id" (immutable; server-set) The id of the object. o title: "String" A brief summary of what is to be done. o keywords: "String[Boolean]" (default: {}) A set of keywords that apply to the Todo. The set is represented as an object, with the keys being the "keywords". The value for each key in the object MUST be true. (This format allows you to update an individual key using patch syntax rather than having to update the whole set of keywords as one, which a "String[]" representation would require.) o neuralNetworkTimeEstimation: "Number" (server-set) The title and keywords are fed into the server's state-of-the-art neural network to get an estimation of how long this Todo will take, in seconds. o subTodoIds: "Id[]|null" The ids of a list of other Todos to complete as part of this Todo. Suppose also that all the standard methods are defined for this type and the FilterCondition object supports a "hasKeyword" property to match Todos with the given keyword.
Top   ToC   RFC8620 - Page 52
   A client might want to display the list of Todos with either a
   "music" keyword or a "video" keyword, so it makes the following
   method call:

                   [[ "Todo/query", {
                     "accountId": "x",
                     "filter": {
                       "operator": "OR",
                       "conditions": [
                         { "hasKeyword": "music" },
                         { "hasKeyword": "video" }
                       ]
                     },
                     "sort": [{ "property": "title" }],
                     "position": 0,
                     "limit": 10
                   }, "0" ],
                   [ "Todo/get", {
                     "accountId": "x",
                     "#ids": {
                       "resultOf": "0",
                       "name": "Todo/query",
                       "path": "/ids"
                     }
                   }, "1" ]]
Top   ToC   RFC8620 - Page 53
   This would query the server for the set of Todos with a keyword of
   either "music" or "video", sorted by title, and limited to the first
   10 results.  It fetches the full object for each of these Todos using
   back-references to reference the result of the query.  The response
   might look something like:

       [[ "Todo/query", {
         "accountId": "x",
         "queryState": "y13213",
         "canCalculateChanges": true,
         "position": 0,
         "ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ]
       }, "0" ],
       [ "Todo/get", {
         "accountId": "x",
         "state": "10324",
         "list": [{
           "id": "a",
           "title": "Practise Piano",
           "keywords": {
             "music": true,
             "beethoven": true,
             "mozart": true,
             "liszt": true,
             "rachmaninov": true
           },
           "neuralNetworkTimeEstimation": 3600
         }, {
           "id": "b",
           "title": "Watch Daft Punk music video",
           "keywords": {
             "music": true,
             "video": true,
             "trance": true
           },
           "neuralNetworkTimeEstimation": 18000
         },
         ...
         ]
       }, "1" ]]
Top   ToC   RFC8620 - Page 54
   Now, suppose the user adds a keyword "chopin" and removes the keyword
   "mozart" from the "Practise Piano" task.  The client may send the
   whole object to the server, as this is a valid PatchObject:

                 [[ "Todo/set", {
                   "accountId": "x",
                   "ifInState": "10324",
                   "update": {
                     "a": {
                       "id": "a",
                       "title": "Practise Piano",
                       "keywords": {
                         "music": true,
                         "beethoven": true,
                         "chopin": true,
                         "liszt": true,
                         "rachmaninov": true
                       },
                       "neuralNetworkTimeEstimation": 360
                     }
                   }
                 }, "0" ]]

   or it may send a minimal patch:

                      [[ "Todo/set", {
                        "accountId": "x",
                        "ifInState": "10324",
                        "update": {
                          "a": {
                            "keywords/chopin": true,
                            "keywords/mozart": null
                          }
                        }
                      }, "0" ]]
Top   ToC   RFC8620 - Page 55
   The effect is exactly the same on the server in either case, and
   presuming the server is still in state "10324", it will probably
   return success:

                 [[ "Todo/set", {
                   "accountId": "x",
                   "oldState": "10324",
                   "newState": "10329",
                   "updated": {
                     "a": {
                       "neuralNetworkTimeEstimation": 5400
                     }
                   }
                 }, "0" ]]

   The server changed the "neuralNetworkTimeEstimation" property on the
   object as part of this change; as this changed in a way *not*
   explicitly requested by the PatchObject sent to the server, it is
   returned with the "updated" confirmation.

   Let us now add a sub-Todo to our new "Practise Piano" Todo.  In this
   example, we can see the use of a reference to a creation id to allow
   us to set a foreign key reference to a record created in the same
   request:

                   [[ "Todo/set", {
                     "accountId": "x",
                     "create": {
                       "k15": {
                         "title": "Warm up with scales"
                       }
                     },
                     "update": {
                       "a": {
                         "subTodoIds": [ "#k15" ]
                       }
                     }
                   }, "0" ]]
Top   ToC   RFC8620 - Page 56
   Now, suppose another user deleted the "Listen to Daft Punk" Todo.
   The first user will receive a push notification (see Section 7) with
   the changed state string for the "Todo" type.  Since the new string
   does not match its current state, it knows it needs to check for
   updates.  It may make a request like:

                   [[ "Todo/changes", {
                     "accountId": "x",
                     "sinceState": "10324",
                     "maxChanges": 50
                   }, "0" ],
                   [ "Todo/queryChanges", {
                     "accountId": "x",
                     "filter": {
                       "operator": "OR",
                       "conditions": [
                         { "hasKeyword": "music" },
                         { "hasKeyword": "video" }
                       ]
                     },
                     "sort": [{ "property": "title" }],
                     "sinceQueryState": "y13213",
                     "maxChanges": 50
                   }, "1" ]]

   and receive in response:

                       [[ "Todo/changes", {
                         "accountId": "x",
                         "oldState": "10324",
                         "newState": "871903",
                         "hasMoreChanges": false,
                         "created": [],
                         "updated": [],
                         "destroyed": ["b"]
                       }, "0" ],
                       [ "Todo/queryChanges", {
                         "accountId": "x",
                         "oldQueryState": "y13213",
                         "newQueryState": "y13218",
                         "removed": ["b"],
                         "added": null
                       }, "1" ]]
Top   ToC   RFC8620 - Page 57
   Suppose the user has access to another account "y", for example, a
   team account shared between multiple users.  To move an existing Todo
   from account "x", the client would call:

                    [[ "Todo/copy", {
                      "fromAccountId": "x",
                      "accountId": "y",
                      "create": {
                        "k5122": {
                          "id": "a"
                        }
                      },
                      "onSuccessDestroyOriginal": true
                    }, "0" ]]

   The server successfully copies the Todo to a new account (where it
   receives a new id) and deletes the original.  Due to the implicit
   call to "Todo/set", there are two responses to the single method
   call, both with the same method call id:

                       [[ "Todo/copy", {
                         "fromAccountId": "x",
                         "accountId": "y",
                         "created": {
                           "k5122": {
                             "id": "DAf97"
                           }
                         },
                         "oldState": "c1d64ecb038c",
                         "newState": "33844835152b"
                       }, "0" ],
                       [ "Todo/set", {
                         "accountId": "x",
                         "oldState": "871903",
                         "newState": "871909",
                         "destroyed": [ "a" ],
                         ...
                       }, "0" ]]
Top   ToC   RFC8620 - Page 58

5.8. Proxy Considerations

JMAP has been designed to allow an API endpoint to easily proxy through to one or more JMAP servers. This may be useful for load balancing, augmenting capabilities, or presenting a single endpoint to accounts hosted on different JMAP servers (splitting the request based on each method's "accountId" argument). The proxy need only understand the general structure of a JMAP Request object; it does not need to know anything specifically about the methods and arguments it will pass through to other servers. If splitting up the methods in a request to call them on different backend servers, the proxy must do two things to ensure back- references and creation-id references resolve the same as if the entire request were processed on a single server: 1. It must pass a "createdIds" property with each subrequest. If this is not given by the client, an empty object should be used for the first subrequest. The "createdIds" property of each subresponse should be passed on in the next subrequest. 2. It must resolve back-references to previous method results that were processed on a different server. This is a relatively simple syntactic substitution, described in Section 3.7. When splitting a request based on accountId, proxy implementors do need to be aware of "/copy" methods that copy between accounts. If the accounts are on different servers, the proxy will have to implement this functionality directly.


(page 58 continued on part 4)

Next Section