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 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
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 informationsschema
: {object} - The Note’s schema. See https://prosemirror.net/docs/guide/#schema for more informationstitle
: {string} - The Note’s titleversion
: {int} - The Note’s version
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 thesubjectsKnownValues
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.
- Examples:
purpose
: {string} the goal of the document: for instance, an identity document has anattestation
goal, to attest an identity. In the same manner, the purpose of a bill is toinvoice
something.- Examples:
attestation
,invoice
,contract
,report
, etc.
- Examples:
sourceCategory
: {string} the activity field of the source that produced the document.- Examples:
gov
,bank
,health
,transport
, etc.
- Examples:
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 thedriver_license
label,gov
is thesourceCategory
andtransport
thesourceSubCategory
.- Examples:
transport
,health
,civil_registration
,health
, etc.
- Examples:
subjects
: {array of strings} list what the document is about. For instance, adriver_license
has two subjects:permit
anddriving
, because this document is about the permit to drive a vehicle. Another example is thecar_insurance
: the subjects areinsurance
andcar
.- Examples:
permit
,insurance
,house
,car
, etc.
- Examples:
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 bydatetimeLabel
.description
: {string} A file summaryfileIdAttributes
: {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/
.datetimeLabel
: {string} specify which attribute is used asdatetime
, e.g.issueDate
orstartDate
.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 [AB 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 connectorelectronicSafe
: {boolean} : if the document is secured in a secure storagebackupDeviceIds
: {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 themetadata.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 toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}invoiceNumber
: {string} Invoice numbercontractReference
: {string} Reference of the related contract, if anyisSubscription
: {bool} True if the invoice is related to a subscription plan
Payslips
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
contentAuthor
: {string} Source of the payslip, e.g.payfit.fr
employerName
: {string} Name of the employer on the payslipstartDate
: {date} First day of the worked periodendDate
: {date} Last day of the worked periodissueDate
: {date} Issue date of the document
Tax Notices
datetime
: {date} Equals toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}issueDate
: {date} Issue date of the documentrefTaxIncome
: {string} reference tax income.taxNumber
: {string} fiscal reference number.
Tax Returns
datetime
: {date} Equals toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}issueDate
: {date} Issue date of the documentformReference
: {string} Reference of the form (ex: ‘2042RICI’)
Contracts
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
contentAuthor
: {string}contractReference
: {string} Reference of the contractcontractType
: {string} type of employment contract.issueDate
: {date} Issue date of the documentstartDate
: {date} First day of the validity periodendDate
: {date} Last day of the validity period
Certificates
datetime
: {date} Equals toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}issueDate
: {date} Issue date of the documentstartDate
: {date} First day of the validity periodendDate
: {date} Last day of the validity period
Diplomas
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
contentAuthor
: {string}startDate
: First day of the validity periodlabel
: {string} Short description of the diplomaschool
: {string} School namecountry
: {string} Country name
Driving licenses
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
number
: {string} Document numbercountry
: {string} Country name-
[A|B|C|D]ObtentionDate
: {date} date of obtaining the driving license [AB C D].
Identity documents
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
contentAuthor
: {string}issueDate
: {date} Issue date of the documentexpirationDate
: {date} Last day of validitynumber
: {string} Document numberschool
: {string} School namecountry
: {string} Country namenoticePeriod
: {string} number of days before expiration alert.
Bank Statements
datetime
: {date} Equals tostartDate
datetimeLabel
: {string}'startDate'
contentAuthor
: {string}startDate
: {date} First day of the statement periodendDate
: {date} Last day of the statement periodaccountNumber
: {string} Number of the related accountbankName
: {string} Name of the related bank
Bank Details (IBAN)
datetime
: {date} Equals toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}issueDate
: {date} Issue date of the documentaccountNumber
: {string} Number of the related accountbicNumber
: {string} Number of the related bankbankName
: {string} Name of the related bank
datetime
: {date} Equals toissueDate
datetimeLabel
: {string}'issueDate'
contentAuthor
: {string}
Report
datetime
: {date} Equals toissueDate
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": {
...
}