Doctypes

Doctypes represent different types of data. Their primary use is for permissions: an app or konnector will request permissions for one or several doctypes and will not be able to access other doctypes.

!!! note Example: A banking application requests permissions for banking doctypes (io.cozy.bank.accounts, io.cozy.bank.operations etc..) but cannot access files (io.cozy.files). This ensure the segregation and security of your data.

In this repository, every (known) doctype and the fields that they contain is described. If you feel the need for another doctype, feel free to open a PR with the description and role of your doctype.

Cozy doctypes

• io.cozy.accounts: Konnector accounts
• io.cozy.apps: Apps installed in the Cozy
  • io.cozy.apps.suggestions: Suggestions for apps that the user might find useful
• io.cozy.bank: Banking related data
  • io.cozy.bank.settings: Bank application settings
  • io.cozy.bank.accounts: Bank accounts
    • io.cozy.bank.accounts.stats: Aggregated data about bank accounts
  • io.cozy.bank.operations: Bank transaction
  • io.cozy.bank.balancehistories: Daily balances
  • io.cozy.bank.recurrence: Recurrence group information
• io.cozy.bills: Bills
• io.cozy.contacts: Contacts
  • io.cozy.contacts.groups: Contacts groups
  • io.cozy.contacts.accounts: Vendors account
• io.cozy.files: Files
  • Files_metadatas: Metadatas about files
• io.cozy.konnectors: Connectors installed in the cozy
• io.cozy.identities: Instance owner identities
• io.cozy.notes: Notes with collaborative edition
• io.cozy.notifications: Notifications made by the apps (Email or Push notifications)
• io.cozy.permissions: Permissions of the instance
• io.cozy.photos: Photos
• io.cozy.procedures: Administrative procedures
• io.cozy.sessions.logins: Sessions logins entry
• io.cozy.settings: Instance settings
• io.cozy.sharings: Documents used for Cozy to Cozy sharings

Technical doctypes

• Accounts Types: io.cozy.account_types : OAuth informations and secrets for apps & konnectors
• cc.cozycloud.autocategorization: Auto categorization remote doctype
• io.cozy.exports: Instances exports
• io.cozy.jobs: Instance jobs
• io.cozy.oauth.clients: OAuth clients informations of the stack
• io.cozy.oauth.access_codes: Access codes specific to OAuth flow
• io.cozy.triggers: Job triggers
  • io.cozy.triggers.state: Job triggers states
• io.cozy.remote.requests: logs of requests via the remote doctypes
• io.cozy.sessions: cozy-stack sessions
• io.cozy.shared: cozy-stack doctype for sharings
• io.cozy.terms: Contains terms of services the user has signed

Remote doctypes

This repository is where the declaration of remote doctypes is done. Read more about remote doctypes in the cozy stack repository.

External doctypes

• com.bitwarden.ciphers: Ciphers for bitwarden clients
• com.bitwarden.folders: Folders for bitwarden clients
• com.unibet.bets: Bets from Unibet website

Generic model

Relationships

Relations between documents are under a relationships object at the root of the document. Relations are referenced by their names.

Each relation is an object with a data property containing either null, one reference or an array of references.

A reference is an object containing at least a _type with the name of the referenced doctype and an _id with the id of the referenced document inside its doctype.

{
  "_id": "mobydick",
  "relationships": {
    "authors": {
      "data": [{ "_id": "hermanmelville", "_type": "io.cozy.contacts" }]
    }
  }
}

External relationships

Relationships that reference a document that lives outside the couchdb of the user will have a _type in a different namespace than io.cozy.*, and will have an additional _protocol field.

At the moment the only available external relationship is bitwarden with the following format:

{
  "_id": "secretsafe",
  "relationships": {
    "vaultCipher": {
      "data": [{ "_id": "123abc", "_type": "com.bitwarden.ciphers", "_protocol": "bitwarden" }]
    }
  }
}

Document metadata

We distinguish three levels : the data (a list of songs from a playlist), the metadata about the data (the creation date of the playlist itself), the metadata of the cozy document (the creation date of the cozy document describing the playlist).

The third level (metadata of the wrapping document) is described by an object named cozyMetadata at the root of the document.

The following keys are reserved and have special meanings:

• doctypeVersion: Name or identifier for the version of the schema used by this document (ie: doctypeVersion: 2 for "This document conforms to io.cozy.contacts in its version 2")
• metadataVersion: Version of the cozyMetadata
• createdAt: Creation date of the cozy document
• createdByApp: Slug of the app or connector which created the document
• createdByAppVersion: Version identifier of the app
• updatedAt: Last modification date of the cozy document
• updatedByApps: List of objects representing the applications (slugs and versions) which modified the cozy document in its life and the last update date for each of those apps (one entry per slug, apps should just update the value)
• sourceAccount: When the document was imported from a connector, identifier of the account in io.cozy.accounts
• sourceAccountIdentifier: When the document was imported from a connector, identifier of the account on targeted web service (the email address most of the time)

Note: All these attributes are optional and taken care by the apps modifying the document. Unless specified otherwise in the documentation of the doctype, all these attributes may not be present or may have a null value.

{
  "_id": "xxxx",
  "cozyMetadata": {
    "doctypeVersion": 4,
    "metadataVersion": 1,
    "createdAt": "xxxxx",
    "createdByApp": "xxxx",
    "createdByAppVersion": "xxxx",
    "updatedAt": "xxxxx",
    "updatedByApps": [
      {
        "slug": "xxxxx",
        "date": "xxxxx",
        "version": 3
      }
    ],
    "sourceAccount": "xxxxx",
    "sourceAccountIdentifier": "[email protected]"
  }
}

Date format

Date should be formatted in ISO8601 :

• 2017-04-22T01:00:00-05:00 ✅
• 2017-04-22T01:00:00Z ✅
• 2017-04-22 ✅
• 2017-04-22 01:00 ❌