Metadata on io.cozy.files documents

Generic metadata

For generic metadata like createdAt or updatedAt, please follow the cozy-doctypes doc about generic model

Image files

For pictures files, like jpg, png, gif…

• width: {number}
• height: {number}
• datetime: {date} : date in original image file metadata
• gps: {map} : localization metadata with the following attributes
  • lat: {float}: latitude
  • long: {float}: longitude
  • city: {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 photo
  • created_at: {date}: date of creation of the tag
  • x: {float}: x coordinate in the photo where the person is
  • y: {float}: y coordinate in the photo where the person is

Cozy Note files

For a Cozy Note, here is the list:

• content: {object} - The Note’s content. See https://prosemirror.net/docs/ref/#model for more informations
• schema: {object} - The Note’s schema. See https://prosemirror.net/docs/guide/#schema for more informations
• title: {string} - The Note’s title
• version: {int} - The Note’s version

Folders

• decorations: {object} information on folder presentation
  • color: {string} hexadecimal color code
  • icon: {string} name of the icon in the list of cozy-ui icons
  • icon_color: {string} hexadecimal color code for the icon
  • emoji: {string} unicode character of the emoji

Document qualification

It is possible to add semantics to documents in order to qualify them.

A qualification model is available here that describes the qualification attributes for a set of documents. A qualification consists of a label bound to some fixed attributes, i.e.purpose, sourceCategory, sourceSubCategory and subjects, all explained in the next section. Note that for a given label, it is possible to customize the model attributes values, by following these rules:

• If a value is defined for the attributes purpose, sourceCategory,sourceSubCategory, it is not possible to customize it.
• If a value is not defined for one of these attributes, a custom value can be defined, if it exists in their respective known values list in the model, e.g. knownSourceCategory.
• If some subjects values are set, they must be included in the given qualification.
• Extra subjects values can be set, but they should exist in the subjectsKnownValues model list.

A document qualification is typically set by konnectors or by applications such as Cozy Drive through the cozy-scanner library.

Data structure

Example

Here is a qualification example:

{
  "qualification": {
    "label": "driver_license",
    "purpose": "attestation",
    "sourceCategory": "gov",
    "sourceSubCategory": "transport",
    "subjects": ["permit", "driving"] }
}

Qualification attributes

A qualification can be composed of the following attributes:

• label: {string} the document label, which precisely specify what is the document. It is the only mandatory attribute in the qualification.
  • Examples: driver_license, car_insurance, bank_statement, etc.
• purpose: {string} the goal of the document: for instance, an identity document has an attestation goal, to attest an identity. In the same manner, the purpose of a bill is to invoice something.
  • Examples: attestation, invoice, contract, report, etc.
• sourceCategory: {string} the activity field of the source that produced the document.
  • Examples: gov, bank, health, transport, etc.
• sourceSubCategory: {string} a precision of the activity field of the source that produced the document. In some cases, it is necessary when the primary field is too broad. Typically, for the driver_license label, gov is the sourceCategory and transport the sourceSubCategory.
  • Examples: transport, health, civil_registration, health, etc.
• subjects: {array of strings} list what the document is about. For instance, a driver_license has two subjects: permit and driving, because this document is about the permit to drive a vehicle. Another example is the car_insurance: the subjects are insurance and car.
  • Examples: permit, insurance, house, car, etc.

For a complete list of the possible values for each attributes, see the qualification model.

If you need to add new values, please consider opening an issue or making a pull request to the cozy-client repository.

Additional metadata attributes

Additional metadata attributes might be set to further describe the document. Most of these attributes heavily depends on the document context and are not expected in every cases.

• contentAuthor : {string} the author of the document, e.g. impots.gouv, amazon.com, etc. It is currently used as a source meaning.
• datetime : {date} Equals to the date attribute specified by datetimeLabel.
• description: {string} A file summary
• fileIdAttributes : {string} Used to deduplicate files imported by a konnector. This is a concatenation of a set of attributes, separated by ####. For example: mycontractid####myfile.pdf####/mypath/.
• externalId : {string} Used to identify the file in an external application.
• datetimeLabel : {string} specify which attribute is used as datetime, e.g. issueDate or startDate.
• issueDate : {date} issue date of the document emitted by the vendor.
• startDate : {date} first day of a period, e.g. for a contract.
• endDate : {date} last day of a period, e.g. for a contract.
• expirationDate : {date} last day of validity, e.g. for an identity document.
• referencedDate : {date} reference date, e.g. for a sports club card.

• [A|B|C|D]ObtentionDate : {date} date of obtaining the driving license [A

  B

  C

  D].

• noticePeriod : {string} number of days before expiration alert.
• contractType : {string} type of employment contract.
• refTaxIncome : {string} reference tax income.
• netSocialAmount : {string} net social amount.
• employerName : {string} name of the employer.
• taxNumber : {string} fiscal reference number.
• invoiceNumber : {string} invoice number.
• number : {string} Relative number e.g. iban number for an iban document.
• contractReference : {string} reference of the related contract.
• isSubscription : {bool} true if the invoice is related to a subscription plan.
• labelGivenByUser : {string} custom document name.
• formReference : {string} reference of the form (ex: ‘2042RICI’).
• school : {string} school name.
• country : {string} country name.
• accountNumber : {string} number of the related account.
• bicNumber: {string} Number of the related bank.
• bankName : {string} name of the related bank.
• carbonCopy: {boolean} : if the document is the original document imported by the connector
• electronicSafe: {boolean} : if the document is secured in a secure storage
• backupDeviceIds: {string[]} : id of the devices owning the backup. Only for backup directories.
• paperProps: {object} : Metadata relative to a paper. A “paper” is an administrative file whose nature is defined in the metadata.qualification set of attributes.
  • isBlank: {boolean} : if the document is created without a visual (image or pdf) added by the user

⚠ carbonCopy and electronicSafe both need specific permission to be added to a document.

Examples

Invoices and documents related to payments

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}
• invoiceNumber : {string} Invoice number
• contractReference : {string} Reference of the related contract, if any
• isSubscription : {bool} True if the invoice is related to a subscription plan

Payslips

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• contentAuthor : {string} Source of the payslip, e.g. payfit.fr
• employerName : {string} Name of the employer on the payslip
• startDate : {date} First day of the worked period
• endDate : {date} Last day of the worked period
• issueDate : {date} Issue date of the document

Tax Notices

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}
• issueDate : {date} Issue date of the document
• refTaxIncome : {string} reference tax income.
• taxNumber : {string} fiscal reference number.

Tax Returns

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}
• issueDate : {date} Issue date of the document
• formReference : {string} Reference of the form (ex: ‘2042RICI’)

Contracts

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• contentAuthor : {string}
• contractReference : {string} Reference of the contract
• contractType : {string} type of employment contract.
• issueDate : {date} Issue date of the document
• startDate : {date} First day of the validity period
• endDate : {date} Last day of the validity period

Certificates

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}
• issueDate : {date} Issue date of the document
• startDate : {date} First day of the validity period
• endDate : {date} Last day of the validity period

Diplomas

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• contentAuthor : {string}
• startDate : First day of the validity period
• label : {string} Short description of the diploma
• school : {string} School name
• country : {string} Country name

Driving licenses

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• number : {string} Document number
• country : {string} Country name

• [A|B|C|D]ObtentionDate : {date} date of obtaining the driving license [A

  B

  C

  D].

Identity documents

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• contentAuthor : {string}
• issueDate : {date} Issue date of the document
• expirationDate : {date} Last day of validity
• number : {string} Document number
• school : {string} School name
• country : {string} Country name
• noticePeriod : {string} number of days before expiration alert.

Bank Statements

• datetime : {date} Equals to startDate
• datetimeLabel : {string} 'startDate'
• contentAuthor : {string}
• startDate : {date} First day of the statement period
• endDate : {date} Last day of the statement period
• accountNumber : {string} Number of the related account
• bankName : {string} Name of the related bank

Bank Details (IBAN)

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}
• issueDate : {date} Issue date of the document
• accountNumber : {string} Number of the related account
• bicNumber: {string} Number of the related bank
• bankName : {string} Name of the related bank

Mail

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}

Report

• datetime : {date} Equals to issueDate
• datetimeLabel : {string} 'issueDate'
• contentAuthor : {string}

Files metadata examples

Invoices, payment statements, payment schedules

// invoice - bouygues telecom
"metadata": {
  "qualification": {
    "label": "telecom_invoice",
    "purpose": "invoice",
    "sourceCategory": "telecom",
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "bouyguestelecom",
  "issueDate": "2019-05-10",
  "contractReference": "0645874398",
  "invoiceNumber": "KJF949875",
  "isSubscription": true
},
"cozyMetadata": {
  ...
}

// payment statement - ameli
"metadata": {
  "qualification": {
    "label": "health_invoice",
    "purpose": "invoice",
    "sourceCategory": "health"
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "ameli",
  "issueDate": "2019-05-10"
},
"cozyMetadata": {
  ...
}

// payment schedule - EDF
"metadata": {
    "qualification": {
      "label": "energy_invoice",
      "purpose": "invoice",
      "sourceCategory": "energy"
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "edf",
  "iSubscription": true,
  "issueDate": "2019-05-10"
},
"cozyMetadata": {
  ...
}

Taxe notices

// taxe notice on income
"metadata": {
  "qualification": {
    "label": "tax_notice",
    "purpose": "invoice",
    "sourceCategory": "gov",
    "sourceSubCategory": "tax",
    "subjects": ["tax"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "impots.gouv",
  "issueDate": "2019-05-10",
  "taxNumber": "1234567891011",
  "refTaxIncome" : "12345"
},
"cozyMetadata": {
  ...
}

// tax return on income
"metadata": {
  "qualification": {
    "label": "tax_return",
    "purpose": "report",
    "sourceCategory": "gov",
    "sourceSubCategory": "tax",
    "subjects": ["tax"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "impots.gouv",
  "formReference": "2042RICI",
  "issueDate": "2019-05-10"
},
"cozyMetadata": {
  ...
}

Payslips

// payslip - cozycloud
"metadata": {
  "qualification": {
    "label": "pay_sheet",
    "purpose": "attestation",
    "sourceCategory": "employer",
    "subjects": ["work", "revenues"]
  },
  "datetime": "2019-05-01",
  "datetimeLabel": "startDate",
  "contentAuthor": "payfit.fr",
  "employerName": "cozycloud",
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},
"cozyMetadata": {
  ...
}

Certificates

// health insurance attestation - ameli
"metadata": {
  "qualification": {
    "label": "national_insurance_card",
    "purpose": "attestation",
    "sourceCategory": "gov",
    "sourceSubCategory": "health",
    "subjects": ["insurance"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "ameli",
  "issueDate": "2019-05-10",
  "startDate": "2019-01-01",
  "endDate": "2019-12-31"
},
"cozyMetadata": {
  ...
}

// car insurance certificate - maif
"metadata": {
  "qualification": {
    "label": "car_insurance",
    "purpose": "attestation",
    "sourceCategory": "insurance",
    "sourceSubCategory": "transport",
    "subjects": ["insurance", "car"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "macif",
  "issueDate": "2019-05-10",
  "startDate": "2019-01-01",
  "endDate": "2019-12-31"
},
"cozyMetadata": {
  ...
}

// right certificate - CAF
"metadata": {
  "qualification": {
    "label": "caf",
    "purpose": "attestation",
    "sourceCategory": "gov",
    "sourceSubCategory": "family",
    "subjects": ["right"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "caf",
  "issueDate": "2019-05-10",
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},
"cozyMetadata": {
  ...
}

Identity documents

// id card
"metadata": {
  "qualification": {
    "label": "national_id_card",
    "purpose": "attestation",
    "sourceCategory": "gov",
    "sourceSubCategory": "civil_registration",
    "subjects": ["identity"]
  },
  "datetime": "2019-05-10",
  "datetimeLabel": "issueDate",
  "contentAuthor": "france",
  "issueDate": "2014-05-10",
  "expirationDate": "2029-05-10",
  "number": "ABC123456",
  "country": "france",
}
"cozyMetadata": {
  ...
}