Declaration schemas¶

Generated from the pydantic models the rows of compliance.db are validated against. Unknown keys are declaration errors.

Application¶

the app row

Field	Type	Required	Description
`name`	`str \\| Marker`	yes	Name of the product
`description`	`str \\| Marker`	yes	What the product does, for whom, in a few sentences
`controller`	`str \\| Marker`	yes	Party id of the controller
`processor`	`str \\| Marker \\| None`	no	Party id of the processor, if any
`large_scale`	`bool \\| Marker \\| None`	no	Whether the product processes personal data at large scale (Art. 35(3)(b)): true, false, or !todo while unknown. Absent means false: a DPIA is then only required for special-category data

a parties row

Field	Type	Required	Description
`name`	`str \\| Marker`	yes	Legal name of the organisation
`country`	`str \\| Marker`	yes	Country of establishment (ISO 3166-1 alpha-2); drives the third-country transfer logic
`address`	`str \\| Marker`	yes	Postal address of the seat
`email`	`str \\| Marker`	yes	Email for privacy matters (the one to put in a notice)
`phone`	`str \\| None`	no
`website`	`str \\| None`	no
`hosts`	`list[str]`	no	Hostnames (or registrable domains) this organisation operates besides its website, e.g. `api.hubapi.com` for HubSpot: a call the code makes to one of them is a transfer to this party; a settings name (`MAILGUN_API_URL`) claims the calls reading that setting
`registration`	`str \\| None`	no	Company registration number
`dpo`	`Contact \\| None`	no	Art. 37 data protection officer
`representative`	`Contact \\| None`	no	Art. 27 representative in the Union
`safeguard`	`Literal['sccs', 'bcr', 'dpf', 'derogation'] \\| Marker \\| None`	no	Ch. V safeguard for transfers to this party when it sits outside the EEA/adequacy countries: sccs, bcr, dpf or derogation
`dpf_certified`	`bool \\| None`	no	Whether the party is on the EU-US Data Privacy Framework list (required for safeguard: dpf)
`dpa`	`str \\| None`	no	Where the data processing agreement with this party lives (URL or document reference)
`distinct_from`	`list[str]`	no	Ids of declared parties this one resembles (a similar name or a shared domain) but is a different organisation: silences the duplicate guard for those pairs

an activities row

Field	Type	Required	Description
`name`	`str \\| Marker`	yes	Short name of the activity
`purpose`	`str \\| Marker`	yes	Why the data is processed, as the register states it
`legal_basis`	`activities.LegalBasis \\| Marker`	yes	Art. 6 basis: contract, consent, legal_obligation, legitimate_interests, vital_interests or public_task; no_pii when the activity handles no personal item
`basis_note`	`str \\| None`	no	When two bases compete: the candidates and the argument
`consent`	`activities.Consent \\| None`	no	Required when legal_basis is consent
`interest`	`str \\| Marker \\| None`	no	legitimate_interests: the balancing test (Art. 6(1)(f))
`dpia_reference`	`str \\| Marker \\| None`	no	Where the DPIA lives, when the derived trigger fires (Art. 35)
`touchpoints`	`list[str]`	no
`data_subjects`	`list[str] \\| Marker`	no	Whose data: customers, staff, prospects, ...
`recipients`	`list[str]`	no
`retention`	`str \\| Marker \\| None`	no	How long the data is kept and what starts the clock
`controller`	`str \\| Marker \\| None`	no	Party id, when not the app's controller
`processor`	`str \\| Marker \\| None`	no	Party id, when not the app's processor
`description`	`str \\| None`	no

a data_items row of kind override

Field	Type	Required
`pii`	`bool \\| None`	no
`sensitivity`	`str \\| None`	no
`category`	`str \\| None`	no
`store`	`str \\| None`	no
`reason`	`str \\| Marker \\| None`	no
`rights`	`rights.RightsSpec \\| None`	no

a touchpoints row

Field	Type	Required	Description
`data`	`list[str \\| dict[str, Any]] \\| None`	no	Every inventory item touched, as `ref` (a read) or `{ref: op \\| [ops]}`; `[]` = checked, touches none; absent = pending
`transfers`	`list[Transfer]`	no	What leaves to another organisation's API
`stores`	`list[StoreWrite]`	no	Copies of the listed items into another store of the project (a realtime server, a search index): a store flow, not a transfer
`scope`	`Scope \\| None`	no	Who this touchpoint serves (subject \| staff \| public \| system); inferred from auth when absent
`reach`	`Reach \\| None`	no	The weakest caller the code lets in (anonymous \| subject \| staff \| system); inferred from auth when absent, required when the view overrides the auth machinery
`ignore`	`bool`	no	Plumbing (health check, static asset): skip
`note`	`str \\| None`	no	The reviewer's reason, citing file:line
`challenge`	`ManifestChallenge \\| None`	no	A doubt cast by the challenger on this declaration; the touchpoint is pending until re-reviewed
`answered`	`ManifestChallenge \\| None`	no	The last challenge a re-review closed (kept so the same grounds are not raised twice)
`undeclared`	`list[Undeclared]`	no	Flows a reviewer found in the code that this declaration does not have (see `flow_report`); each is a finding until the transfer is declared or the code stops sending

transfers of a declaration

Field	Type	Required	Description
`party`	`str`	yes	A declared party id
`data`	`list[str]`	no	Inventory refs of what is sent
`purpose`	`str \\| None`	no	Why, in one line

stores of a declaration

Field	Type	Required	Description
`store`	`str`	yes	Store slug (`tmw`) or `unit:slug` when it is another unit's
`data`	`list[str]`	no	Inventory refs of what is written
`purpose`	`str \\| None`	no	Why, in one line

undeclared of a declaration

Field	Type	Required
`sink`	`str`	yes
`data`	`list[str]`	no
`note`	`str`	yes
`commit`	`str \\| None`	no
`at`	`str \\| None`	no

a stores row

Field	Type	Required	Description
`type`	`StoreType \\| None`	no	Mandatory for a store the settings do not show
`backend`	`str \\| None`	no	Conceptual backend: postgresql, redis, s3, hocuspocus
`name`	`str \\| Marker \\| None`	no	Human name of the store
`provider`	`str \\| Marker \\| None`	no	Who operates it (party id or vendor name)
`location`	`str \\| Marker \\| None`	no	Region the data sits in (country / region id)
`retention`	`str \\| Marker \\| None`	no	How long records stay in this store
`description`	`str \\| Marker \\| None`	no	What this store holds, in one sentence
`hosts`	`list[str]`	no	Hostnames the code reaches this store at, or the names of the settings holding its URL (`TMW_URL`); a fetch to one of them is a write to this store, not a transfer
`ignore`	`bool`	no	Hide the store (a test database)
`distinct_from`	`list[str]`	no	Slugs of stores of this unit that this one resembles (a shared host, a similar name or slug) but is not: silences the duplicate guard

threat_stamps rows (mitigated / accepted / n/a)

Field	Type	Required	Description
`status`	`Literal['mitigated', 'accepted', 'n/a']`	yes
`note`	`str \\| None`	no
`commit`	`str \\| None`	no
`fingerprint`	`str \\| None`	no	The element's fingerprint when stamped; a different one now means the code moved and the stamp is stale
`by`	`Literal['human', 'agent'] \\| None`	no
`challenge`	`StampChallenge \\| None`	no	The challenger doubts this verdict after a change: the cell is open again until re-stamped
`answered`	`StampChallenge \\| None`	no	The last challenge a re-stamp closed (so the same grounds are not raised twice for the same change)

challenge / answered on a stamp

Field	Type	Required
`commit`	`str`	yes
`grounds`	`str`	yes
`at`	`str \\| None`	no

threat_stamps rows written from a !missing

Field	Type	Required
`missing`	`str`	yes
`effect`	`str \\| None`	no
`degree`	`str \\| None`	no
`actors`	`list[str]`	no
`data`	`list[str]`	no
`sensitivity`	`str \\| None`	no
`impact`	`float \\| None`	no
`likelihood`	`float \\| None`	no
`severity`	`str \\| None`	no
`commit`	`str \\| None`	no
`fingerprint`	`str \\| None`	no
`by`	`Literal['human', 'agent'] \\| None`	no
`narrowed_effect`	`str \\| None`	no
`narrowed_degree`	`str \\| None`	no
`narrowed_actor`	`str \\| None`	no