- Editors:
- Laurens De Vocht, Ghent University - iMinds, laurens.devocht@ugent.be
- Raf Buyle, V-ICT-OR, raf.buyle@v-ict-or.be
- Katrien De Smet, Corve, katrien.desmet@bz.vlaanderen.be
- Johan Vander Waal, V-ICT-OR, johan.vanderwaal@v-ict-or.be
Other Contributors: Ziggy Van Lishout, AGIV, Siegfried.Vanlishout@agiv.be; Joerie Robbrecht, AGIV, Joeri.Robbrecht@agiv.be
Abstract
Status of This Document
This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.
Table of Contents
- 1. Inleiding
- 2. URI Strategie
- 3. Resources
- 4. Lijsten
- 5. Operaties op Resources
- 6. Operaties op Lijsten
- 7. Identificatie en Logging
- A. Acknowledgements
Released under the ISA Open Metadata v1.1 license.
Please note that remainder of this specification is written in Dutch.
1. Inleiding
Dit document focust op niet-technische overwegingen om een eenduidige beschrijving te definiëren voor services van lokale overheden, die gebruik maken van de OSLO standaard: in het bijzonder, het ruimere kader van een gedeelde productencatalogus en het uitwisselen van contactinformatie.
Het doel van de hier beschreven services is om de verscheidenheid in services die het zelfde doel beogen te minimaliseren.
In het kader van het EWI Open Data project rond contactinformatie is een voorbeeld-implementatie uitgewerkt. Deze wordt hier toegelicht om een duidelijk beeld te geven van hoe een dergelijke service kan geimplementeerd worden in de praktijk.
Data op een vlotte en efficiënte manier kan door gebruik te maken van standaarden. Het project gedeelde dienstencatalogus voor publieke dienstverlening is een gedistribueerde catalogus waarbij informatie uit verschillende lokale authentieke bronnen en centrale bronnen gecombineerd kan worden om de burger, ondernemer en vereniging correcte en begrijpbare informatie te leveren. Deze databronnen bevatten zowel gestructureerde beschrijvingen van de publieke dienstverlening als contactinformatie. Om de informatie uit deze bronnen te kunnen uitwisselen wordt gebruik gemaakt van de OSLO-standaard.
De gedeelde catalogus voor publieke dienstverlening:
- is een nieuwe open data bron voor contactinformatie en dienstverlening van de overheid waarvan iedereen gebruik kan maken
- laat burgers en ambtenaren toe om snel doorheen het up-to-date aanbod van verschillende overheden te kunnen zoeken
- kent een optimale gegevensdeling dankzij Open Standaarden #OSLO
- maakt het mogelijk dat via een ‘terugkoppelingskanaal’ gebruikers fouten en afwijkingen kunnen melden
De voorliggende Richtlijnen voor Services beschrijven op het technische vlak de wijze waarop deze data ontsloten of uit gewisseld kunnen worden. De beschreven specificaties zijn beproefd en maken het mogelijk voor lokale besturen en hun dienstenleveranciers om services te implementeren in eigen toepassingen. Bij het uitwerken van de service wordt geen voorkeur voor het type webservice naar voren geschoven. Het is zowel mogelijk om uit te wisselen met een restfull webservice als met een Soap webservice.
Op basis van de beschreven services rondom contactinformatie is het mogelijk geworden om ook voor andere services vanuit OSLO op basis van deze richtlijnen te gaan werken. Hierdoor ontstaat een eenduidige ontsluiting van persoons-, organisatie-, adres gegevens zoals OSLO dit beoogd.
2. URI Strategie
De belangrijkste motivatie om te kiezen voor een URI-strategie is dat toepassingen en catalogi op een eenduidige manier kunnen verwijzen naar services die bestaan bij de verschillende overheden en gebruikers. Dit zal het hergebruik van de services maximaliseren en de impact bij wijzigingen voor implementaties minimaliseren. Dat kan aangezien alle dergelijke services op dezelfde manier hun resources toegankelijk maken.
Het basispatroon dat deze strategie vervult is (in lijn met http://www.opendataforum.info/Docs/URI_strategie_versie2):
http://{domein}/{type}/{concept}/{referentie}
2.1 Domein
Het domein bestaat uit het internet-domein en een pad. Het is best zo dat het domein van de URI een referentie bevat naar de bron waar het vandaan komt.
Om het domein herkenbaar te houden voor ontwikkelaars en gebruikers, is het belangrijk om een generiek domein te voorzien in het belang van verschillende diensten die gecentraliseerd zijn rond een bepaald domein of sector.
Bvb. {service}.data.localgov.be/ of data.localgov.be/{service}/ maar dit kan eventueel uitgebreid worden naar {eigendomein}/{eigenpad}/{service} of {service}.{eigendomein}/{eigenpad}.
2.2 Type
Het type duidt op het soort service waarop aanspraak gemaakt wordt en dit heeft impact op hoe de referentie kan gebruikt worden.
Er zijn 2 types die minimaal dienen ondersteund te worden:
- id: de referentie verwijst naar een concrete instantie van het concept
- lijst: een referentie is niet nodig, de lijst van concepten of van types concepten (indien geen concept wordt opgegeven) in het domein wordt weergegeven.
Op een lijst kunnen geavanceerdere operaties uitgevoerd worden zoals een custom filter dat kan toegepast worden een bepaald type concept of op het gehele domein of zoeken op tekstwaarde van een bepaald veld in het domein (al dan niet beperkt binnen een bepaald concept). Deze actie wordt meegegeven in de request (bvb. via de url parameters).
Daarnaast zijn er ook nog andere types mogelijk zoals een concretisatie van id (rijksregisternummer “rrk” of ondernemingsnummer “kbo”.
2.3 Concept
Het type duidt aan wat voor soort identiteit het gaat waarnaar verwezen wordt met de identifier. In het bijzonder zijn hier de geldige concepten (met Nederlandstalige terminologie):
-
Basisconcepten
- persoon en persoonsrelatie
- organisatie en organisatierelatie
- hoedanigheid
- contactinformatie
- locatie (omvat ook verblijfsobjecten)
- adres
- dienstverlening
- product
-
Uitgebreide concepten
- kanaal
- beleidsveld
- bezigheid
- openingsuren
2.4 Architectuur
We passen de URI-strategie toe op contactinformatie van lokale besturen die uitgewisseld wordt beschreven volgens OSLO. In de voorbeelden kiezen we voor een RDF serialisatie en maken we gebruik van The Datatank als publicatie platform voor de services. Er gewerkt met twee basistypes: product en organisatie. De producten komen uit de IPDC en de organisaties uit de VKBO.
Het domein waarop de services gepubliceerd worden is
In de voorbeelden komt dit domein vaak terug. Op dit domein worden de services ondersteunt door The Datatank. The Datatank maakt gebruik van de RDF serialisatie van OSLO resources. Andere implementaties zijn uiteraard ook mogelijk.
In RDF gebeuren al de queries typisch aan de hand van SPARQL., Quasi alle services zullen gebruik maken van SPARQL queries (Virtuoso, ARC, Jena Fuseki e.d.) om de data aan te spreken en via de service te ontsluiten aan de gebruikers.
EasyRDF is een bibliotheek om RDF te consumeren en te produceren. Het dient als controller in de voorbeeldimplementatie van de architectuur. De controller verwerkt en reageert op events, die meestal het gevolg zijn van handelingen van de gebruiker of een software agent en dient als koppeling tussen de representatie in de service en het interne datamodel.
Fig. 1 image
Het interne datamodel kan er volledig anders uitzien als de OSLO representatie voor de gebruikers of software agents.
Fig. 2 image2
Indien er gewerkt wordt met OSLO-XML dan zal elke request verpakt worden in een SOAP envelop die beschreven wordt in de WSDL verbonden met de URI. Het onderliggende model is daar typisch een relationeel datamodel en de vertaling zal in bijna alle gevallen gebeuren naar SQL queries (Microsoft, Oracle, MySQL, PostgreSQL e.d.).
Locaties worden uitgewisseld via de OSLO RDF aan de hand van een referentie naar het bestand met de beschrijving (GML, KML, WKT of andere).
RDF
<http://example.com/id/id/organization/28> a <http://purl.org</oslo/ns/localgov#Organization> ;
oslo:authenticLocation <http://example.com/id/location/201> .
<http://example.com/id/id/location/201> locn:geometry <http://example.com/id/geometry/> .
XML
<oorg:organization>
<ovc:identifier>
<cvb:Identifier>28</cvb:Identifier>
</ovc:identifier>
<oorg:authenticLocation>
<ovc:identifier>
<cvb:Identifier>201</cvb:Identifier>
</ovc:identifier>
<cva:Geometry>
<!-- geometry description blob -->
</cva:Geomtery>
</oorg:authenticLocation>
</organization>
Geometrie
Het kenmerk cva:geometry kan elk type van geografische informatie bevatten. De inhoudelijke validatie van dit veld valt buiten de specificatie van OSLO. Hieronder een aantal typevoorbeelden.
Afhankelijk van de encoding van de geometrie, kunnen volgende types gebruikt worden Een string (WKT, GML, KML) Een klasse (OGC’s - GeoSPARQL, GEOJSON specification)
We adviseren om onderstaande te gebruiken:
-
Geometrie
- WKT
- GML
- RDF+WKT/GML
- GeoSPARQL and/or GEOJSON specification
-
Punten
- RDF W3C Basic Geo (WGS84 lat/long)
- Of bovenstaande (geometrie)
RDF+WKT (GeoSPARQL)
:Resource locn:geometry
[ a ogc:Point; ogc:asWKT "<http://www.opengis.net/def/crs/OGC/1.3/CRS84> Point(-0.001475 51.477811)"^^ogc:WKTLiteral ] .
RDF+GML (GeoSPARQL)
:Resource locn:geometry
[ a ogc:Point; ogc:asGML
"<gml:Point srsName='http://www.opengis.net/def/crs/OGC/1.3/CRS84'>
<gml:coordinates>-0.001475, 51.477811</gml:coordinates></gml:Point>"^^ogc:GMLLiteral ] .
RDF (WGS84 lat/long)
:Resource locn:geometry [ a geo:Point; geo:lat "51.477811"; geo:long "-0.001475" ] .
RDF (schema.org)
:Resource locn:geometry [ a schema:GeoCoordinates; schema:latitude "51.477811"; schema:longitude "-0.001475" ]
3. Resources
Om all attributen en relaties van een specifiek concept te krijgen, gekenmerkt aan de hand van zijn identifier gebruiken we volgende uri:
http://{domein}/id/{concept}/{referentie}
Het resultaat van deze vraag is een document beschreven volgens OSLO (RDF of OSLO-XML) dat de beoogde instantie van het concept beschrijft, of derefereert.
Voorbeeld:
Het bevragen van een resource, een ‘READ’ operatie, vertaalt zich bij een REST Service naar een GET request.
http://example.com/id/organisatie
In de praktijk zal het type ‘id’ vaak expliciet benoemd worden indien het bekend is bijvoorbeeld voor het KBO nummer dat gebruikt wordt als identifier:
http://example.com/kbo/organisatie
Vraag
Type:
GET
URL Parameters:
id : 28
Antwoord
RDF
@prefix skos: <http://www.w3.org/2004/02/skos/core#>
@prefix regorg: <http://www.w3.org/ns/regorg#>
<http://example.com/id/Organization/28> a <http://purl.org/oslo/ns/localgov#Organization> ;
skos:notation "28" ;
regorg:legalName "V-ICT-OR"
XML
<!-- wrapped in XML response body -->
<oorg:organization>
<ovc:identifier>
<cvb:Identifier>28</cvb:Identifier>
</ovc:identifier>
<cvb:legalName>V-ICT-OR</cvb:legalName>
</organization>
4. Lijsten
Om een overzicht te krijgen van alle types concepten die aanwezig zijn in een bepaald domein:
http://{domein}/lijst
In lijsten worden alle instanties van een bepaald concept weergegeven.
http://{domein}/lijst/{concept}
Optioneel kan er nog een paginanummer en aantal resultaten per pagina weergegeven worden.
Het overzicht van de lijsten gebruiken om te kijken naar wijzigingen van versies. Daarvoor zullen er in de resultaten niet alleen concepten, maar ook de versies van de service en de versie van het formaat (bvb. OSLO 1.0 of OSLO 1.1 - in de metadata van het antwoord) worden meegestuurd.
TODO: Overeenkomen + uitleg structuur metadata: in XML en RDF; evenwaardig met statuscode, errorcode, eigen omschrijving als extra veld aan herkomst of identificatie?
http://example.com/lijst/organisatie
Vraag
Type:
GET
Antwoord
RDF
<http://example.com/id/Organization/1> a <http://purl.org/oslo/ns/localgov#Organization> .
<http://example.com/id/Organization/10> a <http://purl.org/oslo/ns/localgov#Organization> .
<http://example.com/id/Organization/11> a <http://purl.org/oslo/ns/localgov#Organization> .
...
XML
<!-- wrapped in XML response body -->
<organizations>
<organization>
<ovc:identifier>
<cvb:Identifier>1</cvb:Identifier>
</ovc:identifier>
</organization>
<organization>
<ovc:identifier>
<cvb:Identifier>10</cvb:Identifier>
</ovc:identifier>
</organization>
<organization>
<ovc:identifier>
<cvb:Identifier>11</cvb:Identifier>
</ovc:identifier>
</organization>
...
</organizations>
4.1 Registratie
Een lijst kan geregistreerd worden door, afhankelijk van de onderliggende technologie, een template te definië"ren die alle instanties van een bepaald type concept gaat weergeven.
De parameters die meegegeven worden in de request aan het domein om een nieuwe service te registreren zijn technologie-afhankelijk. Dit is in principe geen probleem aangezien het lokaal bestuur zelf verantwoordelijk is voor de registratie van de services die het wil ontsluiten. Er kan hierbij gewerkt worden met een gebruikersinterface of een API.
Onze voorbeeld-implementatie ondersteunt beiden: de creatie van een nieuwe service aan de hand van API of aan de hand van een webformulier.
http://example.com/lijst/organisatie
Vraag
Type:
POST
Content:
{
title: "List of organizations",
description: "Uris of organizations in OSLO Consortium.",
date: "2014-02-20",
type: "sparql",
cache_minutes: "5",
draft: "0",
endpoint: "http://example.com/sparql",
query: "CONSTRUCT { ?s a <http://purl.org/oslo/ns/localgov#Organization> } WHERE { ?s a <http://purl.org/oslo/ns/localgov#Organization> }"
}
4.2 Navigatie
Deze lijsten kunnen per concept binnen getrokken worden in een toepassing en het meegegeven paginanummer kan gebruikt worden om efficient te navigeren zonder onnodig een ellenlange lijst te hebben waar de gebruiker sowieso niet in geïnteresseerd is.
De parameters in de request aan de resource zijn daarvoor afhankelijk van de implementatie en erg technologie-afhankelijk.
Het is belangrijk rekening te houden met het risico bij data die veel wordt gewijzigd. Dan is het nodig om tijdens het navigeren te werken met een tijdelijke bijgehouden kopie (cache van de resultaten) in plaats van rechtstreeks op het datamodel.
http://example.com/lijst/organisatie
Vraag
Type:
GET
URL Parameters:
limit = 5
offset = 10
Antwoord
Ingekorte lijst (zie ander voorbeeld)
5. Operaties op Resources
Het is niet enkel mogelijk om de staat van de aanwezige resource op te vragen (zij het als een lijst van types, lijst van resources, of een specifieke resource zelf). Er is ook interactie met deze resources mogelijk, via de ondersteuning van basis operaties (CRUD) en optioneel geavanceerde operaties zoals filters en zoekoperaties op lijsten van resources.
Deze operaties werken enkel op individuele resources; niet op lijsten.
http://{domein}/id/{concept}/{referentie}
5.1 Create
Bij een create wordt de referentie meegegeven in de content maar is de referentie nog niet aangemaakt dus hoeft deze niet meegegeven te worden.
http://{domein}/id/{concept}
Nieuwe resources kunnen aangemaakt worden door op de URI die van toepassing is de nieuwe attributen mee te sturen in OSLO XML of OSLO RDF formaat. Deze zullen echter verpakt moeten worden volgens de onderliggende technologie zodat de service toepassing deze data kan afhandelen en een nieuwe resource kan aanmaken op de gegeven uri. Er kan dus gebruik gemaakt worden van een nieuw referentie en een create operatie op die plaats zorgt voor de introductie van de resource met deze referentie.
Een create is geen goede strategie voor synchronisatie (bulk), daarvoor is een ‘pull’ operatie om alle wijzigingen op te vragen beter geschikt.
Bij een REST Service vertaalt een ‘Create’ operatie zich naar een POST request.
5.2 Read
De read operatie is standaard ondersteund door alle services.
Zie de sectie Resources voor voor meer informatie.
5.3 Update
Aanpassen van een resource, kan op dezelfde manier als create, hier is het enkel nodig om de velden die aangepast worden mee te geven in de request
Bij een REST Service vertaalt een ‘Update’ operatie zich naar een PATCH request.
5.4 Destroy
Het verwijderen van een resource gebeurt aan de hand van de URI en door aan te geven dat de interactie de verwijdering van de resource beoogt.
Bij een REST Service vertaalt een ‘Destroy’ operatie zich naar een DELETE request.
6. Operaties op Lijsten
Geavanceerde operaties kunnen in principe zowel aan client-side als aan server-side geimplementeerd worden op basis van de basis operaties op resources en lijsten. In sommige gevallen is het echter interessant om al op voorhand bepaalde lijsten te creeren. De twee meest evident operaties: filteren en zoeken in lijsten kunnen als een service voorzien worden.
6.1 Filters
Voor elk customfilter wordt op voorhand bepaalt op welke parameters kan gefilterd worden (welke optioneel zijn en welke niet).
http://{domein}/lijst/{concept}/?match=filterterm
of
http://{domein}/lijst?match=filterterm
De registratie van een customfilter gebeurt op dezelfde manier als een lijst. De configuratie van de parameters is gelinkt aan de onderliggende implementatie.
http://example.com/lijst/organisatie?legalName=V-ICT-OR
Vraag
Type:
GET
URI parameters:
legalName : V-ICT-OR
Antwoord
RDF
<http://example.com/id/Organization/28> regorg:legalName "V-ICT-OR" .
XML
<!-- wrapped in XML response body -->
<organizations>
<organization>
<ovc:identifier>
<cvb:Identifier>28</cvb:Identifier>
</ovc:identifier>
<cvb:legalName>V-ICT-OR</cvb:legalName>
</organization>
</organizations>
Minimale vereiste filter:
- gewijzigd (in een bepaalde periode)
Aanbevolen filter:
- exacte match op key (om relaties te kunnen reconstrueren, bvb. het opvragen van hoedanigheden gelinkt aan een bepaald persoon)
Dit is in het bijzonder interessant om bijvoorbeeld de hoedanigheden op te vragen van een bepaalde organisatie.
http://example.com/lijst/hoedanigheid?organization=28
Vraag
Type:
GET
URI parameters:
organization : 28
Antwoord
RDF
<http://example.com/id/organisatie/28> oslo:hasMembership <http://example.com/id/hoedanigheid/28.1> .
XML
<!-- wrapped in XML response body -->
<memberships>
<membership>
<ovc:identifier>
<cvb:Identifier>28.1</cvb:Identifier>
</ovc:identifier>
</membership>
</memberships>
6.2 Zoeken
Voor het zoeken zal er naast een databank, ook nood zijn aan een index. In de index komen dan alle nuttige tekstuele attributen terecht, gelinkt aan hun resource identifier.
http://{domein}/lijst/{concept}?q=zoekterm
of
http://{domein}/lijst?q=zoekterm
Voor elke zoekservice is het nodig om vooraf te zien welk zoekscenario relevant is en welke velden daarbij nodig zijn, of er gezocht kan worden over alle velden die geconfigureerd zijn heen of enkel in specifieke velden.
Als resultaat volgt er typisch een lijst van identifiers per concept of indien het gaat over een algemene zoekopdracht een lijst van identifiers gekenmerkt met hun types.
http://example.com/lijst/organisatie
Vraag
Type:
GET
URI parameters:
q: V-ICT-OR
Antwoord
RDF
<http://example.com/id/Organization/28> regorg:legalName "V-ICT-OR" .
XML
<!-- wrapped in XML response body -->
<organizations>
<organization>
<ovc:identifier>
<cvb:Identifier>28</cvb:Identifier>
</ovc:identifier>
<cvb:legalName>V-ICT-OR</cvb:legalName>
</organization>
</organizations>
7. Identificatie en Logging
Naast het exact overnemen van bestaande richtlijnen binnen de organisatie omtrent toegang tot data bij bevragingen en aanpassingen van services bevelen we aan om bij de uitwisseling de volgende informatie mee te geven. We onderscheiden twee situaties: het algemene geval dat alle operaties dekt en het speciale geval waarbij ook gegevens worden aangepast. Algemeen
ldentificatie; bijhouden wie wat doet en wanneer (datumstempel):
WANNEER + WIE (partij) + WELKE TOEPASSING
de gegevens voor het loggen worden hiervoor meegeven bij elke vraag.
Dit kan afgesproken worden via gebruiksvoorwaarden die ondertekend dienen te worden alvorens een “AGENT-ID” verleend te krijgen (bvb. een token of een API key of eenvoudigweg de naam van de gebruiker).
Dit is van toepassing op eender welke resource.
Vraag
Type:
Eender
URI parameters:
Eender
Extra parameter:
AGENT-APPLICATION: toepassing
AGENT-ID: wie
of
ACCES_TOKEN: toeganscode verkregen na authenticatie
Indien er entiteiten worden gewijzigd dan wordt de datum van laatste wijziging per entiteiten aangepast: in de entiteit Herkomst en Identificatie.
Het is aanbevolen om intern (niet voor de uitwisseling), alle acties op de data bij te houden in een log of een historiek.
We stellen het OAuth 1.0a protocol voor om maximale veiligheid te bekomen, zelfs indien er met niet-versleutelde verbindingen wordt gewerkt.
Fig. 3 image3
A. Acknowledgements
De specificatie is ontwikkeld in een multidiciplinaire werkgroep met 58 mensen uit 28 organisaties en vertegenwoordigers van het ISA programma.
De OSLO standaard is een resultaat van een publiek-private samenwerking , geïnitieerd door V-ICT-OR, de Vlaamse ICT Organisatie. Het project werd gesponsord door Vlaamse ICT dienstenleveranciers (BCT, CEVI, Remmicom en; Schaubroeck) en overheden (CORVE, Digipolis).
Onderzoeksactiviteiten voor het testbed werden gesponsord door het OSLO consortium en het departement Economie, Wetenschap en Innovatie van de Vlaamse Overheid (EWI - Open Data).
Naast deze consortiumpartners nodigde V-ICT-OR ook een aantal experts uit vanuit de overheid: AGIV en AMC (bestuurszaken).