Slimme opmaak

Dit document is kladversie 0.1

Linked Data, en dus het gebruik van URI’s, zorgt voor een betere uitwisselbaarheid van gegevens. HTTP URI’s zorgen er immers voor dat voor iedere identificator, er een definitie kan worden opgevraagd. Dit kan vaak heel erg moeilijk te implementeren lijken, zeker als er nog geen basislijsten online staan. Vaak heeft een dienst of gemeentewebsite echter al informatie-pagina’s over diverse zaken. Deze website annoteren met de URI’s door middel van “slimme opmaak” kan een snelle en goedkope manier zijn om te voldoen aan de Linked Data principes. Op deze pagina gaan we eerst dieper in op waarom dit een goed idee is: zoek-machines creëren vandaag ook al sowieso “scrapers” voor uw gegevens en met slimme opmaak laat je iedereen toe je data op je website sneller te hergebruiken. Dan gaan we in op hoe we de technische principes toepassen op een HTML-pagina. Als laatste puntje tonen we ook aan de hand van een code-voorbeeld hoe je direct aan de slag kan met informatie op dergelijke websites.

Websites scrapen

Het scrapen van website had oorspronkelijk een slechte naam. Programmeurs zouden doen alsof ze een pagina handmatig bezochten, en de gegevens van een pagina via een pagina machinaal van een pagina plukken. Er zijn wenselijke gevolgen van web-scraping, zoals een zoekmachine die jouw website op deze manier doorzoekbaar maakt, maar ook minder wenselijke gevolgen, zoals voor websites die afhangen van vooral menselijke bezoekers. Zeker is in ieder geval dat web-scraping nog vandaag voor heel wat controverse zorgt in zelf het publieke debat, van nieuws-sites die zoek-machines aanklagen voor onrechtmatig gebruik van nieuws-overzichten tot het hergebruik van publieke gegevens rond het openbaar vervoer. In sommige gevallen is er inderdaad sprake van een intellectuele eigendomsbreuk, of zelfs tot het onrechtmatig overbelasten van een web-service, in andere gevallen gaat het om het hergebruik van gegevens in het publieke domein waarbij geen noemenswaardige extra load op de servers wordt geplaatst.

Los van de controverse houden programmeurs wel van web-scraping. Ze zijn immers zeker dat ze op officiële gegevens werken, want achter een website zit een team van content-creatoren dat moet zorgen dat mensen juist geïnformeerd worden. Als er een tweede kanaal wordt opgericht, bijvoorbeeld een “open-data-API” (zoals bij het Vlaams Parlement) of een data-dump (bijvoorbeeld zoals bij het KBO), dan is er een zekere argwaan bij een hergebruiker: “Zullen de gegevens wel up to date blijven? Zal deze bron evenlang online blijven als de website, of zou het kunnen dat deze offline wordt gehaald door besparingen bij de volgende legislatuur? Gebruikt de organisatie zijn eigen Open Data wel?”. De authentieke bron is echter vaak de website.

Vandaag is scrapen vooral een ingeburgerde zaak bij zoekmachines en social-media-toepassingen. Bijvoorbeeld, als iemand een link naar deze website op een sociaal netwerk plaatst, zal dat sociaal netwerk de website scrapen om al een samenvatting en een image te tonen aan de hergebruiker. Maar ook bij zoekmachines kan je vandaag al snelle overzichten vinden in de kantlijn als je bijvoorbeeld de openingsuren en contactgegevens zoekt van een overheidsdienst. Ook dit wordt veelal gescrapet van een overheidswebsite.

We gaan dat duidelijk maken, en ook direct de zaken automatisch scrapebaar maken met 2 technieken die gerust gemengd mogen worden: JSON-LD-snippets en RDFa. Deze technieken worden vandaag ook al gebruikt in het Lokale Besluiten als Linked Open Data project. Ze worden gezien als een goedkope, snelle, en developer-vriendelijke manier om data die al online staat open en machine-leesbaar herbruikbaar te maken. Voor echte snelle interactie met een app zijn deze interfaces wat traag (gezien de hele HTML-pagina moet gescrapet worden per aanvraag), en wordt verondersteld dat een programmeur eerst alle gegevens lokaal repliceert. Zo kunnen er wel gespecialiseerde databanken worden gebouwd zoals een overzicht en toegankelijkheid van overheidsgebouwen, openingsuren, publieke diensten, gemeenteraadsbesluiten, enzovoort, zonder dat daar eerst een Vlaamse databank moet worden voor opgericht.

Uw website als Open Data

Een algemeen overzicht van de technische principes vind je op https://smart.flanders.be/resources. Dit hoofdstuk is een toepassing van de technische principes op HTML-pagina’s.

Een licentie toevoegen (juridisch)
Gezien de controverse die nog steeds bestaat omtrent web-scraping is het nodig dat bij het publiceren van gegevens als Open Data in HTML, er duidelijk een indicatie is dat dit wordt toegestaan. Daarom geven we aan dat de huidige pagina, beschikbaar op de url, een licentie bevat. We hebben de keuze tussen twee open-data-licenties: de CC-0 verklaring en de Modellicentie Gratis Hergebruik.

In RDF-vorm, moet er een triple aanwezig zijn (dit wordt in het volgend hoofdstuk beter geïllustreerd) van de volgende vorm:

<{URL van huidige pagina}> <http://purl.org/dc/terms/license> <http://data.vlaanderen.be/id/licentie/creative-commons-zero-verklaring/v1.0>
Toegang tot de gegevens (technisch)

Als een website scrape-vriendelijker wordt gemaakt, wordt vaak gevreesd dat menselijke gebruikers een webpagina niet meer kunnen bezoeken omdat machinale activiteiten alles overbelasten. Dit hoeft niet zo te zijn als ook de goede caching wordt ingesteld op de server-documenten. Dit is meestal reeds in voege op overheidswebsites. Indien niet raden we de uitleg over caching aan op de website van Mozilla door te geven aan uw website-bouwer en met deze persoon te overleggen.

Om Web-toepassingen op andere domeinen ook toegang te geven tot deze publieke gegevens op jouw website, moet een header worden toegevoegd die dit toelaat. Dit heet de Cross Origin Resource Sharing (CORS) header. We raden ook hier weer aan om ten rade te gaan bij uw website bouwer. Meer informatie is te vinden op http://enable-cors.org.

Gestandardiseerd triples vinden in HTML (syntactisch)

Er zijn 2 standaarden om triples te steken in uw pagina: RDFa en JSON-LD-snippets. RDFa breidt HTML uit met tags die aangeven hoe een serializer dit kan parsen. Voor code-voorbeelden en een “playground” verwijzen we naar RDFa Play.

De tweede manier maakt gebruik van een code snippet, net zoals javascript wordt ingevoegd in een pagina. Daarvoor steek je een JSON-LD-fragment in deze tags: <script type="application/ld+json">{"@context": "...", "@graph": "..."}</script> Voor code-voorbeelden en een “playground” verwijzen we naar de website van JSON-LD, alsook de broncode van deze web-pagina (rechtmuisknop - view source). Ook de website van Google bevat mooie voorbeelden. Daar helpt een rich snippet validator om jouw rich snippet zo op te bouwen dat de zoekmachine er het beste kan uithalen.

Een domeinmodel kiezen (semantisch)

Een exhaustieve lijst maken van alle URI’s die je mogelijks kan gebruiken om de zaken op jouw pagina te beschrijven is onmogelijk. Wel geven we een lijst mee van vocabularia waarvan wij denken dat ze direct nuttig kunnen zijn. Een goeie snippet en slimme mark-up gebruikt een mengeling en vermeldt sommige zaken (zoals titel) meerdere keren met verschillende vocabularia.

  • Schema.org: Geliefkoosd door zoekmachines. Een heel simpel vocabularium dat het mogelijk maakt om zaken rudimentair te beschrijven. Let wel: de zoekmachine van bvb. Google toont slechts een deeltje hiervan in de zoekresultaten.
  • Open Graph: Geliefkoosd door social-media-netwerken. Zorgt voor mooie voorbeelden als je een URL op social media plaatst.
  • Dublin Core Terms: Geliefkoosd door archieven. Geeft een lijst van de meest fundamentele metadatavelden.
  • OSLO²: De vocabularia van de Vlaamse Overheid, gestandardiseerd door een stuurorgaan. Hiermee kan je zaken zoals gemeenteraadsbesluiten, diensten, mandaten, gebouwen, enzovoort bespreken.
  • Linked Open Vocabularies (LOV): “All you need is LOV” als je op zoek bent naar nog andere vocabularia als uw specifieke use case niet onder de eerste 4 viel.

Andere URI’s hergebruiken (semantisch)

Niet alleen domeinmodellen moeten worden hergebruikt, ook linken naar andere entiteiten. Zo kan je je bijvoorbeeld inbeelden dat een bepaalde dienst zal worden geannoteerd met een adres. Dit adres heeft een unieke identificator, en dus ook een URI, gekregen in het adressenbestand van Informatie Vlaanderen. Deze URI hergebruiken is een must. Je kan zelf deze URI’s ontdekken in de webservices van de datasets van de Vlaamse Overheid. Zie http://data.vlaanderen.be/#Datasets.

Niet aleen Vlaamse ID’s kunnen worden hergebruikt. Nog een populaire dataset om mee te linken is het Wikidata project. Als je wilt linken naar bijvoorbeeld het concept “De Aarde”, kan je nu ook onambigu de URI http://www.wikidata.org/entity/Q2 gebruiken. Deze URI’s kan je zelf ontdekken op diverse manieren: handmating via de zoekinterface op de homepagina van wikidata, of via een van hun web-services of data-dumps.

Cruciaal is dat je uiteraard ook voor eigen entiteiten linken legt. Zo kan bijvoorbeeld iets door jou beschreven op het openbaar domein, beheerd worden door een organisatie die ook beschreven staat op een andere URI. Dan kan je de link leggen tussen deze twee zaken met het OSLO²-predicaat http://data.vlaanderen.be/ns/openbaardomein#beheerder.

Vindbaar maken van uw pagina’s

Een machine vindt uw pagina na het volgen van enkele links uit een andere dataset zoals een dataportaal, of via links volgen vanaf een andere pagina binnen je website. Om uw dataset goed vindbaar te maken, kan je deze toevoegen aan het dataportaal van uw stad, of op het opendataportaal van de Vlaamse Overheid. Indien dit niet van toepassing is, kan je ook Dublin Core metadata-velden toevoegen in uw pagina, zoals title, creator, modified, etc.

Om binnen de website zelf beter vindbaar te maken, kan je nu ook de server-functionaliteit die je aanbiedt aan mensen (zoals een zoek-functie, een overzicht of een filter), vindbaar maken via het Hydra-vocabularium. In Vlaanderen wordt dit op dit moment nog gestandaardiseerd door de werkgroep “Generieke Hypermedia API” binnen data-standaarden van het Stuurorgaan van de Vlaamse Overheid.

Lijst van 7 checks

  • Er wordt een licentie in RDFa of de JSON-LD snippet toegevoegd via het predicaat dct:license.
  • Er zit een goede caching-strategie op de website (bvb. via ETag of cache-control).
  • Er staat een CORS-header geconfigureerd.
  • Je gebruikt veel-voorkomende vocabularia.
  • Als je zaken zoals een adres vermeldt, of andere identificatoren van andere pagina’s gebruikt, zorg je dat deze via URI’s gelinkt zijn.
  • Je dataset en pagina is vindbaar via andere pagina’s.
  • Je pagina bevat ook in RDF de metadata die het CMS aanbiedt (creator, title, modified, ...).

Als je aan deze checklist voldoet, zal je je pagina kunnen valideren in de Smart Flanders validator (binnenkort beschikbaar).

Voorbeelden

Ter illustratie pasten we deze checklist toe op een kopie van enkele pagina’s:

  • De pagina waar we nu opzitten bevat een machine-leesbare lijst van toepasbare licenties.
  • (meer komt)
Deze kunnen allen in dit code-fragment bekeken worden:

See the Pen RDFa / Rich Snippets demo by Pieter Colpaert (@pietercolpaert) on CodePen.