Skip to Content
Last modified by Robert Schaub on 2025/12/24 20:35
From version 3.1
edited by Robert Schaub
on 2025/11/27 12:08
Change comment: There is no comment for this version
To version 5.2
edited by Robert Schaub
on 2025/11/27 12:31
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,3 +1,7 @@
1 +(((
2 +
3 +)))
4 +
1 1  = 5. Data Model =
2 2  
3 3  The FactHarbor data model centers on four fully versioned, immutable entities:
... ... @@ -57,6 +57,13 @@
57 57  The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
58 58  and fields with {{code}}...IdFk{{/code}} are foreign keys.
59 59  
64 +{{comment}} Core Data Model ERD (Mermaid, from /Specification/Diagrams/Data Model) {{/comment}}
65 +{{include document="FactHarbor.Playground.Core Data Model ERD Page (from Specification chat).WebHome"/}}
66 +
67 += Core Data Model ERD (Versioned) =
68 +
69 +This diagram shows the full core data model with all versioned entities.
70 +
60 60  {{mermaid}}
61 61  erDiagram
62 62   CLAIM_CLUSTER {
... ... @@ -147,9 +147,14 @@
147 147  
148 148   SCENARIO ||--o{ VERDICT : assessed
149 149   VERDICT ||--o{ VERDICT_VERSION : versions
150 -
151 151  {{/mermaid}}
152 152  
163 +{{info}}
164 +All key entities are explicitly versioned here (…VERSION tables).
165 +This reflects the versioning requirements in the textual Data Model chapter.
166 +{{/info}}
167 +
168 +
153 153  **Important points:**
154 154  
155 155  * Scenarios and Evidence are **linked via their versions**
... ... @@ -170,6 +170,14 @@
170 170  * Roles and role assignments
171 171  * Review actions on versioned entities
172 172  
189 +{{comment}} Data Use ERD (Mermaid, from /Specification/Diagrams/Data Use ERD) {{/comment}}
190 +{{include document="FactHarbor.Playground.Data Use ERD Page (from Specification chat).WebHome"/}}
191 +
192 += Data Use ERD (Roles, Review & Versioned Entities) =
193 +
194 +This diagram shows how users, roles, and review actions relate to the
195 +versioned core entities.
196 +
173 173  {{mermaid}}
174 174  erDiagram
175 175   %% Core clusters shown for context
... ... @@ -310,9 +310,16 @@
310 310   REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
311 311   REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
312 312   REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
313 -
314 314  {{/mermaid}}
315 315  
339 +{{info}}
340 +This diagram focuses on *who* uses and reviews *which* versioned entities.
341 +USER is the base type; TECHNICAL_USER and CONTRIBUTING_USER are specializations.
342 +Other roles (REVIEWER, EXPERT, TRUSTED_CONTRIBUTOR, FEDERATION_ADMIN, FEDERATION_NODE)
343 +are modelled as specializations or technical subtypes.
344 +{{/info}}
345 +
346 +
316 316  Notes:
317 317  
318 318  * Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
... ... @@ -379,3 +379,173 @@
379 379  Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
380 380  replication logs, and trust rules) are described in the Federation &
381 381  Decentralization chapter and build on top of the core data model defined here.
413 +
414 +----
415 +
416 +== 1. Overall analysis & review of the data model ==
417 +
418 +=== 1.1 Strengths of the current design ===
419 +
420 +* (((
421 +**Identity vs. version pattern**
422 +Using base entities plus version entities (CLAIM + CLAIM_VERSION, SCENARIO + SCENARIO_VERSION, etc.) is exactly how modern knowledge systems handle:
423 +
424 +* auditability
425 +* time evolution
426 +* re-evaluation triggers
427 +* federation and partial replication
428 +)))
429 +* (((
430 +**Scenario-centric reasoning**
431 +Separating //Claim// (what people argue about) from //Scenario// (interpretive frame) is very aligned with “truth landscape” style systems:
432 +
433 +* Scenarios explain //why people disagree//.
434 +* Verdicts are tied to specific scenario versions → avoids mixing incompatible assumptions.
435 +)))
436 +* **Evidence and verdicts as first-class entities**
437 +Evidence is explicit, linked to scenarios, and verdicts are per scenario. This matches good practice from fact-checking, scientific assessment panels, and trust graphs.
438 +* (((
439 +**Cluster level (CLAIM_CLUSTER)**
440 +Grouping related claims avoids duplication and lets you:
441 +
442 +* reuse scenarios across paraphrases
443 +* share embeddings / semantic search
444 +* keep the system scalable as the corpus grows.
445 +)))
446 +* (((
447 +**Explicit review layer (REVIEW_ACTION, roles, etc.)**
448 +Separating “data” from “who reviewed what” keeps the model clean, and is exactly what you want for:
449 +
450 +* governance
451 +* permissions
452 +* audit trails
453 +* future trust scoring per user / role.
454 +)))
455 +
456 +----
457 +
458 +=== 1.2 Design decisions I’m locking in (based on our discussions) ===
459 +
460 +To make the model consistent and “state-of-the-art”, I will assume the following as //current intended design//:
461 +
462 +1. (((
463 +**Claims vs Scenarios**
464 +
465 +* CLAIM is the stable identity for “what people argue about”.
466 +* CLAIM_VERSION are individual phrasings / formulations / metadata.
467 +* (((
468 +SCENARIO belongs to a **CLAIM**, not to a specific CLAIM_VERSION.
469 +Rationale:
470 +
471 +* Many different phrasings share the //same// scenario.
472 +* You avoid duplicating scenarios per wording.
473 +)))
474 +* SCENARIO_VERSION holds detailed definitions, assumptions, boundaries, etc.
475 +)))
476 +1. (((
477 +**Version-specific reasoning**
478 +
479 +* **Verdicts** are always attached to SCENARIO_VERSION (not base SCENARIO).
480 +* **Evidence links** are between SCENARIO_VERSION and EVIDENCE_VERSION.
481 +→ This is what we agreed when we said //“SCENARIO_EVIDENCE_LINK should link the respective versions instead”//.
482 +)))
483 +1. (((
484 +**Clusters**
485 +
486 +* CLAIM_CLUSTER groups Claims (semantically close claims).
487 +* It is visible in **both diagrams** (Core Data Model and Data Use).
488 +)))
489 +1. (((
490 +**Review vs data**
491 +
492 +* (((
493 +All review happens **on versioned entities**:
494 +
495 +* CLAIM_VERSION
496 +* SCENARIO_VERSION
497 +* EVIDENCE_VERSION
498 +* SCENARIO_EVIDENCE_LINK_VERSION
499 +* VERDICT_VERSION
500 +)))
501 +* REVIEW_ACTION is the generic log of //who// did //what// on //which version//.
502 +)))
503 +1. (((
504 +**Users & roles**
505 +
506 +* USER has an attribute (or a linked entity) that distinguishes **technical users** from normal accounts.
507 +* We //keep// TECHNICAL_USER as a specialisation of USER (strictly technical accounts).
508 +* All human & technical accounts can hold roles via USER_ROLE_MEMBERSHIP.
509 +* (((
510 +Roles include:
511 +
512 +* READER
513 +* CONTRIBUTOR
514 +* TRUSTED_CONTRIBUTOR
515 +* REVIEWER
516 +* MODERATOR
517 +* SYSTEM_ADMIN / MAINTAINER
518 +* FEDERATION_OPERATOR
519 +* FEDERATION_ADMIN
520 +(all present in the Data Use ERD, but as rows of ROLE rather than separate entities).
521 +)))
522 +)))
523 +
524 +----
525 +
526 +=== 1.3 Gaps / potential problems ===
527 +
528 +These are the main issues & missing areas I see:
529 +
530 +1. (((
531 +**Versioning text in chapter 5 is currently too thin (‘…’ placeholders)**
532 +
533 +* (((
534 +The spec does not yet //verbally// spell out:
535 +
536 +* the identity vs version pattern, systematically
537 +* how re-evaluation triggers are derived from version changes
538 +* how this aligns with federation (which versions are replicated where).
539 +)))
540 +)))
541 +1. (((
542 +**No explicit “provenance granularity” in the model**
543 +
544 +* (((
545 +EVIDENCE is a single entity. For more advanced use cases, you may later want:
546 +
547 +* EVIDENCE_SOURCE (the whole article/report/video)
548 +* EVIDENCE_FRAGMENT (specific paragraph/clip with its own reliability, quote, etc.)
549 +)))
550 +* For now, I’ll keep EVIDENCE/EVIDENCE_VERSION as is, but I’ll mention this as a possible extension.
551 +)))
552 +1. (((
553 +**Review target polymorphism**
554 +
555 +* (((
556 +REVIEW_ACTION can apply to multiple entity types. In the diagram this shows as multiple relationships:
557 +
558 +* CLAIM_VERSION → REVIEW_ACTION
559 +* SCENARIO_VERSION → REVIEW_ACTION
560 +* etc.
561 +)))
562 +* A more “pure” relational modeling would use a generic “subjectType + subjectId” or an intermediate “REVIEW_TARGET” table.
563 +* For readability, I’ll keep the simpler multi-edge representation and mention the polymorphism in text.
564 +)))
565 +1. (((
566 +**Federation details missing from core ERD**
567 +
568 +* There is no explicit FEDERATION_NODE / REPLICATION_LOG in the Data Model chapter.
569 +* This is ok for “core logical data model”, but I’ll add a short note that federation metadata is handled in the Federation chapter and via additional entities.
570 +)))
571 +1. (((
572 +**Automation / AKEL artifacts left implicit**
573 +
574 +* (((
575 +The Data Model chapter currently doesn’t describe:
576 +
577 +* AKEL task queues
578 +* extraction runs
579 +* model versions
580 +)))
581 +* That’s fine for now; I’ll just clarify that those belong to a “Processing / AKEL” submodel, not the core logical data model.
582 +)))