In dit document worden werkzaamheden voorgesteld teneinde het maken van [=FAIR=] dataproducten mogelijk te maken op uniforme, gestandaardiseerde en toegankelijke wijze. Hierbij zal LinkML als middel centraal staan.
Het werk omvat het beschrijven van definities, processen en werkwijzen; het bouwen en uitbreiden van benodigde software; en het verbeteren van (de beschikbaarheid van) referentiemodellen en de documentatie daarvan. Zie [[[#werkzaamheden]]] voor meer details.
Dit werk zal zich direct nuttig maken bij het opstellen van de [NBNL-profielgroep](https://github.com/Netbeheer-Nederland/doc-design-wg-sem-int), alsook zich laten voeden door de concrete vragen en uitdagingen die daar ervaren zullen worden.
## Status van dit document
Work in progress.
### Accordering door stakeholders
☐ Yun Wu (EDSN)
☐ Ritger Teunissen (Alliander)
☐ Tjeerd Schoemaker (EDSN)
## Executive summary
Alvorens dataproducten te kunnen maken is een formele vastlegging van wat onder een dataproduct verstaan wordt benodigd. Een formele beschrijving gebaseerd op een referentiemodel als DCAT of DX-PROF is daarbij wenselijk.
Een onmiskenbaar en belangrijk onderdeel van een dataproduct is het [=logisch gegevensmodel=] dat de structuur van de data erin beschrijft. Voor de vastlegging daarvan wordt LinkML gebruikt: een toegankelijke Linked Data-modelleertaal die mogelijkheden biedt om de betekenis van data expliciet te maken door verwijzingen naar referentiemodellen. Het is daarmee een uitermate geschikt middel om data [=FAIR=] mee te maken.
Verder komt LinkML met een ecosysteem aan software dat ondersteunt bij het maken van dataproducten, met name een tal van generatoren die mogelijk maken om fysieke datamodellen, documentatie en overige artefacten te genereren. Dit is enorm behulpzaam bij het realiseren van de technische implementatie van de dataservice die het dataproduct aan gaat bieden.
Wellicht de grootste uitdagingen komen echter vanuit het informatiemodelleringsperspectief. Het domein is complex en het modelleren van een usecase is moeilijk. Bovendien is het wenselijk dit FAIR te doen, wat bijvoorbeeld vraagt om termen uit referentiemodellen te gebruiken en een doordachte IRI-strategie voor globale identificatie te hanteren.
Om het modelleren van usecases eenvoudiger te maken zijn een aantal referentiemodellen (zoals het CIM en de CGMES-profielgroep) geconverteerd naar LinkML-schema's, zodat op basis daarvan schema's kunnen worden opgesteld waaraan vervolgens structuur en beperkingen kunnen worden toegevoegd om uitdrukking te geven aan de usecase.
Nog meer hulp kan worden verkregen door het gebruik van de LinkML Profiler. Dit is een applicatie waarmee een gegeven LinkML-schema kan worden geprofileerd, d.w.z. er wordt een snede uit het schema gemaakt. De gebruiker geeft een of meerdere klassen op en de profiler genereert een schema met enkel die klassen (en alle afhankelijkheden ervan).
---
Dataproductvoortbrengingsproces met LinkML
## Werkzaamheden
### Beschrijven, beheersen en beheren van dataproducten
TODO. (Refereer aan plaatje.)
#### Formele beschrijving van wat een FAIR dataproduct is
##### Omschrijving
De definitie van wat een dataproduct is dient formeel vastgelegd te worden door een datamodel op te stellen op basis van een referentiestandaard als [DCAT](https://www.w3.org/TR/vocab-dcat-3/) of DX-PROF. In het bijzonder kan gekeken worden naar reeds bestaande toepassingsprofielen (application profiles, of AP) op basis van DCAT gemaakt door de [EU](https://semiceu.github.io/DCAT-AP/releases/3.0.0/) en de [Nederlandse overheid](https://data.overheid.nl/en/ondersteuning/open-data/dcat).
Een machineleesbaar, formeel model:
- neemt veel discussie weg;
- maakt validatie van dataproductdefinities mogelijk;
- maakt generatie van (deel van de) documentatie mogelijk.
Dit datamodel kan in LinkML worden opgesteld met expliciete referenties naar de gebruikte termen uit de gewenste standaarden. Een voorbeelduitwerking van een in LinkML gedefinieerde, op DCAT-gebaseerde dataproductdefinitie voor Alliander kan [hier](https://github.com/Alliander/aim--dataproduct) worden raadgepleegd.
Aanvullend dient mensvriendelijke documentatie te worden geschreven over wat een dataproduct is. Voor de hand ligt om gegenereerde documentatie te daarmee verrijken.
Tot slot dient er nog voorgeschreven te worden hoe het FAIR uitwisselen van (instantie)data dient te worden ingevuld. Hierbij speelt Linked Data een cruciale rol, waarbij middelen als JSON-LD het toegankelijk maken.
##### Deliverables
- Een op standaarden gebaseerde formele beschrijving in de vorm van een logisch informatiemodel van wat een wat een dataproduct is;
- Mensvriendelijke documentatie;
- Vastlegging van de manier waarop met Linked Data uitwisseling van FAIR data mogelijk wordt gemaakt.
#### IRI-strategie voor dataproducten en verscheidene typen modellen
##### Omschrijving
Ter bevordering van de FAIR-principes is het van belang dataproducten en alle voorkomende typen informatiemodellen en de erin voorkomende elementen van een IRI te voorzien. Dit maakt eenduidige verwijzing mogelijk, wat cruciaal is voor o.a. datamanagement en datagovernance.
Het is daarbij van belang de volgende nuance te belichten. Stel, in een LinkML-schema definieer ik een klasse met zekere beperkingesregels, waarbij ik een (semantische) verwijzing naar een klasse in een referentiemodel opneem. Merk dan op dat de beperkende klassedefinitie in LinkML een andere resource is dan de klasse waarnaar wezen wordt, en dat beide dus een andere IRI hebben.
Er is veel reeds verricht werk voor hoe IRI's op te stellen, zowel nationaal als internationaal. Het is wijsheid op dat werk voort te borduren.
##### Deliverables
* Documenten waarin beschreven staat wat de IRI-strategie is voor de volgende typen modellen en elementen daarin:
* dataproducten;
* profielen en evt. profielgroepen;
* logische informatiemodellen en (bijvoorbeeld van dataproducten);
* conceptuele informatiemodellen;
* begrippenmodellen.
### Bruikbaarheid vergroten van referentiemodellen
TODO.
#### CIM: LinkML-schema's en documentatie verbeteren
##### Omschrijving
Het CIM is effectief een gestructureerd vocabulair waarin decennialange domeinexpertise is vastgelegd. Helaas is de bruikbaarheid van dit informatiemodel belemmerd doordat het informatiemodel beheerd wordt in een commerciële applicatie waar interoperabiliteit niet voor de hand ligt.
Verder is de documentatie van het CIM niet gebruiksvriendelijk, met name niet voor hen die niet gewend zijn aan het doorlezen van formele specificaties.
###### Verbetering kwaliteit van LinkML-schema's
Er is reeds werk verricht om het CIM in LinkML-schema's te representeren. De correctheid en compleetheid van de schema's dient verder te worden verbeterd. Daarbij is het van belang de gemaakte aannames en ervaren uitdagingen bij het genereren van de schema's te documenteren. Tot slot mogen de schema's met meer metadata verrijkt worden zoals versieinformatie.
###### Gebruiksvriendelijke documentatie
Zoals gezegd is de huidige documentatie van het informatiemodel niet gebruiksvriendelijk. Het zou helpen webdocumentatie te verzorgen, waarbij als basis de statisch gegenereerde documentatiebestanden van LinkML kunnen worden genomen.
Indien gewenst kunnen andere, visuele vormen van documentatie worden verkend. Denk hierbij met name aan een interactieve graafvisualisatie, die het perspectief van ontdekken vanuit een bekend startpunt benadrukt.
###### Dereferenceable IRI's
In de filosofie van Linked Data is het idee om IRI's dereferenceable te maken zodat de definitie en documentatie van de termen via standaard HTTP-verzoeken op te vragen is. Dit zal gerealiseerd worden in samenwerking met mensen uit de CIM-gemeenschap.
##### Deliverables
* LinkML-schema's voor het CIM van een volwassenheidsniveau dat ze bruikbaar maakt voor het opstellen van profielen en dataproducten;
* Gebruiksvriendelijke documentatie, publiek beschikbaar via het WWW;
* Dereferenceable IRI's teneinde termen zelfbeschrijvend te maken, waarbij de implementatie content-negotiation ondersteunt zodat zowel een machineleesbare als mensvriendelijke representatie van de beschrijving opgehaald kan worden.
#### CGMES: LinkML-schema's verbeteren
##### Omschrijving
Ook voor CGMES zijn LinkML-schema's gegenereerd. Vergelijkbaar met de uitleg voor het CIM hierboven, geldt dat de kwaliteit van de schema's mag worden verbeterd, alsook dat de gemaakte aannames en ervaren uitdagingen bij het genereren van de schema's mogen worden gedocumenteerd en de metadata mag worden verrijkt.
##### Deliverables
- LinkML-schema's voor het CIM van een volwassenheidsniveau dat ze bruikbaar maakt voor het opstellen van profielen en dataproducten.
#### IRI's voor Netbeheer Nederland-begrippenkader formaliseren
##### Omschrijving
Gebruikmakende van de [IRI-strategie](#IRI-strategie voor dataproducten en verscheidene typen modellen) dienen de IRI's van de begrippen(modellen) aangepast te worden.
Verder is het wenselijk de IRI's dereferenceable te maken. Zie voor meer details de uitleg onder [Dereferenceable IRI's](#Dereferenceable IRI's).
##### Deliverables
* Nieuwe IRI's toekennen aan de begrippen en schema's.
* IRI's dereferenceable maken zodat de definitie en documentatie van de begrippen via standaard HTTP-verzoeken op te vragen is.
### Hulpmiddelen bij het opstellen van dataproducten en profielen
TODO. (Het profileren van LinkML-schema's, ongeacht wat voor type model erin beschreven is.)
#### LinkML Profiler uitbreiden en toegankelijker maken
##### Omschrijving
De LinkML Profiler is een CLI-applicatie geschreven in Python waarmee eenvoudig een selectie uit een gegeven LinkML-schema kan worden gemaakt door aan te geven welke klassen interessant zijn. Dit levert een nieuw LinkML-schema op dat óf as-is gebruikt kan worden, óf verder uitgebreid of aangepast kan worden indien wenselijk.
###### Nieuwe features
De huidige versie van de profiler is nog relatief beperkt in de aangeboden features, maar nu al bewijst het een krachtig hulpmiddel in het modelleren op basis van CIM en CGMES. Zodra de software intensiever gebruikt wordt en ook door meerdere mensen, is te verwachten dat er feature requests zullen komen. Om deze op te pakken is tijd en mankracht nodig.
###### Toegankelijkheid en gebruiksgemak verbeteren
Het installeren van de CLI-applicatie is complex. De gebruiker dient over een Python-installatie te beschikken op diens systeem (en wél een compatibele versie) en de rechten en kennis te bezitten om virtual environments aan te kunnen maken om library's te installeren.
Een voor de hand liggende verbetering is een web-API bouwen die de functionaliteit van de profiler aanbiedt. Eigenaarschap en het serveren van de dienst dient dan tevens belegd te worden.
Een andere interessante optie is een herimplementatie van de CLI-applicatie in een andere programmeertaal waarbij het mogelijk is om te compileren naar binary executables. Tevens zal dit de performance ten gunste komen.
###### Grafische web-UI voor LinkML Profiler
Om het gebruiksgemak vele malen te vergroten is een grafische interface van groot belang. Een web-UI in bijvoorbeeld de vorm van een PWA is een geschikte keuze, omdat de applicatie daarmee crossplatform is en geen installatie vereist. Ook hier geldt dat eigenaarschap en het serveren van de dienst belegd dient te worden.
##### Deliverables
* CLI-applicatie van de LinkML Profiler met vereenvoudigde installatie en verbeterde gebruiksvriendelijkheid;
* Web-UI-frontend voor de LinkML Profiler;
Alle software is opensource en maakt geen domeinspecifieke aannames.
#### Editor-extensies bouwen voor het werken met LinkML-schema's
##### Omschrijving
LinkML-schema's zijn in YAML geschreven, en aangezien er van het LinkML-metamodel ook YAML- en JSON-serializatie bestaat is het mogelijk om in editors en IDE's gebruik te maken van features als syntactische checks en autocompletion. Hoewel dit handig is, is deze hulp erg beperkt. Wat kunnen we nog meer bedenken?
###### IRI-autocompletion vanuit andere modellen
Wat enorm krachtig zou zijn is de mogelijkheid om IRI-autocompletion te krijgen vanuit andere modellen, met name referentiemodellen als het CIM en NBNL-begrippenkader. Dit maakt het een stuk eenvoudiger en minder foutgevoelig om semantische verwijzingen te leggen.
Hoe op te geven vanuit welke modellen autocompletion wordt aangeboden is nader te onderzoeken. Één optie is om in ieder geval te kijken of iets slims gedaan kan worden met de prefixdeclaraties en imports van het schema.
###### Profileren van schema's
De profileerfunctionaliteit van de LinkML Profiler kan geïntegreerd worden in de editor-extensie. Dit maakt mogelijk om direct vanuit de editor op basis van een opgegeven klasse een geheel deel van een schema te kopiëren.
###### Opmerkingen over technische invulling
Indien mogelijk en niet te beperkend, is het interessant om te onderzoeken of een oplossing kan worden verzonnen die editoragnostisch is. Zo kan een languageserverimplementatie een interessante optie zijn. Indien toch een vaste editor gekozen gaat worden, is het vermoedelijk verstandig een gratis en populaire editor te nemen, zoals VS Code. Tot slot is ook het realiseren van een eigen web-based editor een optie, al zou ik dan eerder kijken naar een VS Code Remote Development-opzet.
Verder kan worden overwogen om een diversiteit aan technische typen bronnen voor term-autocompletion te ondersteunen (zoals LinkML-schema's, RDF-grafen en SPARQL-endpoints), en hoe om te gaan met lokale vs. remote beschikbare modellen.
##### Deliverables
* Een editorextensie die een rijkere developerexperience geeft voor het schrijven van LinkML-schema's.
* Rijkere autocompletion vanuit dynamisch op te geven modellen;
* Mogelijkheid om te profileren zoals met de LinkML Profiler, vermoedelijk gebruikmakend daarvan;
* Indien mogelijk is de extensie opensource en worden er geen domeinspecifieke aannames gemaakt.
### Technisch realiseren van dataproducten
#### Grafische UI bouwen voor de LinkML-generatoren
##### Omschrijving
De installatie en het gebruik van de LinkML-generatoren is omslachtig en foutgevoelig om dezelfde redenen als eerder uiteengezet voor de LinkML Profiler.
Om de generatoren voor eindgebruikers toegankelijker te maken is het een goed idee om een UI te maken ervoor. Een web-UI ligt voor de hand, maar andere mogelijkheden kunnen verkend worden.
##### Deliverables
* UI (frontend) voor de LinkML-generatoren.
* De applicatie is opensource en maakt geen domeinspecifieke aannames.
##### Geautomatiseerde PDF-documentatiegeneratie realiseren
##### Omschrijving
De MkDocs-webdocumentatie die door LinkML eenvoudig mogelijk wordt gemaakt is erg waardevol, maar er is vaak ook behoefte aan een draagbaar document in de vorm van Word- of PDF-formaat. Doorgaans worden deze documenten met de hand geschreven, wat erg veel tijd kost en bovendien een tweede bron van waarheid creëert.
Het genereren van een dergelijk document moet even eenvoudig en vanuit eenzelfde enkele bron van waarheid kunnen worden gedaan als dat het geval is voor de webdocumentatie.
##### Deliverables
* Software die een PDF-variant van de documentatie genereert.
#### Bouwen en aanpassen van LinkML-generatoren
##### Omschrijving
De LinkML-generatoren zijn enorm waardevol voor het bouwen van dataproducten, maar soms:
* is de kwaliteit van de uitvoer van de generator onvoldoende;
* zijn aannames of gemaakte conversiekeuzes in de generator anders dan gewenst voor ons gebruik;
* biedt een generator onvoldoende functionaliteit of opties;
* ontbreekt een generator volledig.
Zo kan het zijn dat we voor SQL DDL-code bepaalde modelleeraannames willen maken die aansluiten bij onze datawarehouses. Verder heeft LinkML geen generator voor Apache Avro-schema's, een veelgebruikt uitwisselingsstandaard voor streamingdata. Een dergelijke generator kan dan gebouwd worden, of zelfs een generator voor Avrotize-schema's, waarmee door gebruik van [`avrotize`](https://github.com/clemensv/avrotize) weer tal van fysieke datamodellen kunnen worden gegenereerd.
##### Deliverables
* Implementatie van LinkML-generatoren zodat alle door ons gewenste fysieke datamodellen ondersteund worden en van voldoende kwaliteit en rijkheid aan functionalitieit.
#### Procesbeschrijving, handleiding en voorbeelduitwerking van het bouwen van een dataproduct
##### Omschrijving
Er dienen hulpmiddelen beschikbaar te zijn voor het maken van dataproducten zodat teams zelfstandig op uniforme wijze dataproducten kunnen bouwen. Denk daarbij aan een handleiding die beschrijft wat te ondernemen stappen zijn en hoe deze uit te voeren. Dit dekt onderwerpen als het opstellen van logische informatiemodellen met LinkML, het profileren van referentiestandaarden als het CIM, hoe dataproducten te beheren in of naast de codebase van de voortbrengende applicatie, enzovoorts.
Daarnaast is het van belang om goede informatie aan te bieden over data-architectuur en informatiemodellering. Basale kennis van deze vakgebieden helpt teams begrijpen wat ze doen en waarom.
Naast dergelijke gebruiksvriendelijke hulpmiddelen kan overwogen worden een formele procesbeschrijving te modelleren.
Voor snelle naslag en troubleshooting kan een FAQ worden opgesteld.
Voorbeelden doen soms wonderen, dus wellicht is het een goed idee om een voorbeeld- of templaterepository op GitHub te maken. De bovengenoemde documentatie zou eventueel ook daar geplaatst kunnen worden (in de README en/of wiki).
De ambitie is om zoveel mogelijk te leren vanuit de praktijk, bijvoorbeeld van het maken van de NBNL-profielen en dataproducten die ontwikkeld worden binnen EDSN of RNB's.
##### Deliverables
Ten aanzien van het maken van een dataproduct en alles wat erbij komt kijken:
* gebruiksvriendelijke documenten zoals een handleiding en FAQ;
* een voorbeelduitwerking van een dataproduct gepubliceerd op GitHub;
* evt. een formele procesbeschrijving.
### Technische support en opensourcebijdragen
#### Verlenen van technische hulp aan gebruikers
##### Omschrijving
Het maken van dataproducten, het gebruik van LinkML en op een bepaalde manier denken over informatiemodellering zal voor veel mensen niet zonder slag of staat gaan. Daarbij zullen er ongetwijfeld bugs ontdekt worden en technische problemen zich voordoen.
Het is van belang tijd vrij te maken om hier aandacht aan te besteden.
##### Deliverables
* Vast aantal uur beschikbaar voor het verlenen van technische support en voor administratie zoals featurerequests;
#### Meehelpen LinkML te verbeteren
##### Omschrijving
Het LinkML-ecosysteem is aardig groot en er valt nog veel toe te voegen en te verbeteren. Het is van belang in contact te blijven met het team achter LinkML, onze invloed uit te oefenen op de doorontwikkeling en bij te dragen aan het project waar we kunnen.
Verder kan software die door ons ontwikkeld wordt - waarin geen domeinspecifieke aannames zijn gemaakt - opensource beschikbaar worden gesteld aan de LinkML-gemeenschap.
##### Deliverables
* Meehelpen verbeteren van LinkML door betrokken te blijven bij gesprekken en meehelpen met doorontwikkelen;
* Ontwikkelde software die relevant is voor anderen opensource beschikbaar stellen aan de LinkML-gemeenschap.
