# StorageNode A StorageNode is the structure for storing file information in JMAP. A StorageNode can take 2 fundamental forms: a node that references an existing blob (aka a file) OR a node that has no reference to a blob, is used as a parent of other nodes and thus defines part of the structured storage (aka a folder). A **StorageNode** object has the following properties: - **id**: `String` (immutable; server-set) The id of the StorageNode. While server-set, the following folders MUST be present in each account with the following ids: - `root` - The id of the user's home directory - `trash` - The id of the user's trash directory - `temp` - The id of the users' temp directory These three core folders are all siblings inside the user's namespace directory. - **parentId**: `String` The StorageNode id for the parent of this node. - **blobId**: `String|null` The id of the binary data. This is `null` if, and only if, the storage node represents a folder, otherwise it MUST be the id of the blob representing the binary data for the node. - **name**: `String` User-visible name for the StorageNode, This may be any UTF-8 string of at least 1 character in length, except: * The name MUST be unique for all StorageNodes with the same parentId. * The name MUST NOT be "." or ".." * The name MUST NOT contain a "/" A server MAY limit the name length and will return an `invalidProperties` error if this limit is exceeded. - **type**: `String|null` The content-type of the StorageNode. This MUST be `null` if, and only if, the node does not have a `blobId`. - **size**: `Number` (server-set) Size in bytes of the associated blob data. If this node does not have a `blobId` then this MAY be the cumulative size in bytes of all child nodes. - **created**: `UTCDate` The date the node was created. - **modifed**: `UTCDate` The date the node was last updated. - **myRights**: `FilesRights` (server-set) The set of rights (ACLs) the user has in relation to this folder. A **FilesRights** object has the following properties: - **mayRead**: `Boolean` The user may read the contents of this node. - **mayWrite**: `Boolean` The user may modify the properties of this node, including renaming children. - **mayAdmin**: `Boolean` The user may change the sharing of this node. - **shareWith**: `String[FilesRights]|null` A map of userId to rights for users this node is shared with. The owner of the node MUST NOT be in this set. This is `null` if the user requesting the object does not have `myRights.mayAdmin`, or if the node is not shared with anyone. ## StorageNode/get Standard */get* method. StorageNodes can only be fetched explicitly by id. There is one additional argument: - **includeParentsLimit**: `Number` (default: `0`) Specifies how far up the parent hierarchy to traverse for each found node with a non-null `parentId`, returning the parent StorageNode along with the requested node. A value of `-1` is equivalent to 'no limit', returning all parent nodes of any requested node. ## StorageNode/changes Standard */changes* method. ## StorageNode/query Standard */query* method. The **FilterCondition** object has the following properties: - **parentIds**: `String[]` A list of StorageNode ids. A node must have a parentId equal to ONE of these to match the condition. - **ancestorIds**: `String[]` A list of StorageNode ids. A node must have an ancestor (parent, parent of parent, etc.) equal to ONE of these to match the condition. - **hasBlobId**: `Boolean` If `true`, the StorageNode must have a blobId set to match (i.e. be a file, not a folder). - **createdBefore**: `Date` The creation date of the node (as returned on the StorageNode object) must be before this date to match the condition. - **createdAfter**: `Date` The creation date of the node (as returned on the StorageNode object) must be on or after this date to match the condition. - **modifiedBefore**: `Date` The modified date of the node (as returned on the StorageNode object) must be before this date to match the condition. - **modifiedAfter**: `Date` The modified date of the node (as returned on the StorageNode object) must be on or after this date to match the condition. - **minSize**: `Number` The size of the node in bytes (as returned on the StorageNode object) must be equal to or greater than this number to match the condition. - **maxSize**: `Number` The size of the node in bytes (as returned on the StorageNode object) must be less than this number to match the condition. - **name**: `String` Does a glob match of the specified name against the *name* property of the node. - **type**: `String` Does a glob match of the specified type against the *type* property of the node. A StorageNode object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically `true` for all objects. The exact semantics for matching `String` fields is **deliberately not defined** to allow for flexibility in indexing implementation, subject to the following: - Text SHOULD be matched in a case-insensitive manner. - Text contained in either (but matched) single or double quotes SHOULD be treated as a **phrase search**, that is a match is required for that exact sequence of words, excluding the surrounding quotation marks. Use `\"`, `\'` and `\\` to match a literal `"`, `'` and `\` respectively in a phrase. - Outside of a phrase, white-space SHOULD be treated as dividing separate tokens that may be searched for separately in the node, but MUST all be present for the node to match the filter. - Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for `bus` would match "buses" but not "business"). The following properties are supported for sorting: - **id**: The id as returned in the StorageNode object. - **hasBlobId**: Is the StorageNode a folder or a file? - **name**: The name as returned in the StorageNode object. - **type**: The type as returned in the StorageNode object. - **size**: The size as returned in the StorageNode object. - **created**: The created date as returned in the StorageNode object. - **modified**: The modified date as returned in the StorageNode object. ## StorageNode/queryChanges Standard */queryChanges* method. ## StorageNode/set Standard */set* method. Note, *created* and *modified* MAY be included but the server SHOULD impose some sanity checks (e.g. can't set in future, subject to reasonable jitter allowance or a minimum allowable date). This is intended to support syncing by offline clients. If sanity checks are triggered the create/update is accepted, but the values are overwritten and the server will return the values used to the client. If on create a node with a conflicting *name* already exists, the server will add a suffix to the name to make it no longer clash and allow the create to proceed, returning the new name in the created response. If *type* is set to `null` and the storage node has a blob id, the server will determine the type based on the filename and return this with the created/updated response. Standard set errors, e.g. `overQuota`, `invalidProperties` etc. should be returned where appropriate. An *id* corresponding to a previously deleted folder MAY be passed for creates. The server will restore the previous contents of this folder when creating the folder, if found. If the node being created is not a folder, or the id given is not a valid id for a deleted folder, reject with `notFound` error. ## StorageNode/copy Standard */copy* method.