Cozy Files doctype¶
io.cozy.files
¶
The io.cozy.files
doctype is used for both the files and directories.
Folder¶
For a folder, its attributes are:
type
: {string} alwaysdirectory
name
: {string} the directory namepath
: {string} the path to this directory, which is the path of its parent, then/
, then its namerestore_path
: {string} the restore path of the directory, if is in the trashcreated_at
: {timestamp} the date of the creation of this directory given by the clientupdated_at
: {timestamp} the date of the last update of this directory given by the clienttags
: {array of strings} a list of tags
It also has a relationship with its parent
in the JSON-API representation, and another called data
with the files and directory inside it.
Files¶
The attributes of a file are:
type
: {string} alwaysfile
name
: {string} the file nametrashed
: {bool} true if the file is in the trashrestore_path
: {string} the restore path of the file, if is in the trashmd5sum
: {string} the checksum of its content, computed with the MD5 algorithmcreated_at
: {date} the date of the creation of this file given by the clientupdated_at
: {date} the date of the last update of this file given by the clienttags
: {array of strings} a list of tags. It is currently used to know if a file was uploaded through the mobile photo sync, with the valuelibrary
.size
: {number} the size of its content, in bytesexecutable
: {bool} true is the file has the executable bit on UNIX (chmod +x
)class
: {string} a class in the list:['image', 'document', 'audio', 'video', 'text', 'binary', 'pdf', 'files', 'code', 'slide', 'spreadsheet', 'text', 'zip', 'shortcut']
mime
: {string} the full mime-typemetadata
: {map} an optional map of metadata (Full metadata description), with for example:width
: {number}height
: {number}datetime
: {date} : date in original image file metadatagps
: {map} : localization metadata with the following attributeslat
: {float}: latitudelong
: {float}: longitudecity
: {string}: nearest city (optional)zip
: {string}: postal code of the nearest city (optional)country
: {string}: name of the associated country if any (optional)
persons
: {array}: the maps can have the following attributes (optional)name
: {string}: then name of the tagged person on the photocreated_at
: {date}: date of creation of the tagx
: {float}: x coordinate in the photo where the person isy
: {float}: y coordinate in the photo where the person is
icon
: {string} : A small SVG file to use as icon for this file (optional)carbonCopy
: {boolean} : if the document is the original document imported by the connectorelectronicSafe
: {boolean} : if the document is secured in a secure storage
⚠ carbonCopy
and electronicSafe
both
need specific permission
to be added to a document.
It also has a relationship with its parent
in the JSON-API representation.
For an image
, there are 3 links to thumbnails: small
, medium
, and large
.
These thumbnail links are valid for 10 minutes. After that, links will return a 400 Bad Request response code.
Trash¶
When a file or a directory is put in the trash bin, some attributes are updated:
- trashed
is set to true, but only for files: directories never have this attribute.
- The restore_path
is set, for both files and directories.
- ⚠️ The restore_path
is not set on children. For instance, if a directory foo
is trashed, it will have a restore_path
but not the children.
- The path
is updated only for directories, starting with .cozy_trash
Here is how one could query files and directories not in the trash, through a mango query:
_id: { $ne: 'io.cozy.files.trash-dir' }, path: { $or: [{ $exists: false }, { $regex: '^(?!/.cozy_trash)' }] }, trashed: { $or: [{ $exists: false }, { $eq: false }] }
References¶
It’s possible to link a file or a folder to another document.
It’s called a reference.
It appears in the JSON-API representation as a refererenced_by
relationship.
CozyMetadata¶
The io.cozy.files
doctype has the standard cozyMetadata
, but with some more fields:
createdOn
: {string} the instance URL on which the file has created (useful if the file is shared between several cozy instances)uploadedAt
: {date} the server date/time of the last upload (when the content was changed)uploadedOn
: {string} the instance URL on which the file content was changed the last timeuploadedBy
: {map} information on which app has made the last uploadslug
: {string} the slug of the application that has made the uploadversion
: {string} the version number of this applicationoauthClient
: {map} if the upload was made by an OAuth Client, information about it (id
,name
, andkind
)
Example (JSON-API format)¶
{ "data": { "type": "io.cozy.files", "id": "9152d568-7e7c-11e6-a377-37cbfb190b4b", "meta": { "rev": "3-0e6d5b72" }, "attributes": { "type": "file", "name": "sunset.jpg", "trashed": false, "md5sum": "ODZmYjI2OWQxOTBkMmM4NQo=", "created_at": "2018-01-02T20:38:04Z", "updated_at": "2019-06-12T12:38:04Z", "tags": [], "metadata": { "datetime": "2018-01-02T20:38:04Z", "height": 1080, "width": 1920, "icon": "<svg xmlns='http://www.w3.org/2000/svg' width='32' height='32'><g fill='none' fill-rule='evenodd' transform='translate(0 2)'><rect width='32' height='26' y='2' fill='#B2D3FF' rx='2'/><path fill='#197BFF' d='M0 1a1 1 0 011-1h12c.55 0 1.31.31 1.71.71l.58.58c.4.4 1.15.71 1.71.71h13a2 2 0 012 2H17c-.55 0-1.31.31-1.71.71l-.58.58c-.4.4-1.16.71-1.72.71H1.01A1 1 0 010 5V1z'/></g></svg>" }, "size": 12, "executable": false, "class": "image", "mime": "image/jpg", "cozyMetadata": { "doctypeVersion": 1, "metadataVersion": 1, "createdAt": "2019-06-11T01:02:03Z", "createdByApp": "flickr", "createdByAppVersion": "1.2.3", "createdOn": "https://alice.cozy.example", "updatedAt": "2019-06-12T12:40:06Z", "updatedByApps": [ { "slug": "flickr", "date": "2019-06-11T01:02:03Z", "version": "1.2.3", "instance": "https://alice.cozy.example" }, { "slug": "cozy-desktop", "date": "2019-06-12T12:40:06Z", "version": "3.13.2", "instance": "https://alice.cozy.example" } ], "uploadedAt": "2019-06-11T20:34:56Z", "uploadedOn": "https://alice.cozy.example", "uploadedBy": { "slug": "cozy-desktop", "version": "3.13.2", "oauthClient": { "id": "9aaa6886-8b69-11e9-8412-b7855fb3838f", "kind": "desktop", "name": "Cozy Drive - mac book pro d'Alice" } }, "sourceAccount": "07b49550-8b60-11e9-bb7e-87717e829039", "sourceAccountIdentifier": "157ae784" } }, "relationships": { "parent": { "links": { "related": "/files/fce1a6c0-dfc5-11e5-8d1a-1f854d4aaf81" }, "data": { "type": "io.cozy.files", "id": "fce1a6c0-dfc5-11e5-8d1a-1f854d4aaf81" } }, "referenced_by": { "links": { "self": "/files/fce1a6c0-dfc5-11e5-8d1a-1f854d4aaf81/relationships/references" }, "data": [ { "type": "io.cozy.albums", "id": "94375086-e2e2-11e6-81b9-5bc0b9dd4aa4" } ] } }, "links": { "self": "/files/9152d568-7e7c-11e6-a377-37cbfb190b4b", "small": "/files/9152d568-7e7c-11e6-a377-37cbfb190b4b/thumbnails/0f9cda56674282ac/small", "medium": "/files/9152d568-7e7c-11e6-a377-37cbfb190b4b/thumbnails/0f9cda56674282ac/medium", "large": "/files/9152d568-7e7c-11e6-a377-37cbfb190b4b/thumbnails/0f9cda56674282ac/large" } } }
Shortcuts¶
Shortcuts (or hyperlinks) are a special type of files. They are served with the
application/internet-shortcut
mime-type, they have a .url
extension, and
respect the URL file
format.
They can have metadata
:
sharing.status
will be set if the link can be used to open a sharing. 2 values are possible:new
andseen
, depending on whether the link has been opened.target.cozyMetadata.instance
is set to the cozy instance when relevant (mostly sharing and internal links)target._type
is the doctype of the destination of the link (when the link goes to a sharing or document inside a cozy)target.mime
is the mime-type of the destination of the link (when it is a file)target.app
is the slug of the destination app (internal links only).icon
{string?} contains the svg icon.
Example (JSON format)¶
{ "_id": "629fb233be550a21174ac8e19f0043af", "_rev": "1-61c7804bdb4f9f8dae5a363cb9a30dd8", "type": "file", "name": "sunset.jpg.url", "dir_id": "629fb233be550a21174ac8e19f003e4a", "trashed": false, "md5sum": "vfEMDpJShs8QeIlsDmw9VA==", "created_at": "2020-02-10T20:38:04Z", "updated_at": "2020-02-10T20:38:04Z", "tags": [], "metadata": { "sharing": { "status": "new" }, "target": { "cozyMetadata": { "instance": "https://alice.cozy.example/" }, "_type": "io.cozy.files", "mime": "image/jpg" } }, "size": 62, "executable": false, "class": "shortcut", "mime": "application/shortcut", "cozyMetadata": { "doctypeVersion": 1, "metadataVersion": 1, "createdAt": "2020-02-10T20:38:04Z", "createdOn": "https://bob.cozy.example/", "updatedAt": "2020-02-10T20:38:04Z", "uploadedAt": "2020-02-10T20:38:04Z", "uploadedOn": "https://bob.cozy.example/" } }
io.cozy.files.versions
¶
The io.cozy.files.versions
is used to track old versions of a file content,
when files versioning is enabled. The attributes of a version are:
size
: {number} the size of its content, in bytesmd5sum
: {string} the checksum of its content, computed with the MD5 algorithmupdated_at
: {date} the date of the last update of this file given by the clienttags
: {array of strings} a list of tagsmetadata
: {map} an optional map of metadata.
It also has the same cozyMetadata
that a file (including the uploaded*
fields), and a relationship to the versioned file.
Example (CouchDB format)¶
{ "_id": "9152d568-7e7c-11e6-a377-37cbfb190b4b/3-0e6d5b72", "_rev": "1-782839bf19cf4edbc29b82f77b28482f", "updated_at": "2019-06-12T12:38:04Z", "size": "12", "md5sum": "ODZmYjI2OWQxOTBkMmM4NQo=", "tags": [], "metadata": { "datetime": "2018-01-02T20:38:04Z", "height": 1080, "width": 1920 }, "cozyMetadata": { "doctypeVersion": "1", "metadataVersion": 1, "createdAt": "2019-06-11T20:34:56Z", "createdOn": "https://alice.cozy.example", "updatedAt": "2019-06-11T20:34:56Z", "uploadedAt": "2019-06-11T20:34:56Z", "uploadedBy": { "slug": "drive" }, "uploadedOn": "https://alice.cozy.example" }, "relationships": { "file": { "data": { "_id": "9152d568-7e7c-11e6-a377-37cbfb190b4b", "_type": "io.cozy.files" } } } }
io.cozy.files.settings
¶
This doctype is used to store settings for files. It is currenly only used for the qualification migration service.
- lastProcessedFileDate: {string} the
cozyMetadata.updatedAt
date of the last processed file. It is used to know from where the query should be starting on an index sorted by date.
io.cozy.files.encryption
¶
This doctype is used to store encryption keys for directories. The encryption keys are stored encrypted in the same way than bitwarden’s ciphers, and are used to encrypt/decrypt files’ binary inside the directory.
_id
: {string} refers to its directory id:io.cozy.files/<dirID>
key
: {string} the encrypted key, used to encrypt/decrypt files inside the directory.