Repository navigation
Description
Summary
EntityRelation records the link between a detected entity and the chunk/file/object/email it was found in, plus its anonymisation outcome (anonymized, anonymizedValue). What it does NOT carry is why a redaction was applied — the legal basis (grondslag) under which the anonymisation was performed.
This change adds a single optional bases JSON column to EntityRelation and extends the anonymise endpoint to accept and persist these bases per entity. The bases MUST be stripped from the payload before forwarding to OpenAnonymiser — they are metadata about the decision, not input to the redaction tool.
OpenSpec change directory: openspec/changes/entity-relation-grondslagen/
Specs
- entity-relation-grondslagen (NEW capability) — optional bases-link on
EntityRelation; the anonymise endpoint's contract for accepting, persisting, and stripping per-entity bases. Spec:openspec/changes/entity-relation-grondslagen/specs/entity-relation-grondslagen/spec.md
Cross-app
Paired DocuDesk change: anonymisation-grondslagen-and-prohibition-gate (DocuDesk repo). Either side can land first; the unused side is a no-op until its counterpart ships.
Tasks
1. Database migration
- 1.1 Add a new migration class under
lib/Migration/(next-available version, e.g.Version<X>Date<Y>.php) that adds a nullable JSON columnbasestooc_openregister_entity_relations. Use the platform's existing JSON column type (JSON on MySQL/MariaDB, JSON / JSONB on PostgreSQL — match what other JSON columns in OpenRegister use today). Default value: NULL. - 1.2 Verify the migration is idempotent: running it twice on the same database is a no-op (Nextcloud's
addColumnprimitive is idempotent — confirm via dry-run or unit test). - 1.3 Smoke-test the migration on a populated dev database: confirm existing
EntityRelationrows are read correctly post-migration andbasesreads asnullfor all of them.
2. EntityRelation entity + mapper
- 2.1 Add
protected ?array $bases = null;tolib/Db/EntityRelation.php. - 2.2 Add
addType(fieldName: 'bases', type: 'json');inEntityRelation::__construct(). - 2.3 Add the
getBases(): ?arrayandsetBases(?array $bases): voidmagic-method docblocks to the class header (mirroring the existing pattern for other fields). - 2.4 Update
jsonSerialize()to includebasesin the returned array. Order it afteranonymizedValuefor consistency. - 2.5 Update the psalm/phpdoc return type on
jsonSerializeto includebases. - 2.6 Confirm
EntityRelationMapperdoes not need changes — Nextcloud'sQBMapperautomatically handles columns registered viaaddType. If the mapper has any column-list handling that's NOT auto-derived (e.g. manualselect(...)lists), update those to includebases.
3. Anonymise endpoint integration
- 3.1 In
FileService::anonymizeDocument(node, payload)(or the equivalent service method), accept an optionalbasesfield on each entry inpayload.entities[]. Validate at the entry point: the field, when present, MUST be eithernullor an array of strings. Reject malformed input with a 400-level error. - 3.2 Implement the persist-then-strip order: locate or upsert the
EntityRelationrow for(entityId, fileId/objectId/chunkId); setanonymized,anonymizedValue,bases; persist BEFORE the OpenAnonymiser HTTP call. - 3.3 Construct the OpenAnonymiser request body from a copy of
payload.entities[]withbasesremoved from every entry. Confirm by inspection that the request body is byte-equivalent to the pre-change shape. - 3.4 Confirm the mapper does NOT issue any cross-register lookup to validate the supplied UUIDs. The persistence layer accepts any string array.
4. Unit tests
- 4.1 Add
tests/unit/Db/EntityRelationTest.phpcovering:getBases/setBasesround-trip;jsonSerializeincludesbases; null vs empty-array distinction is preserved. - 4.2 Add
tests/unit/Db/EntityRelationMapperTest.php(or extend an existing suite) covering: insert with bases; insert without bases (defaults to null); update bases on existing row; non-UUID strings are accepted; idempotent migration smoke test. - 4.3 Add
tests/unit/Service/FileServiceTest.phpcases for the anonymise-endpoint integration: persist precedes OpenAnonymiser call; OpenAnonymiser receives a request body withoutbases; OpenAnonymiser failure preserves the persisted bases on the row.
5. Integration tests
- 5.1 Add a Newman/Postman integration test (or extend the existing collection) for the anonymise endpoint with a
bases-populated payload. Verify: 200 response; EntityRelation row queried directly returns the correct bases. - 5.2 Add an integration test for the no-bases path: pre-change-shape payload still works, returns identical behaviour.
6. Cross-app regression check
- 6.1 Manually run the opencatalogi anonymise flow (if any). Confirm no break.
- 6.2 Smoke-test against DocuDesk's existing anonymise calls (without
bases). Confirm no break. - 6.3 Inspect the OpenAnonymiser request body via debug logging on a single test call. Confirm the body shape is unchanged from pre-change.
7. Documentation
- 7.1 Add an entry to
CHANGELOG.mdunder Added describing the new optionalbasescolumn onEntityRelationand the anonymise endpoint's persist+strip behaviour. - 7.2 Update the OpenAnonymiser interface contract documentation (if one exists in
docs/) to note thatbasesis recognised but stripped before the call. If no such doc exists, add a one-line comment onFileService::anonymizeDocumentreferencing the strip behaviour.
8. Quality and verification
- 8.1 Run the full unit test suite — clean.
- 8.2 Run static analysis (Psalm / PHPStan at the project's configured strictness) — clean.
- 8.3 Run code style (PHPCS at project config) — clean.
- 8.4 Manual smoke against a live stack: anonymise call with bases populated, confirm EntityRelation row has bases populated, confirm OpenAnonymiser was not sent the bases.
- 8.5 Run
openspec validate entity-relation-grondslagen— clean.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsIn review
Activity
Merge pull request #1494 from ConductionNL/feat/1435/entity-relation-…
chore(openspec): rework entity-relation-grondslagen per explore-mode …
feat(entity-relation-grondslagen): implement decision-metadata PATCH …
chore(openspec): rework entity-relation-grondslagen per explore-mode …
feat(entity-relation-grondslagen): implement decision-metadata PATCH …
chore(openspec): rework entity-relation-grondslagen per explore-mode …
feat(entity-relation-grondslagen): implement decision-metadata PATCH …