Exercise on hypermedia APIs and SHACL

1. www.vlaanderen.be/informatievlaanderen
OSLO Code Challenge

2. wifi-netwerk “VO Events"
wachtwoord: vla%nderen
OSLO Opleidingsdag - Track Business Verantwoordelijke 2

3. > Eerste sessie: 10u45 – 12:15
 Introductie OSLO Technische Principes
 Toelichting bij Code Challenge
 Start met bouwen van webapplicatie
> Tweede sessie: 13u15 – 15:45
 Verder bouwen aan webapplicatie
 Kennisdeling
Overzicht
3

4. Het Semantisch Web en Linked Data
OSLO Technische Principes

5. Het Web evolueert van een “Web of linked
documents” naar een “Web of linked data”...
5

6. 1. Semantiek inbedden in data formaten
2. Data validatie op basis van semantische modellen
3. Hypermedia controls in web services om API’s
zelfbeschrijvend te maken
Hoe kunnen we data en service integratie
kosten verlagen?
6

7. PIM  PSM  Code
7
OO
diagram
DDL
diagram
XSD
diagram
RDF
SHACL
SQL Server
Oracle
C#
JAVA
XSD
UML
class
diagram
RDF
diagram

8. Het Web als blauwdruk
8
Persistente
identificat
-oren:
URI’s
Links naar
andere
informatie
Dereference
able HTTP
URI’s
Standardise
d
information
(RDF)

9. Het Web als blauwdruk
9
Persistente
identificat
-oren:
URI’s
Links naar
andere
informatie
Dereference
able HTTP
URI’s
Standardise
d
information
(RDF)
https://data.vlaanderen.be/id/adres/3706808
Koningin Maria Hendrikaplein 70,
9000 Gent

10. Het Web als blauwdruk
10
Persistente
identificat
-oren:
URI’s
Links naar
andere
informatie
Dereference
able HTTP
URI’s
Standardise
d
information
(RDF)
https://data.vlaanderen.be/id/adres/3706808
Machine
vriendel
ijkMens
leesbaa
r

11. Het Web als blauwdruk
11
Persistente
identificat
-oren:
URI’s
Links naar
andere
informatie
Dereference
able HTTP
URI’s
Standardise
d
information
(RDF)
https://data.vlaanderen.be/id/organisatie/OVO002949
http://www.w3.org/2004/02/skos/core#prefLabel
agentschap Informatie Vlaanderen
subject
predicate
object

12. Het Web als blauwdruk
12
Persistente
identificat
-oren:
URI’s
Links naar
andere
informatie
Dereference
able HTTP
URI’s
Standardise
d
information
(RDF)
https://data.vlaanderen.be/id/organisatie/OVO002949
http://schema.org/contactPoint
https://data.vlaanderen.be/id/contact/1c279a9e
subject
predicate
object

13. Informatie voorgesteld als een graaf
13

14. Semantische interoperabiliteit
15 vocabularia en applicatieprofielen
14
https://data.vlaanderen.be/ns/

15. > JSON Linked Data (JSON-LD)
 Een eenvoudig Linked Data formaat, gebaseerd op het al
succesvolle JSON
 Machine interpreteerbare data door link naar semantiek
 100% compatibel met JSON en makkelijk te “retrofitten”
× Geen formele gestandaardiseerde methode voor
gegevensvalidatie
× Data is machine leesbaar, de methodes en operaties niet
Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
15

16. Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
16
> Upgrade van bestaande services m.b.v. JSON-LD parsing

17. Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
17
> Gedeelde context voor nieuwe services

18. Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
18
> Uitbreidingen op basis van andere RDF vocabularia

19. > SHACL voor gegevensvalidatie
 Shapes Constraint Language
 W3C Recommendation sinds 20 juli 2017
 Een standaard voor het valideren van RDF data tegen een set
van restricties (kardinaliteiten, codelijsten,…)
 SHACL files beschikbaar voor alle OSLO Applicatieprofielen
× API’s ontsluiten vaak slechts een subset van de data per
methode
× API’s combineren vaak data overheen verschillende domeinen
Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
19

20. > Voorbeeld van een SHACL file
Syntactische interoperabiliteit
Implementaties met JSON-LD en SHACL
20
Voor het beschrijven van een organisatie
Wordt een attr. “voorkeursNaam” gespecifieerd
Met als datatype een “string”
Dat minstents 1 keer voorkomt
En werd gedefinieerd door: skos:prefLabel

21. Hypermedia controls in web services
Voorbeeld: een parkeerplaats vinden in Vlaanderen
21
> Javascript code example at
https://smart.flanders.be/piloten/parkeren
1. Retrieve data catalog
2. Javascript filters parking
dataset
3. Populate dropdown
4. Select parking site in city
5. Show real-time and historic

22. > Hypermedia Controls toevoegen
aan API responses op een
gestandaardiseerde manier.
> Van toepassing op RESTful API’s
> Twee mogelijke implementaties
 Semantisch, als onderdeel van
de response payload
(aanbevolen)
 Op HTTP niveau via Link Headers
in de response
Scope van de OSLO Hypermedia specificatie
22

23. Toelichting bij ‘Code Challenge’

24. > Trade-offs afwegen tussen client en server
> Innovatieve herverdelingen zoeken mbv hypermedia
 dynamische interactie tussen client en server
Linked Data Fragments
24

25. Comunica
25
> Gloednieuw modulair framework om het Web te query’en
> Makkelijk testen van verschillende LDF interfaces
> Toekomst: hypermedia bouwblokken VO automatisch
interpreteren
> Nu: zelf generieke client schrijven
http://comunica.linkeddatafragments.org/

26. Voorbeeld 1: paginering
26
{ first: 'http://my-api/organizations?page=0',
next: 'http://my-api/organizations?page=1',
last: null,
prev: null }

27. function getCRUDControls(url) {
return new Promise(resolve => {
const crud = new window.ghaclient.CRUDHandler({
crudCallback: (crud) => resolve(crud);
});
client.fetch(url, [crud]);
});
}
Voorbeeld 2: CRUD
27
[ { method: 'GET' },
{ expects:
'https://data.vlaanderen.be/shacl/organisatie-basis#OrganisatieShape',
method: 'PUT' } ]

28. > Momenteel geen eenduidige manier
 Lokale datadump, SPARQL-endpoint...
> Hoe doen jullie dit?
Linked Data consumeren (1/2)
28

29. Linked Data consumeren (2/2)
29
Linked Data Documents
SPARQL-endpoint
Triples
Gefilterde triples
SPARQL
Verwachte JSON
JSON-LD framing
GRAPHQL-LD
JSON-LD framing
Fetch, LDFetch

30. > Ophalen van triples ongeacht het formaat
> Let response = await ldfetch.get(url);
-> response.triples
> let frame = {
"@id": “https://data.vlaanderen.be/id/organisatie/OVO025815”
};
Let organisatie = await ldf.frame(response.triples, frame)
LDFetch
30

31. Te gebruiken API
31
> Startpunt: https://lodi.ilabt.imec.be/oslo-api/organizations
> Bevat hypermedia controls paginering en CRUD
 Pagina van organisaties (hydra:PartialCollectionView)
 Link naar CRUD document met meer info (foaf:primaryTopic)
> CRUD document bevat verwijzing naar OSLO shape:
https://data.vlaanderen.be/shacl/organisatie-basis#OrganisatieShape

32. > Gebruiker ziet een lijst van objecten
 Bijvoorbeeld: organisaties
> Wanneer de gebruiker klikt op een object opent een invulformulier
> De gegevens die ingevuld kunnen worden, zijn OSLO-compliant
 Gebruik de SHACL shape om dynamisch het formulier op te bouwen
met ‘simpele’ datatypes
Invulformulier OSLO
32

33. Overzichtpagina
33
https://codepen.io/brechtvdv/pen/VEzPza

34. Invulformulier
34

35. > Maak een fork van:
https://codepen.io/brechtvdv/pen/bmagPW
> Of werk lokaal in 1 bestand:
https://gist.github.com/brechtvdv/9ca07d730e72a8ba85cc2e632d38a616
Codepen
35