Datastations-met-KIK-Starter-specifieke-extensies.md

+# Inleiding
+In onderstaande tekst staat beschreven hoe een standaard Verpleeghuis datastation moet worden uitgebreid om met de VOLT Decentraal te communiceren en gegevens uit te wisselen.
+
+Om met de VOLT Decentraal samen te werken met een standaard datastation is het nodig om een aantal uitbreidingen toe te voegen aan uw standaard datastation.
+
+# Uitbreidingen
+De uitbreidingen zijn nodig om gebruik te kunnen maken van de validatieservice in de VOLT Decentraal.
+
+De volgende uitbreidingen worden hieronder toegelicht:
+
+1. Geen extra functionaliteit, enkel een datastation
+1. SPARQL endpoint
+1. GRAPHSTORE endpoint
+1. SHACL endpoint
+
+Volgorde van toenemende complexiteit, maar ook in volgorde van toenemende toepasbaarheid.
+
+# Wat zijn de basisvereisten?
+Er moet een datastation aanwezig zijn conform de standaard specificaties (https://kik-v.github.io/datastation)
+De specificaties zijn bedoeld voor software ontwikkelaars en beheerders.
+
+# Wie vormt de doelgroep van deze specificaties?
+Deze specificaties zijn bedoeld voor software ontwikkelaars die deze uitbreidingen realiseren voor de zorgaanbieder met een standaard datastation.
+Waarom zijn de endpoints nodig?
+
+# Waarom zijn de endpoints nodig?
+De VOLT Decentraal voert op verzoek validaties uit op de dataset in uw datastation. Afhankelijk van de manier waarop u uw datastation inricht legt dat een belasting op hoeveelheid geheugen en werklast, netwerkverkeer en verspreiding van eventueel gevoelige informatie die beter op een plek kan blijven.
+
+| VOLT Functie | Datastation | Level 1 (SPARQL) | Level 2 (GRAPHSTORE) | Level 3 (SHACL) |
+| --- | --- | --- | --- | --- |
+| Query, uit profiel | x | x | x | x |
+| Query, custom | | x | x | x |
+| Validatie, small dataset | | (x)* | (x)* |  x |	
+| Validatie, medium dataset *) | | | (x)* |  x |	
+| Validatie, any dataset | | | | x |
+
+*) Onderdelen gemarkeerd met een asterisk maken een kopie van de data in de VOLT, waardoor de belasting en het netwerkverkeer toenemen en bewaren potentieel gevoelige data buiten de controle van het datastation.
+
+# Wat moet mijn datastation ondersteunen?
+Bij voorkeur realiseert u in ieder geval een SPARQL endpoint. GRAPHSTORE en SHACL endpoints zijn nice to haves.
+
+Hoe maak ik een SPARQL endpoint?
+Zie standaard: https://www.w3.org/TR/sparql11-protocol/
+Alleen sectie 2.1 (query) is vereist
+
+## Query/response example
+Hoe maak ik een GRAPHSTORE endpoint?
+Zie standaard: https://www.w3.org/TR/sparql11-http-rdf-update/
+Alleen sectie 5.2 (HTTP GET) is vereist
+
+## Query/response example
+Hoe maak ik een SHACL endpoint?
+Zie: https://jena.apache.org/documentation/shacl/index.html
+SHACL standard: https://www.w3.org/TR/shacl/ 
+
+Validatie met shapes in ``fu-shapes.ttl`` waarmee je het validatie rapport (zie SHACL standaard sectie 3.6) terug ontvangt:
+
+``curl -XPOST --data-binary @fu-shapes.ttl  \``  
+
+``     --header 'Content-type: text/turtle' \``  
+
+``     'http://localhost:3030/ds/shacl?graph=default'``
+
+_Specificatie SHACL endpoint staat in bijlage 1._
+
+In Java, the Apache Jena Fuseki RDF store/server (https://jena.apache.org/documentation/fuseki2/index.html) supports all the above operations.
+
+Die standaarden hebben onze voorkeur.
+
+# Authenticatie en authorisatie
+
+De volgende vormen van authenticatie hebben de voorkeur:
+
+1. Token Bearer met JSON Web Tokens (JWT).
+1. HTTP Basic authenticatie
+
+Encrypted with TLS 1.2/1.3, no two-way TLS necessary, trusted/PKIOverheid certificate (server-side).  Allow user uploading/manually approving a non-trusted cert? Probably yes, but guard this behind a configuration option that’s switched off by default.
+
+Geëncrypt met TLS 1.2/1.3, geen two-way TLS nodig, trusted/PKIOverheid certificaat (server-side).  Stelt dit gebruikers in staat om een non-trusted certificaat te uploaden of handmatrig goed te keuren? Ja, waarschijnlijk wel, maar vergrendel dit achter een configuratie optie dat standaard uitgeschakeld is.
+
+Het is mogelijk om een niet-vertrouwde certificaat tijdelijk te vertrouwen. Dit is bedoeld voor developers tijdens de ontwikkeling.
+
+De optie om tijdelijk niet-vertrouwde certificaten toch te vertrouwen wordt bij het opstartcommando van de VOLT decentraal meegegeven.
+
+## Credentials
+Een datastation moet voor de kwaliteitsinformatie verpleeghuiszorg de scopes "sparql", “graphstore”, en “shacl” gebruiken for each of the 3 services.
+
+Optimally, VOLT has these 3 scopes in addition to the standard  “verifiedsparql”, but it can work with any subset with limited functionality.
+
+In de ideale situatie heeft de VOLT drie scopes in aanvulling op de standaard “verifiedsparql”, maar het kan met elke subset met gelimiteerde functionaliteit werken.
+
+Uitgangspunt is dat elke zorgaanbieder deze scopes toewijst in de eigen authorisatiedienst.
+
+# Data catalogus
+Hieronder is een beschrijving van de eerder genoemde endpoint services die in eerste instantie intern zichtbaar zijn. Het is mogelijk om in de toekomst dat derde partijen deze services extern aanspreken om diensten uit te breiden of over te nemen van de centrale VOLT.
+
+Voorbeeld 11 uit Datastation specificatie:
+
+``:dist-validatequery``
+
+``  a dcat:Distribution ;``
+
+``  dcat:accessService :verifiedsparql-service ;``
+
+``  dct:conformsTo <https://www.w3.org/TR/rdf-schema/> ;``
+
+``  dct:title "RDF distributie voor kwaliteitsinformatie."@nl .``
+
+``:verifiedsparql-service``
+
+``  a dcat:DataService``
+
+``  dct:conformsTo <https://verwijzing-naar-de-gepubliceerde-specificatie/> ;``
+
+``  dct:title "Gevalideerde vragen"@nl ;``
+
+``  dct:description "Service voor het uitvoeren van gevalideerde vragen via sparql"@nl ;``
+
+``  dcat:endpointURL <http://data.example.com/api/verifiedsparql> .``
+
+Breid uit met specificatie:
+
+``:dist-validatequery``
+
+``  a dcat:Distribution ;``
+
+``  dcat:accessService :verifiedsparql-service ;``
+
+``  dcat:accessService :sparql-service ;``
+
+``  dcat:accessService :graphstore-service ;``
+
+``  dcat:accessService :shacl-service ;``
+
+``  dct:conformsTo <https://www.w3.org/TR/rdf-schema/> ;``
+
+``  dct:title "RDF distributie voor kwaliteitsinformatie."@nl .``
+
+``:verifiedsparql-service``
+
+``  a dcat:DataService``
+
+``  dct:conformsTo <https://verwijzing-naar-de-gepubliceerde-specificatie/> ;``
+
+``  dct:title "Gevalideerde vragen"@nl ;``
+
+``  dct:description "Service voor het uitvoeren van gevalideerde vragen via sparql"@nl ;``
+
+``  dcat:endpointURL <http://data.example.com/api/verifiedsparql> .``
+
+``:sparql-service``
+
+``  a dcat:DataService``
+
+``  dct:conformsTo <https://www.w3.org/TR/sparql11-protocol/> ;``
+
+``  dct:title "SPARQL"@nl ;``
+
+``  dct:description "Service voor het uitvoeren van gevalideerde vragen via sparql"@nl ;``
+
+``  dcat:endpointURL <http://data.example.com/api/sparql> .``
+
+``:graphstore-service``
+
+``  a dcat:DataService``
+
+``  dct:conformsTo <https://www.w3.org/TR/sparql11-http-rdf-update/> ;``
+
+``  dct:title "GRAPHSTORE"@nl ;``
+
+``  dct:description "Service voor het uitvoeren van gevalideerde vragen via sparql"@nl ;``
+
+``  dcat:endpointURL <http://data.example.com/api/graphstore> .``
+
+``:shacl-service``
+
+``  a dcat:DataService``
+
+``  dct:conformsTo <https://verwijzing-naar-de-gepubliceerde-specificatie/shacl> ;``
+
+``  dct:title "SHACL"@nl ;``
+
+``  dct:description "Service voor het uitvoeren van gevalideerde vragen via sparql"@nl ;``
+
+``  dcat:endpointURL <http://data.example.com/api/shacl> .``
+
+# Bijlage 1: SHACL shape voorbeeld
+
+_Dit is een fragment uit https://jena.apache.org/documentation/shacl/index.html_
+_Zie paragraaf “Integration with Apache Jena Fuseki”._
+
+The service accepts a shapes graph posted as RDF to /ds/shacl with content negotiation.
+
+There is a graph argument, ``?graph=``, that specifies the graph to validate. It is the URI of a named graph, ``default`` for the unnamed, default graph (and this is the assumed value of ``?graph`` if not present), or ``union`` for union of all named graphs in the dataset.
+
+Upload data in file ``fu-data.ttl``:
+
+``curl -XPOST --data-binary @fu-data.ttl    \  ``
+
+``     --header 'Content-type: text/turtle' \  ``
+
+``     'http://localhost:3030/ds?default'``
+
+Validate with shapes in ``fu-shapes.ttl`` and get back a validation report:
+
+``curl -XPOST --data-binary @fu-shapes.ttl  \  ``
+
+``     --header 'Content-type: text/turtle' \  ``
+
+``     'http://localhost:3030/ds/shacl?graph=default'``
\ No newline at end of file