Data-architectuur Jottem

1. Inleiding en lagenmodel

Dit document beschrijft de data-architectuur van het Jottem-platform: welke data waar wordt vastgelegd, hoe die door het platform stroomt en in welke vormen die aan de buitenwereld wordt aangeboden. Het sluitstuk is de outputcontrole: per output is nagegaan of alle benodigde data beschikbaar is in de eerdere lagen; de daarbij gevonden hiaten zijn direct in het datamodel verwerkt.

De data leeft in drie lagen:

Leidend principe (zie ook de systeemarchitectuur): standaarden aan de buitenkant - elke output volgt een open standaard zodat harvesters en aggregators (o.a. NDE) zonder maatwerk kunnen aansluiten - en PostgreSQL plus miiify en de Object Storage als bron van waarheid, zodat elke afgeleide store en elke output reproduceerbaar is.

2. ERD diagram

erDiagram

Organisatie {
  int id PK
  string naam
  string slug
  string beschrijving
  string website
  string NAAN
  string kleurenpalet
  string logo
  string favicon
}

Project {
  uuid projectId PK
  string naam
  string slug
  string beschrijving
  string oproep
  date startDatum
  date eindDatum
  string afbeelding
  string datasetLicentie
  string terminologiebronnen
  string status
  int organisatieId FK
}

Gebruiker {
  int gebruikersId PK
  string naam
  string email
  bool naamPubliek
  date bevestigingsDatum
  date registratieDatum
  date laatsteLoginDatum
  bool favorietenPubliek
}

GebruikerRol {
  int gebruikerRolId PK
  int gebruikersId FK
  int organisatieId FK
  string rol
}

Media {
  uuid mediaId PK
  string titel
  string beschrijving
  string bestandsnaam
  string genre
  string licentie
  int breedte
  int hoogte
  string mimeType
  string status
  string afkeurReden
  string herkenbaar
  float herkenbaarBetrouwbaarheid
  bool toestemmingPersonen
  string ark
  date creatieDatum
  date publicatieDatum
  date wijzigingsDatum
  int gebruikersId FK
  int organisatieId FK
  uuid projectId FK
}

Metadata {
  int metadataId PK
  uuid mediaId FK
  int gebruikersId FK
  string type
  string label
  string value
  string uri
}

Favoriet {
  int favorietId PK
  int gebruikersId FK
  uuid mediaId FK
  date creatieDatum
}

Verwijderverzoek {
  int verzoekId PK
  uuid mediaId FK
  string reden
  string email
  string status
  string toelichting
  date creatieDatum
  date afhandelDatum
}

Melding {
  int meldingId PK
  uuid mediaId FK
  string annotatieIri
  string reden
  string status
  date creatieDatum
  date afhandelDatum
}

Gebeurtenislog {
  int logId PK
  string type
  date tijdstip
  int organisatieId FK
  uuid projectId FK
  int gebruikersId FK
  string payload
  date verwerktOp
}

%% Project: campagne op organisatieniveau (bijv. "Smaak van Gouda"), beheerd door de
%% organisatiebeheerder. Elke organisatie heeft minstens een project; elke jottem hoort
%% bij precies een project (Media.projectId verplicht). Project.status: actief / afgerond.
%% Project.datasetLicentie: licentie van de projectdataset (datasetbeschrijving per project).
%% Project.terminologiebronnen: lijst van bron-URI’s uit het NDE Termennetwerk die binnen
%% dit project beschikbaar zijn voor term-URI’s (standaard: alle bronnen).
%% Publiek zichtbare identifiers (mediaId, projectId) zijn betekenisloze UUID’s; interne
%% id’s (gebruikersId e.d.) blijven interne sleutels.
%% Rollen: een gebruiker kan meerdere rollen hebben, per organisatie (GebruikerRol);
%% de rol platformbeheerder heeft geen organisatieId. Lidmaatschap van een organisatie
%% volgt uit de GebruikerRol-rijen. GebruikerRol is de LEIDENDE bron voor autorisatie;
%% de IdP (Authentik) doet uitsluitend authenticatie (koppeling via sub-claim).
%% Media.status: nieuw / goedgekeurd / afgekeurd / gedepubliceerd; afkeurReden alleen bij
%% afgekeurd. Afgekeurde jottems kunnen door de uploader worden bijgewerkt en opnieuw
%% ingediend (terug naar nieuw); gedepubliceerd volgt uit een gehonoreerd verwijderverzoek
%% (tombstone op de duurzame URL, schoning van alle outputs).
%% Verwijderverzoek.status: open / gehonoreerd / afgewezen.
%% Gebeurtenislog: bron voor statistieken (type: login, upload, goedkeuring, afkeuring,
%% annotatie, ...); persoonsgebonden regels worden na een bewaartermijn geaggregeerd of
%% geanonimiseerd (AVG).
%% Media.herkenbaar (ja/nee) + herkenbaarBetrouwbaarheid: resultaat van de Herkenbaar API
%% bij upload (paradata, geen gebruikersmetadata); toestemmingPersonen: verklaring van de
%% uploader dat toestemming van herkenbare personen is geregeld.
%% Media.titel/beschrijving/licentie, breedte/hoogte/mimeType en wijzigingsDatum zijn
%% toegevoegd n.a.v. de outputcontrole in de data-architectuur (IIIF-label/rights/canvas,
%% RDF schema:name/license, RSS en IIIF Change Discovery).
%% Organisatie.beschrijving/website: nodig voor publisher-informatie, IIIF provider en
%% RSS-channel. Gebruiker.naamPubliek: bepaalt of de naam als creator bij annotaties
%% getoond wordt.
%% Organisatie.NAAN en Media.ark zijn gereserveerd voor de ARK-fase (uitgesteld,
%% zie keuze-oplossingsrichting).
%% Locatie- en tijdlijngegevens (adres, openings-/sluitingsjaar, geo-WKT, archiefbron)
%% worden vastgelegd als Metadata-rijen op Media; er is geen apart locatiemodel.
%% De coordinaten komen van de speld die de uploader op de kaart prikt (lat/lon als
%% Metadata-rijen); er is geen geocoding-dienst in de MVP.
%% Melding: rapportage van een annotatie of reactie (spam/ongepast) door bezoekers;
%% annotatieIri wijst naar de W3C-annotatie in miiify, status: nieuw / afgehandeld /
%% afgewezen. Afhandeling door de moderator, gelogd in het Gebeurtenislog.
%% Gebeurtenislog is tevens de transactional outbox (zie systeemarchitectuur):
%% payload beschrijft de mutatie, verwerktOp markeert succesvolle doorwerking naar
%% Elasticsearch / Fuseki / Varnish-purge.

%% Relationships
Organisatie ||--o{ GebruikerRol : "kent"
Organisatie ||--o{ Media : "bevat"
Organisatie ||--o{ Project : "voert_uit"

Project ||--o{ Media : "verzamelt"

Gebruiker ||--o{ GebruikerRol : "heeft"
Gebruiker ||--o{ Media : "uploadt"

Media ||--o{ Metadata : "heeft"

Gebruiker ||--o{ Favoriet : "maakt"
Media ||--o{ Favoriet : "wordt_gefavoriet"

Media ||--o{ Verwijderverzoek : "betreft"
Media ||--o{ Melding : "betreft"
Organisatie ||--o{ Gebeurtenislog : "logt"

Gebruiker ||--o{ Metadata : "maakt"

3. URI-strategie en content negotiation

Elke gepubliceerde jottem krijgt een duurzame platform-URL die als identifier in alle outputs wordt gebruikt:

Deelbaarheid. Elke jottem-detailpagina toont deelknoppen naar sociale media en de HTML-weergave bevat Open Graph-metadata, zodat gedeelde links (ook via de deel-oproep in de goedkeuringsmail) een nette preview tonen:

De duurzame jottem-URL ondersteunt content negotiation: Accept: text/html levert de HTML-weergave (IIIF-viewer + metadata + annotaties), application/ld+json, text/turtle of application/rdf+xml levert de RDF-representatie conform schema.org AP NDE (303-redirect naar data.iotm.nl). De mediaId en projectId zijn niet-herbruikbare, betekenisloze identifiers (UUID); duurzame data-URI’s zijn daarop gebaseerd, terwijl publiekspagina’s leesbare slugs gebruiken. Zo kan in de latere ARK-fase (zie het keuzedocument) een ARK ark:/{NAAN}/{shoulder}{mediaId} zonder linkbreuk op dezelfde resource worden gelegd.

4. IIIF

4.1. IIIF Image API v3

Cantaloupe serveert per gepubliceerde jottem info.json, tiles, regio’s en formaten op basis van de pyramidal TIFF/JP2-afgeleide in de Object Storage (derivatives-bucket). De benodigde data:

4.2. IIIF Presentation API v3 (Manifest en Collection)

De backend genereert per jottem een Manifest en per organisatie en per project een Collection (met iiif-prezi3), rechtstreeks uit de database:

Audio-jottems (fase 2, zie de uploadscope in de requirements) krijgen een manifest met een audio-canvas (duration; vastgelegd bij verwerking van de upload) en het bestand uit de audio-bucket als painting annotation.

4.3. IIIF Change Discovery v1

Per organisatie publiceert de backend een ActivityStreams-feed (OrderedCollection met pages) waarmee harvesters nieuwe en gewijzigde jottems kunnen volgen:

Regel: elke mutatie die de outputs raakt - metadata-wijziging, nieuwe/gewijzigde/verwijderde annotatie, depublicatie - werkt Media.wijzigingsDatum bij, zodat de Change Discovery-feed (en schema:dateModified in de RDF) ook annotatie-wijzigingen omvat, zoals de usecase voor API-gebruikers vraagt. Het verwijderen van een annotatie levert daarbij een Update-activity op de jottem op (géén Delete: de jottem zelf blijft bestaan; Delete/tombstone is voorbehouden aan depublicatie van de jottem). De AnnotationCollections komen live uit miiify en tonen de verwijderde annotatie direct niet meer; de workers hersynchroniseren daarna de named graph in Fuseki en de zoekindex via het outbox-mechanisme uit de systeemarchitectuur.

5. Annotaties

Annotaties volgen het W3C Web Annotation Data Model en worden opgeslagen in miiify; lezen kan publiek en standaardconform via het W3C Web Annotation Protocol op anno.iotm.nl (de Miifi API). Schrijven verloopt via de beheer-API, die de geauthenticeerde gebruiker als creator toevoegt en autorisatie bewaakt (eigen annotaties bewerken en verwijderen; de git-backend van miiify bewaart de versiegeschiedenis).

5.1. Ontsluiting: AnnotationCollection per jottem en per organisatie

De annotatieserver hanteert één container per jottem (containernaam = mediaId). Daarmee zijn annotaties op drie niveaus opvraagbaar, telkens W3C-conform:

6. RDF en datadump

6.1. Mapping naar schema.org AP NDE

Een worker mapt elke gepubliceerde jottem naar RDF conform het schema.org-profiel van NDE en upsert deze in Fuseki (named graph per organisatie). De representatie is opvraagbaar via content negotiation op de duurzame URL, via SPARQL en via de datadump.

Persoonsgegevens van inzenders komen niet in de RDF: de inzender wordt alleen als schema:contributor opgenomen indien Gebruiker.naamPubliek.

6.2. Datasetbeschrijving en datadump

Per project publiceert het platform een datasetbeschrijving als schema:Dataset conform de NDE-requirements voor datasets, aanmeldbaar bij het NDE Datasetregister; de platformbrede datacatalogus (schema:DataCatalog, /datacatalog) bundelt alle projectdatasets. Omdat elke jottem bij precies één project hoort, dekken de projectdatasets samen alle gepubliceerde data.

De datadump wordt per project periodiek (nachtelijks) door een worker gegenereerd uit Fuseki (named graph per project) en is tevens onderdeel van de exit-/exportstrategie uit het keuzedocument: de dumps plus de mediabestanden vormen samen een volledige, herbruikbare export van de gepubliceerde data.

Beheer en aanmelding. De organisatiebeheerder bewerkt per project de velden waaruit de datasetbeschrijving wordt gegenereerd (Project.naam, beschrijving, datasetLicentie; publisher-gegevens uit de organisatie) en kan de beschrijving - uitsluitend wanneer het project openbare (gepubliceerde) data heeft - valideren en aanmelden bij het NDE Datasetregister via de Datasetregister-API: de backend valideert eerst tegen het SHACL-shape van het register (PUT /datasets/validate), meldt daarna de URL van de datasetbeschrijving aan (POST /datasets) en kan deze ook weer afmelden (DELETE /datasets). Het domein iotm.nl moet daarvoor eenmalig op de allowlist van het register staan (POST /allowed-domains). Zie de bijbehorende endpoints in de beheer-API.

6.3. Aanvullende distributies (verkenning)

Naast de RDF-datadump en het SPARQL-endpoint kunnen ook de andere outputkanalen van een project als schema:distribution in de projectdatasetbeschrijving worden opgenomen; een distributie vereist slechts een schema:contentUrl en schema:encodingFormat, en het SHACL-shape van het register staat extra distributies toe. Dat maakt álle toegangswegen tot de projectdata vindbaar via één datasetbeschrijving:

Aanbeveling: alle kandidaten als extra distributies opnemen - de endpoints bestaan in de publieke API, het is louter een uitbreiding van de gegenereerde projectdatasetbeschrijving. Alle kandidaten zijn volledig afleidbaar uit de bestaande bronlagen; er is geen nieuwe brondata nodig.

6.4. E-depot-export: BagIt als verpakking, RO-Crate als beschrijving

Naast de RDF-datadump kan per project een compleet exportpakket worden aangemaakt waarmee al het materiaal van een project kan worden aangeboden aan het e-depot van een archiefinstelling (het SIP in OAIS-termen), en dat tevens de exit-strategie uit het keuzedocument concreet maakt:

• **BagIt (RFC 8493) als omhulsel** - een zip met data/-payload en checksummanifesten (manifest-sha512.txt, bag-info.txt), zodat de ontvangende instelling bit-integriteit bij ingest kan verifiëren. BagIt wordt native ondersteund door Archivematica en wordt probleemloos geaccepteerd door Preservica - de systemen achter de meeste Nederlandse e-depots.

• **RO-Crate als inhoudelijke beschrijving** - een ro-crate-metadata.json (JSON-LD op basis van schema.org) die alle bestanden in het pakket beschrijft en relateert. Omdat de Jottem-metadata al schema.org AP NDE is, volgt de crate vrijwel direct uit de bestaande RDF-mapping; het pakket blijft daardoor ook búiten een e-depot zelfbeschrijvend en herbruikbaar.

{projectSlug}-{datum}.zip  (BagIt)
├── bagit.txt / bag-info.txt          project, organisatie, datum, aantallen
├── manifest-sha512.txt               checksums van alle payload-bestanden
└── data/
    ├── ro-crate-metadata.json        beschrijft alles (schema.org)
    ├── dump.nt.gz                    de RDF-datadump van het project
    ├── media/{mediaId}.(tif|jpg|…)   originelen uit de Object Storage
    ├── metadata/{mediaId}.jsonld     per jottem (schema.org AP NDE)
    └── annotaties/{mediaId}.jsonld   W3C Web Annotations per jottem

Een instellingsspecifieke metadatalaag (MDTO, of een E-ARK SIP/CSIP-structuur) wordt bewust niet standaard gegenereerd: Nederlandse e-depots verschillen daarvoor te sterk (zie de infrastructuuranalyse); zo’n laag is maatwerk per ontvangende instelling en kan bovenop de bag worden toegevoegd. METS/PREMIS genereert het e-depot zelf bij ingest.

Proces. De organisatiebeheerder start de export per project; een worker stelt het pakket asynchroon samen (originelen uit de Object Storage, metadata en annotaties uit de bronlagen) en plaatst het in een aparte exports-bucket met beperkte bewaartermijn. Zodra het pakket klaar is, ontvangt de organisatiebeheerder een e-mail met een directe downloadlink.

7. API-beschrijvingen

De API is gesplitst in een publieke lees-API (zonder authenticatie, voor bezoekers en API-gebruikers/harvesters) en een beheer-API (OIDC Bearer-authenticatie, voor uploaden, modereren en beheren).

7.1. Publieke API

7.2. Beheer-API

8. RSS

Twee feedtypen conform de RSS 2.0-specificatie: een platformbrede feed met nieuwe organisaties en per organisatie een feed met nieuwe jottems.

9. Vocabulaires en termen

Vaste waardelijsten voorkomen vrije-tekstwildgroei en maken facetteren en linken mogelijk:

• Genre/materiaaltype (Media.genre): foto, menukaart, advertentie, folder, krantenartikel, vergunning, audio, overig - elk gekoppeld aan een term uit de Cultuurhistorische Thesaurus (CHT), opgezocht via het NDE Termennetwerk (zie hieronder). De waardelijst met bijbehorende CHT-URI’s is platformconfiguratie.

• Metadata-types (Metadata.type): vervaardiger, datering, plaats, adres, openingsjaar, sluitingsjaar, persoon, gebouw, bedrijf, gebeurtenis, archiefbron, steekwoord, standpunt (WKT), zichtveld (WKT), herinnering.

• Annotatiemotivaties (motivation, W3C-vocabulaire): describing (herinnering), commenting (reactie), identifying (persoon/gebouw/bedrijf op vlak), tagging (steekwoord), linking (archiefbron, gebeurtenis), editing (correctie).

• Term-URI’s: bij plaatsnamen, personen, gebeurtenissen en gebouwen wordt naast het label een URI vastgelegd (Metadata.uri resp. annotation body), zodat de RDF-output linkbaar is.

9.1. NDE Termennetwerk (GraphQL)

Alle term-lookups (genres én term-URI’s) verlopen via de GraphQL API van het NDE Termennetwerk (https://termennetwerk-api.netwerkdigitaalerfgoed.nl/graphql), één externe API die zoeken in vele terminologiebronnen bundelt (CHT, Wikidata, GTAA, thesauri van RKD, RCE, e.a.):

• de sources-query levert de lijst van beschikbare terminologiebronnen;

• de terms-query zoekt een term in één of meer gekozen bronnen en levert label + URI.

Terminologiebronnen per project. De organisatiebeheerder stelt per project in welke terminologiebronnen beschikbaar zijn voor term-URI’s (Project.terminologiebronnen, een lijst van bron-URI’s uit de sources-query; standaard staan alle bronnen open). De upload- en annotatie-interfaces beperken hun terms-queries tot die bronnen, zodat bijdragers per project passende thesauri aangeboden krijgen (bijv. CHT + Wikidata voor Smaak van Gouda). De backend biedt hiervoor een sources-proxy in de beheer-API.

10. Zoekindex en geo-data

Elasticsearch is een afgeleide store, gevuld door de indexeer-worker bij publicatie of wijziging (incl. annotatie-mutaties):

Geo-data wordt vastgelegd als WKT/GeoJSON in Metadata-rijen (adres/locatie van de jottem, standpunt fotograaf, zichtveld) en in annotatie-bodies, en gebruikt in: de kaart-frontend (MapLibre), de pand-tijdlijn (adres + openings-/sluitingsjaar), de koppeling met externe tijdmachines (zoals de Gouda Tijdmachine), Elasticsearch (geo-queries) en de RDF (schema:geo). Voor IIIF is de navPlace-extensie een optie om geo-informatie ook in manifests op te nemen.

11. Outputcontrole (traceability)

De veld→bron-tabellen in de voorgaande secties vormen de controle of alle benodigde data aan de outputkant beschikbaar is in de bronlagen. Daarbij zijn de volgende hiaten gevonden; deze zijn direct in het ERD verwerkt:

Aandachtspunten die geen datamodel-wijziging vragen maar wel een implementatieregel zijn:

• Reproduceerbaarheid: Elasticsearch en Fuseki zijn volledig herbouwbaar uit PostgreSQL + miiify + Object Storage; een herindexeer-/hersync-taak hoort bij de beheervoorzieningen. Ook de e-depot-export is volledig afleidbaar uit deze bronlagen.

• Depublicatie: bij een gehonoreerd verwijderverzoek worden alle outputs geschoond (index, RDF/named graph, feeds, IIIF-cache-purge) en resteert een tombstone op de duurzame URL.

• Audio (fase 2): duration wordt bij verwerking van audio-uploads vastgelegd (technische metadata bij het mediabestand) ten behoeve van het IIIF-canvas.

• Vocabulaire-URI’s (genre e.d.) zijn configuratie, geen databasemodel; ze moeten wel versioneerbaar beheerd worden. De per project beschikbare terminologiebronnen komen uit Project.terminologiebronnen (zie § 9.1 NDE Termennetwerk (GraphQL)).