Naar Linked Data: Invoegen van @context JSON-LD object

De huidige API specificatie is goed opweg om niet alleen een mooie REST API te worden, maar ook nog eens om een volwaardige Linked Data API te worden. Met een @context object (zie specificatie JSON-LD) kan dit realiteit worden.

Een @context JSON-LD object beschrijft de mapping tussen JSON keys en een URI. Hierdoor wordt het mogelijk om simpele, reguliere JSON namen te gebruiken, terwijl de semantische betekenis (en de daarbij RDF data) behouden blijft. Met andere woorden: door een @context beschrijving te hebben, kan je een gewone JSON API omzetten naar een RDF Linked Data API. Daarmee wordt het eenvoudig om de data op te slaan in triple stores en om het om te zetten naar formaten zoals Turtle, N-Triples, N-Quads of RDF-XML. Daarnaast maakt het de API nog iets makkelijker om te gebruiken: als een hergebruiker de JSON response wil gebruiken, kan hij de @context opvragen om de specificatie te bekijken.

Dit @context object kan in zijn volledigheid bij iedere respons worden bijgevoegd, maar dit zorgt voor een onnodig grote body. Gelukkig zijn er ook twee manieren om te linken naar een extern @context object, namelijk met een link in de body van de respons of met een speciale HTTP header. Ik zou willen aanbevelen om de eerste methode te gebruiken: een link in de body. Een respons komt er dan als volgt uit te zien:

{
    "@context": "https://vng.nl/ns/open-raadsinformatie/context.jsonld",
    "...": "..."
}

De link naar de @context resolved naar een bestand zoals het onderstaande:

{
    "@context": {
        "ori": "https://vng.nl/ns/open-raadsinformatie/",
        "naam": "ori:naam",
        "...": "..."
    }
}

Sub-issues:

[ ] Het context object samenstellen. Imvertor (de software die voor VNG Realisatie diverse representaties maakt van een UML bestand) zou verantwoordelijk kunnen zijn voor het aanmaken van dit bestand.
[ ] Het bestand online beschikbaar stellen van de @context bestand via een Namespace (URI) waar VNG-Realisatie controle over heeft.
[ ] De @context waarden in de swagger documentatie naar de bovengenoemde URI laten linken. Momenteel tonen ze de waarde "string", dit zou een specifieke string moeten zijn naar het JSON-LD context object.
[ ] De types in het @context object laten resolven naar hun definities. Voorbeeld: Het Vergadering type moet een link hebben, die als je hem opent, gaat naar een definitie van het concept Vergadering.
[ ] De @type velden in de swagger docs laten linken naar de bovengenoemde Class definities van de typen.

VNG-Realisatie / ODS-Open-Raadsinformatie

Naar Linked Data: Invoegen van @context JSON-LD object #16