File schemas¶

Generated from the pydantic models. Unknown keys are declaration errors.

Application¶

compliance/app.yaml

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
`owners`	`dict[str, str]`	no	GitHub handles reviewing the compliance files: `dpo` (register: activities, parties, data) and `ciso` (posture: stores, threats, the gate). Default: @/dpo and @/ciso

compliance/parties/<id>.yaml

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)
`threats`	`Stamps`	no	Stamps closing the threat cells the matrix left open

compliance/activities/<slug>.yaml

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

<unit>/compliance/data/<id>.yaml

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

<unit>/compliance/touchpoints/<slug>.yaml

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
`exporting`	`list[Transfer] \\| None`	no	Deprecated spelling of `transfers`
`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
`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)
`threats`	`Stamps`	no	Stamps closing the threat cells the matrix left open (`SID` or `SID@sink` -> {status, note} or !missing)
`undeclared`	`list[Undeclared]`	no	Flows a reviewer found in the code that this manifest does not declare (see `flow_report`); each is a finding until the transfer is declared or the code stops sending

transfers: items of a manifest

Field	Type	Required	Description
`party`	`str`	yes	Party id, a file in `compliance/parties/`
`data`	`list[str]`	no	Inventory refs of what is sent
`purpose`	`str \\| None`	no	Why, in one line

stores: items of a manifest

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: items of a manifest

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

<unit>/compliance/stores/<slug>.yaml

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
`threats`	`Stamps`	no	Stamps closing the threat cells the matrix left open
`ignore`	`bool`	no	Hide the store (a test database)

threats: entries (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

threats: entries 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