Case 1: Een API opzetten

REST en RDF, de technologie die Linked Data onderbouwt, delen een aantal fundamentele principes:

• Aan de basis van informatie ligt het concept ‘resource’;
• Maken gebruik van HTTP(S) en HTTP(S) URI’s;
• Zelfbeschrijvend, er is geen voorkennis nodig om de relaties tussen resources te begrijpen;
• Geschikt voor Domain Driven Design.

In combinatie zijn ze in staat om resources (data) te ontsluiten samen met het achterliggend informatiemodel, gebruik te maken van meer gesofisticeerde semantiek voor state-transitions en het Web of Data write-enabled te maken.

De W3C Recommendation Linked Data Platform is een specificatie die patronen aanreikt om RESTful HTTP services te bouwen die in staat zijn om read-write operaties uit te voeren op Linked Data. Daarnaast wint een specificatie in opbouw, Hypermedia Driven Web APIs (HYDRA), aan populariteit om Linked Data principes toe te passen op REST API’s door een vocabularium van termen aan te reiken waarmee generieke API clients gemaakt kunnen worden. Tot slot is het mogelijk om bestaande REST API’s die gebruik maken van JSON om te vormen met minimale inspanning door een @context definitie mee te geven in de HTTP Link Header. Meer informatie hieromtrent is terug te vinden in de JSON-LD specificatie.

Case 3: Gegevensuitwisseling

Naast een semantisch afgestemd informatiemodel heeft een toepassing nood aan een concrete methode voor gegevensuitwisseling. Een mogelijk formaat om semantiek mee te geven in API payloads is JSON-LD (JSON Linked Data). JSON-LD laat ontwikkelaars toe om applicaties en diensten die gebruik maken van JSON, met een minimale inspanning Linked Data enabled te maken.

De stabiele JSON-LD 1.0 specificatie werd gepubliceerd door W3C als een Recommendation. De meest recente specificatie en documentatie is te vinden op json-ld.org. JSON-LD kenmerkt zich door het toevoegen van volgende elementen aan een klassiek JSON object:

• @context: bevat een oplijsting van keys die doorheen het JSON(-LD) object gebruikt worden samen met een link (IRI) die verwijst naar hun definitie en indien relevant een type die aangeeft wat de verwachte value is voor deze keys. Op deze manier wordt de “context” meegegeven aan de ontvanger van het JSON object.
• @id: een unieke identificator voor objecten.
• @type: bepaalt het type van het object of de node en kan ook meegegeven worden in de context.

Voor een volledige uiteenzetting van de specificatie verwijzen we naar JSON-LD 1.0.

De W3C Recommendation Linked Data Platform is een specificatie die patronen aanreikt om RESTful HTTP services te bouwen die in staat zijn om read-write operaties uit te voeren op Linked Data. Daarnaast wint een specificatie in opbouw, Hypermedia Driven Web APIs (HYDRA), aan populariteit om Linked Data principes toe te passen op REST API’s door een vocabularium van termen aan te reiken waarmee generieke API clients gemaakt kunnen worden. Tot slot is het mogelijk om bestaande REST API’s die gebruik maken van JSON om te vormen met minimale inspanning door een @context definitie mee te geven in de HTTP Link Header. Meer informatie hieromtrent is terug te vinden in de JSON-LD specificatie.

Gebruik van @context definities

De @context heeft als doel de semantiek samen met de data te ontsluiten. Dit kan op verschillende manieren gebeuren:

• Hergebruik van bestaande context definitie
  Voor OSLO vocabularia bestaan herbruikbare context files in JSON-LD formaat waar naar verwezen kan worden vanuit een JSON-LD object.
  
  

  OSLO vocabularium	Context file
  Generiek	http://data.vlaanderen.be/context/generiek.jsonld
  Adres	http://data.vlaanderen.be/context/adres.jsonld
  Persoon	http://data.vlaanderen.be/context/persoon.jsonld
  Organisatie	http://data.vlaanderen.be/context/organisatie.jsonld
  Dienst	http://data.vlaanderen.be/context/dienst.jsonld

  
  
  Voorbeeld: hergebruik van OSLO context definitie.
  
  
• Combineren van meerdere context definities
  

  In vele gevallen is het mogelijk dat meerdere entiteiten uit verschillende vocabularia in hetzelfde JSON-LD object voorkomen. Daarom is het mogelijk om ook meerdere context referenties mee te geven in hetzelfde JSON-LD object. In het geval dat bepaalde termen overlappen, zal de laatst gedefinieerde term (in onderstaand voorbeeld uit de adres context) voorgaande termen met dezelfde benaming overschrijven.

  
  
  Voorbeeld: hergebruik van OSLO context definitie.
  
  
• Gebruik van eigen termen
  

  Wanneer een bestaande API zijn informatie wil ontsluiten conform de OSLO semantische informatiemodellen als JSON-LD, zonder de reeds gebruikte keys aan te passen, kan er voor gekozen worden om een eigen context file te creëren. Het blijft evenwel een vereiste om eerst het semantisch afstemmingstraject te doorlopen. Voor meer informatie met betrekking tot het creëren van een context file refereren we naar de JSON-LD specificatie. Voor bestaande API’s kan de context definitie meegegeven worden in de HTTP Link Header in plaats van als onderdeel van de payload.

  
  
  Voorbeeld: hergebruik van OSLO context definitie.
  
  
• Bestaande context definitie uitbreiden
  

  Indien een JSON-LD object gebruik maakt van zowel OSLO als andere entiteiten, en indien deze andere entiteiten relevant zijn voor de uitwisselingen van informatie met andere toepassingen of agentschappen, kan een bestaande OSLO @context uitgebreid worden met nieuwe termen.

  
  
  Voorbeeld: OSLO context definitie voor persoon uitbreiden met nieuwe termen van het FOAF vocabularium voor het weergeven van een profielfoto.
  
  
  Verduidelijking: Het is ook mogelijk om in een JSON-LD object gewone JSON attributen mee te geven, zonder deze te definiëren in de @context. Wanneer het object als JSON-LD geparsed wordt, zullen termen die niet voorkomen in de @context genegeerd worden. De term zal dus enkel beschikbaar zijn voor de lokale applicatie, binnen de bounded context.
• Overschrijven van context definities
  

  In JSON-LD is het mogelijk om de definitie van termen te overschrijven. Dit is vooral relevant wanneer een bestaande API omgevormd wordt zonder de JSON-structuur aan te passen én wanneer bepaalde keys een andere betekenis hebben afhankelijk van het niveau waarop ze voorkomen.

  
  
  Voorbeeld: de eigenschap ‘plaats’ heeft afhankelijk van waar het voorkomt in het JSON-LD object, ofwel als verwacht type ‘GeografischePlaats’, wat de standaard optie is in OSLO en dus ook in de OSLO context definitie voor persoon staat, of ‘Adresvoorstelling’. In onderstaand voorbeeld wordt ‘GeografischePlaats’ als type gebruikt voor plaats onder ‘inwonerschap’ en overschreven met ‘Adresvoorstelling’ in de context definitie onder ‘heeftGeboorte’.
  
  

Omgaan met identificatoren

In Linked Data, en zo ook in JSON-LD, wordt als identificator voor een object waar mogelijk gebruik gemaakt van een URI (uniform resource identifier). In JSON-LD kan elk ‘node object’ een eigen identificator hebben, aangeduid met de key “@id”. Om hier invulling aan te geven kan gebruik gemaakt worden van absolute URI’s, relatieve URI’s of ‘blank node identifiers’.

Wanneer de value van de “@id” key niet start met http(s) wordt de string geïnterpreteerd als een relatieve URI. Als basis wordt dan de URI van de request header genomen. Alternatief kan in de context definitie ook een ‘base URI’ vastgelegd worden.

Een blank node identifier is een string die dienst doet als identificator voor een blank node object. Een blank node identifier is een lokale identificator en is niet persistent, waardoor ze niet bruikbaar zijn buiten de applicatie of service waar ze hun oorsprong vinden. Blank node identifiers hebben steeds _: als prefix, opdat ze niet als relatieve URI zouden geïnterpreteerd worden.

Nesting en arrays

In JSON-LD wordt het nesten van objecten gebruikt om relaties tussen objecten weer te geven, niet om een hiërarchisch verband voor te stellen. Elk genest object kan bijgevolg ook een eigen “@id” en “@type” hebben.

Net zoals bij JSON kunnen arrays weergegeven worden door gebruik te maken van vierkante haakjes. In tegenstelling tot JSON, zijn bij JSON-LD arrays standaard niet geordend. Om het concept van collecties te bewaren kan gebruik gemaakt worden van @list.

Definiëren van codelijsten, taxonomieën en thesauri

Het Simple Knowledge Organisation System (SKOS) is een generiek datamodel voor het delen van controlled vocabularies zoals codelijsten, thesauri en taxonomieën in een machine-leesbaar formaat op het Web. Het beschikbaar maken van codelijsten volgens SKOS brengt enkele voordelen met zich mee:

• De-referencing: de principes van Linked Data zijn ook van toepassing op codelijsten en stellen dat elke term in een codelijst moet corresponderen met een URI op basis van het HTTP protocol. Mensen die een term uit een codelijst tegenkomen kunnen dan makkelijk de betekenis opzoeken door de URI in te voeren in een web browser.
• Machine-leesbaarheid: via de URI kan zowel een machine- als mens-leesbare versie van de codelijst worden opgehaald. SKOS is bovendien een W3C Recommendation, wat interoperabiliteit bevordert met andere systemen die SKOS implementeren.
• Meertaligheid: SKOS laat toe om makkelijk labels en definities in meerdere talen toe te voegen.

Een codelijst kan in SKOS worden voorgesteld door gebruik te maken van de volgende klassen, eigenschappen en relaties:

• skos:ConceptScheme: de codelijst zelf kan voorgesteld worden als een skos:ConceptScheme.
• skos:Concept: elke term in de codelijst is een instantie van de klasse skos:Concept.
• skos:hasTopConcept: deze eigenschap laat toe om een hiërarchie in een codelijst te stoppen, bijvoorbeeld types en subtypes, door voor een skos:ConceptScheme aan te duiden welke termen zich op het hoogste niveau bevinden.
• skos:inScheme: deze eigenschap laat toe om vanuit een bepaalde term (een skos:Concept) aan te geven bij welke codelijst deze behoort.
• skos:definition: deze eigenschap laat toe om een definitie (in tekstvorm) mee te geven aan een terms in de codelijst (een skos:Concept).
• skos:notation: deze eigenschap laat toe om aan een bepaalde term een code toe te kennen.
• skos:prefLabel: het (mens-leesbare) label dat geassocieerd is met de term.

Containers en paginering

Soms is het nodig om in één JSON(-LD) document meerdere top-level objecten mee te geven die allen dezelfde context delen als antwoord op een specifieke API request. Bijvoorbeeld om een overzichtspagina te maken of een oplijsting van objecten te tonen met een bepaalde filter erop toegepast. In deze gevallen kan gebruik gemaakt worden van HYDRA. De HYDRA specificatie voor hypermedia-driven Web APIs laat toe om meer informatie mee te geven aan een container, specifiek voor het aansturen van REST APIs, in lijn met de principes van Linked Data.

Input of output structuur vastleggen met JSON-LD framing

JSON-LD framing is een techniek waarbij ontwikkelaars een bepaalde structuur (een frame) kunnen opleggen aan het JSON-LD payload. Er kan onder meer een onderscheid gemaakt worden tussen verplichte en optionele nodes en standaardwaarden voor attributen kunnen worden meegegeven. Op die manier kan consistentie gegarandeerd worden en kunnen deze frames dienen als basis voor tests, validatie en het toelaten van meerdere datastructuren langs input zijde. Het Framing Algoritme is bovendien in staat om JSON-LD objecten om te zetten naar de gewenste structuur. Voor meer details verwijzen we naar de specificatie.

Beschikbare tools en libraries

Er bestaan tools en libraries voor de meeste web-programmeertalen. Onderstaande tabel geeft een overzicht van JSON-LD processors en API’s in verschillende programmeertalen.

De OSLO tool SpecificationGenerator kan gebruikt worden om vertrekkend uit een domeinmodel een JSON-LD context file te genereren. Verder is de JSON-LD Playground een handige tool om snel JSON-LD objecten te valideren op vlak van syntax.

Andere serialisaties

Naast JSON-LD bestaan tal van andere serialisaties voor Linked Data, elk met een eigen syntax. De meest gebruikte zijn:

• RDF/XML
• Turtle
• N-triples
• Notation3
• RDFa (HTML annotaties)