Merge pull request #33 from kadaster-labs/final-release

Final release

.github/workflows/gh-pages.yml

@@ -0,0 +1,22 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # CUSTOM_DOMAIN: optionaldomain.com
+          # CONFIG_FILE: ./mkdocs.yml
+          EXTRA_PACKAGES: build-base
+          # GITHUB_DOMAIN: github.myenterprise.com

README.md

@@ -21,32 +21,14 @@ Check out our research implementations of secured SPARQL endpoints and our testd
 ## Local development
 
 The publication of the documentation is based on [Squidfunk Mkdocs
-Material](https://squidfunk.github.io/mkdocs-material/) and extended with
-[mike](https://github.com/jimporter/mike). This supports versions in the published site. Versions is
-not available @ localhost, but the build structure is the same as the published site :muscle:
+Material](https://squidfunk.github.io/mkdocs-material/).
 
 To develop & serve the docker image on [localhost:8000](http://localhost:8000/):
 
 ```bash
-docker-compose up --build
+docker-compose up
 ```
 
-(omit the `--build` if nothing has changed in the docker infrastructure)
-
-## Publish & Versioning
-
-The documentation of this repo is published on [GitHub Pages](https://pages.github.com/). It is set
-up to support multiple versions of the documentation seperately. It uses
-[mike](https://github.com/jimporter/mike) to do so, following the documetation of mkdocs: [Seting up
-versioning](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/). This means:
-
-- the `main` branch is published under 'version' `dev`
-- every branch starting with `v` is published under the branch name; e.g. branch `v0.90` is
-  published as such
-- there is a workflow available to [set the default
-  version](https://github.com/kadaster-labs/lock-unlock-docs/actions/workflows/set-default.yml) to
-  show; this takes a manual input ( :warning: be sure to enter a matching name)
-
 ## License
 
 Om hergebruik en doorontwikkeling maximaal mogelijk te maken, is dit project gelicenseerd onder

docker-compose.yaml

@@ -1,10 +1,7 @@
 services:
 
   dev-site:
-    image: lock-unlock/mkdocs-material-with-mike
-    build:
-      context: .
-      dockerfile: ./Dockerfile
+    image: squidfunk/mkdocs-material
     # command: server -p 8000
     ports:
       - "8000:8000"

docs/afscherming/afschermingspatronen.md

@@ -6,7 +6,7 @@ Zoals in het vorige hoofdstuk al is gesteld, willen we graag een [federatieve
 bevraging](../federatieve-bevraging/index.md) doen. Dat betekent een query over meerdere silo's en
 dus meerdere endpoints. Zie ook [informatiekundige
 kern](../federatieve-bevraging/informatiekundigekern.md),
-[testopstelling#silos](../federatieve-bevraging/testopstelling.md#silos) en
+[testopstelling#silos](../federatieve-bevraging/testopstelling.md#testdata-genereren-in-silos) en
 [informatiemodel](../federatieve-bevraging/informatiemodel.md). 
 
 Omdat deze databronnen gevoelige informatie bevatten, moet autorisatie op deze gegevenssets worden toegepast. Wie toegang heeft tot informatie (en tot hoeveel informatie) hangt af van de context. Gegevens kunnen bijvoorbeeld niet openbaar beschikbaar zijn op basis van beleid en wetten die verband houden met de bescherming van persoonsgegevens of om commerciële redenen, zoals gevoelige informatie die verband houdt met bedrijfsprocessen. Zelfs binnen deze contexten kunnen bepaalde rollen meer toegang krijgen tot informatie dan andere rollen en alleen voor bepaalde doeleinden.

docs/afscherming/bestaande-implementaties.md

@@ -11,7 +11,7 @@ uitdagingen voor dit project.
 
 Hierbij komen de volgende implementaties aan bod:
 
-- [PoC Topsector Logistiek & iSHARE](#poc-topsector-logistiek--ishare)
+- [PoC Topsector Logistiek & iSHARE](#poc-topsector-logistiek-ishare)
 - [Personal Health Train (FAIR Data Train)](#personal-health-train-pht)
 - [Nuts Bolt voor KIK-V](#nuts-bolt-voor-kik-v)
 - [Solid Project](#solid-project)

docs/afscherming/oplossingsrichtingen.md

@@ -1,32 +1,38 @@
 ---
 title: Oplossingsrichtingen
 ---
-Gegeven de behoefte aan [autorisatie](./autorisatie.md) in een [federatieve bevraging](../index.md) én de
-requirements van [afschermingspatronen](./afschermingspatronen.md) zijn er verschillende
+Gegeven de behoefte aan [autorisatie](./autorisatie.md) in een [federatieve bevraging](../index.md)
+én de requirements van [afschermingspatronen](./afschermingspatronen.md) zijn er verschillende
 technologische oplossingsrichtingen te bedenken.
 
-Verschillende technologische oplossingen bieden verschillende kansen en uitdagingen om de doelen van Lock-Unlock te behalen. De technologische oplossingen zijn eindeloos en toch beperkt in het kader van een federatief datastelsel en Linked Data. In ons desk research zijn we diverse standaarden, voorbeelden en implementaties tegengekomen (zie vorige secties).
+Verschillende technologische oplossingen bieden verschillende kansen en uitdagingen om de doelen van
+Lock-Unlock te behalen. De technologische oplossingen zijn eindeloos en toch beperkt in het kader
+van een federatief datastelsel en Linked Data. In ons desk research zijn we diverse standaarden,
+voorbeelden en implementaties tegengekomen (zie vorige secties).
 
-In het hoofdstuk [federatieve bevraging](../index.md) wordt al het onderscheid en verschillen beschreven
-tussen de verschillende soorten [REST vs GraphQL vs SPARQL](../federatieve-bevraging/apis.md). Tbv afscherming en autorisatie bestaan er voor [REST API's](#rest-api) en [GraphQL API's](#graphql-api) al gestandaardiseerde uitwerkingen. Rondom Linked Data zijn er wel ideeën en concepten maar bestaat [autorisatie als Linked
-Data](#autorisatie-als-linked-data) nog niet echt. Deze kunnen we grofweg verdelen en bundelen in de volgende selectie van technologische oplossing(srichtingen):
+In het hoofdstuk [federatieve bevraging](../index.md) wordt al het onderscheid en verschillen
+beschreven tussen de verschillende soorten [REST vs GraphQL vs
+SPARQL](../federatieve-bevraging/apis.md). Tbv afscherming en autorisatie bestaan er voor [REST
+API's](#autorisatie-in-rest-api) en [GraphQL API's](#autorisatie-in-graphql-api) al
+gestandaardiseerde uitwerkingen. Rondom Linked Data zijn er wel ideeën en concepten maar bestaat
+[autorisatie als Linked Data](#autorisatie-als-linked-data) nog niet echt. Deze kunnen we grofweg
+verdelen en bundelen in de volgende selectie van technologische oplossing(srichtingen):
 
 ## Query Auditing
 
 Gegeven de wens om vrije bevraging (query) tot onze beschikking te houden én te voldoen aan de wens
 tot [auditing](./autorisatie.md#auditing), is het noodzakelijk om vast te leggen welke queries er
 worden gesteld. Dit is vooral van belang in geval van Linked Data en minder in geval van [REST
-API's](#rest-api) en [GraphQL API's](#graphql-api), aangezien deze minder mogelijkheden bieden voor
-vrije bevraging en alle [afschermingspatronen](./afschermingspatronen.md).
+API's](#autorisatie-in-rest-api) en [GraphQL API's](#autorisatie-in-graphql-api), aangezien deze
+minder mogelijkheden bieden voor vrije bevraging en alle
+[afschermingspatronen](./afschermingspatronen.md).
 
 Deze technologische oplossingsrichting is geen oplossing voor autorisatie, maar draagt wel bij aan
 de inzage en controle van toegestane bevragingen. Dit zou een oplossing of implementatie zijn van de
 [GEMMA verwerkingenlogging](bestaande-implementaties.md#gemma-verwerkingenlogging) in het Linked
 Data domein.
 
-| ![Query Auditing](images/query-auditing.png) |
-| :--: |
-| Query Auditing | 
+| ![Query Auditing](images/query-auditing.png) | | :--: | | Query Auditing | 
 
 **Kansen voor Lock-Unlock**
 
@@ -60,15 +66,17 @@ ontsluiting een nieuwe API ontwikkeld. Een samengestelde dataset of meerdere dat
 nieuwe API. Als een andere subset dan in de beschikbare API’s gewenst is, betekent dat de
 ontwikkeling van een nieuwe API.
 
-| ![Authorisation REST API](images/authorisation-rest-api.png) |
-| :--: |
-| Authorisation REST API |
+| ![Authorisation REST API](images/authorisation-rest-api.png) | | :--: | | Authorisation REST API |
 
-**Kansen voor Lock-Unlock**
-Veel data is al dmv een API beschikbaar, waarbij dit al vaak REST API’s betreft. Soms nog voorlopers als SOAP. De techniek is gestandaardiseerd met HTTP (oa OAuth2) en in vele technologie stacks beschikbaar.
+**Kansen voor Lock-Unlock** Veel data is al dmv een API beschikbaar, waarbij dit al vaak REST API’s
+betreft. Soms nog voorlopers als SOAP. De techniek is gestandaardiseerd met HTTP (oa OAuth2) en in
+vele technologie stacks beschikbaar.
 
-**Uitdagingen voor Lock-Unlock**
-Afscherming van data is op het niveau van de REST API. Autorisaties geven toegang of niet. Het is aan of uit, ja of nee. Er zijn geen gradaties van autorisaties mogelijk. Er zijn geen mogelijkheden om andere datasets of subsets op te vragen dan dat er in de API’s (collectie) wordt aangeboden. Er is orkestratie noodzakelijk om meerdere datasets over meerdere API’s te bevragen. Navigeren en vrij bevragen is niet mogelijk.
+**Uitdagingen voor Lock-Unlock** Afscherming van data is op het niveau van de REST API. Autorisaties
+geven toegang of niet. Het is aan of uit, ja of nee. Er zijn geen gradaties van autorisaties
+mogelijk. Er zijn geen mogelijkheden om andere datasets of subsets op te vragen dan dat er in de
+API’s (collectie) wordt aangeboden. Er is orkestratie noodzakelijk om meerdere datasets over
+meerdere API’s te bevragen. Navigeren en vrij bevragen is niet mogelijk.
 
 | Requirement        | Support                            |
 | ------------------ | ---------------------------------- |
@@ -79,21 +87,33 @@ Afscherming van data is op het niveau van de REST API. Autorisaties geven toegan
 
 ## Autorisatie in GraphQL API
 
-GraphQL is gebaseerd op een voor-gedefinieerd schema (zie voorbeeld). Dit schema is een object georiënteerde benadering waarin objecten en de relaties beschreven zijn. Welke objecten beschikbaar zijn, welke relaties en in welke richting die relaties mogelijk zijn, staat gedefinieerd in het schema. Dit geeft mogelijkheden voor het afschermen van data. Er kunnen filters toegepast worden, zowel als gebruiker en in de API. Bijvoorbeeld: _geef alle KVKInschrijvingen met rechtsvorm "BV"_. Of in het voorbeeld hiernaast: _vanuit KVKInschrijving kan wel het adres opgevraagd worden maar niet andersom_.
+GraphQL is gebaseerd op een voor-gedefinieerd schema (zie voorbeeld). Dit schema is een object
+georiënteerde benadering waarin objecten en de relaties beschreven zijn. Welke objecten beschikbaar
+zijn, welke relaties en in welke richting die relaties mogelijk zijn, staat gedefinieerd in het
+schema. Dit geeft mogelijkheden voor het afschermen van data. Er kunnen filters toegepast worden,
+zowel als gebruiker en in de API. Bijvoorbeeld: _geef alle KVKInschrijvingen met rechtsvorm "BV"_.
+Of in het voorbeeld hiernaast: _vanuit KVKInschrijving kan wel het adres opgevraagd worden maar niet
+andersom_.
 
 ![GraphQL KVK Inschrijving voorbeeld](images/graphql-kvk-inschrijving-voorbeeld.png)
 
-Met een GraphQL Gateway is het mogelijk om meerdere samenhangende datasets tegelijkertijd te bevragen. De Gateway distribueert de query en stelt de resultaten samen tot een samenhangend geheel (schema stitching).
+Met een GraphQL Gateway is het mogelijk om meerdere samenhangende datasets tegelijkertijd te
+bevragen. De Gateway distribueert de query en stelt de resultaten samen tot een samenhangend geheel
+(schema stitching).
 
 ![GraphQL API](images/graphql-api.png)
 
-Er zijn verschillende manieren om de objecten in het schema te beveiligen. Net zoals met REST API’s kan wel of geen toegang verleent worden tot de hele API. Met GraphQL is het ook mogelijk om in het schema te configureren welke rollen toegang krijgen tot objecten of attributen daarvan. Waar in REST API’s meerdere API’s beschikbaar gemaakt zouden worden, kan dat met GraphQL in één GraphQL API/Gateway, uiteraard beperkt tot het betreffende schema.
+Er zijn verschillende manieren om de objecten in het schema te beveiligen. Net zoals met REST API’s
+kan wel of geen toegang verleent worden tot de hele API. Met GraphQL is het ook mogelijk om in het
+schema te configureren welke rollen toegang krijgen tot objecten of attributen daarvan. Waar in REST
+API’s meerdere API’s beschikbaar gemaakt zouden worden, kan dat met GraphQL in één GraphQL
+API/Gateway, uiteraard beperkt tot het betreffende schema.
 
-**Kansen voor Lock-Unlock**
-Verfijnde autorisatie op schema niveau mogelijk. Binnen het schema zijn (vrije) queries mogelijk. Gateways ondersteunen federatieve queries.
+**Kansen voor Lock-Unlock** Verfijnde autorisatie op schema niveau mogelijk. Binnen het schema zijn
+(vrije) queries mogelijk. Gateways ondersteunen federatieve queries.
 
-**Uitdagingen voor Lock-Unlock**
-GraphQL kan aangeboden worden op basis van een Linked Data architectuur, maar volgt niet volledig de Linked Data principes.
+**Uitdagingen voor Lock-Unlock** GraphQL kan aangeboden worden op basis van een Linked Data
+architectuur, maar volgt niet volledig de Linked Data principes.
 
 | Requirement        | Support                            |
 | ------------------ | ---------------------------------- |
@@ -120,7 +140,10 @@ Predefined Queries zijn een eenvoudige manier om afscherming mogelijk te maken 
 
 **Uitdagingen voor Lock-Unlock**
 
-Er is geen standaard voor het vastleggen Predefined Queries. Dit is daarom afhankelijk van de technische oplossing of dit beschikbaar is of niet. Deze oplossing levert nauwelijks meer dan de mogelijkheden bij REST API’s. Het is namelijk voor de gebruiker niet meer mogelijk om zelf queries op te stellen en te navigeren door de knowledge graph voor gesloten data.
+Er is geen standaard voor het vastleggen Predefined Queries. Dit is daarom afhankelijk van de
+technische oplossing of dit beschikbaar is of niet. Deze oplossing levert nauwelijks meer dan de
+mogelijkheden bij REST API’s. Het is namelijk voor de gebruiker niet meer mogelijk om zelf queries
+op te stellen en te navigeren door de knowledge graph voor gesloten data.
 
 | Requirement        | Support                            |
 | ------------------ | ---------------------------------- |

docs/autorisatie-als-linkeddata/implementaties/index.md

@@ -38,5 +38,5 @@ toegepast, zijn wel verschillende strategieën:
   gegenereerd van de data waartoe de gebruiker toegang heeft. Vervolgens wordt de originele query op
   deze subset uitgevoerd (ipv uitvoering op alle gegevens). 
 
-Een samenvatting van de sterke en zwakke punten van beide concepten staat in [evaluatie van de twee
-implementaties](../evaluatie.md#vergelijking-implementaties).
+Hoewel een uitgebreide vergelijking tussen beide implementaties niet gelukt is, hebben we wel een
+korte [evaluatie](../evaluatie.md) gedaan.