

Metadata

Cozy documents have a cozyMetadata block with metadata about the document, like its schema version, its creation date, its source, etc.

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

Options for cozy-client

This cozyMetadata block is managed by the apps themselves. Cozy-Client is able to manage some parts of cozyMetadata automatically. For this it needs an appMetadata parameter with a few informations:

• slug: the slug of the app or konnector (will be used in createdByApp and updatedByApps)
• version: version of the app (will be used in createdByAppVersion and updatedByApps)
• when in a konnector, sourceAccount: the id of the io.cozy.accounts document that triggered the current execution (it will help to know which documents belong or are created by which account)
• when in a konnector, sourceAccountIdentifier: identifier unique to the account targetted by the konnector. It is the user login most of the time

const client = new CozyClient({
  appMetadata: {
    slug: 'banks',
    version: '1.27.1'
  }
})

When you provide this information, cozy-client will automatically update metadata when it saves a document.

For new documents

Cozy-Client will set:

• metadataVersion : to the last version known to Cozy-Client. It’s the version of the schema for the metadata block itself.
• doctypeVersion : if it’s provided in the schema at Cozy-Client initialization
• slug : Slug of the app
• sourceAccount: : if it’s provided in the appMetadata at initialization. Note it won’t work for files (see below).
• creation date, app and version
• updated date, app and version

const client = new CozyClient({
  appMetadata: {
    slug: 'banks',
    version: '1.27.1'
  },
  schema: {
    bankAccounts: {
      doctypeVersion: '1.0.0'
    }
  }
})

If any of these fields already exists in the document you try to save, these values will override the defaults. This allows you to import a document with an existing history.

For existing documents

Cozy-Client will:

• Set the updated date
• Add your app and version in the updatedByApps list

⚠️ These values will override any values that your document may already have.

Specific case of io.cozy.files

The io.cozy.files doctype is protected by cozy-stack, that restricts the attributes that can be saved by the client, including the cozyMetadata.

This is the case for : * cozyMetadata.sourceAccount * cozyMetadata.sourceAccountIdentifier

To save those attributes, you can pass them directly to the save method, like this:

const client = new client()
client.save({
  _type: 'io.cozy.files',
  sourceAccount: '12ab3c',
  sourceAccountIdentifier: 'john@example.org',
  ...
})