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

[joepio]

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.

[joepio]

Afgelopen jaar ben ik bezig geweest met een RDF + JSON compliant specificatie, genaamd JSON-AD (staat voor JSON-Atomic-Data). Deze is, net als JSON-LD, compatible met zowel linked data (RDF) als met standaard JSON. De standaard zelf is echter een stuk lichter en veel makkelijker om te parsen.

Voorbeeldje van van hoe JSON-AD zich verhoudt met JSON, RDF en JSON-LD is hier te zien.

Al met al is daarmee een alternatieve aanpak voor dit probleem ontstaan. In plaats van een @context object toe te voegen, kan je de keys vervangen met URLs.

Denk dat dit nu misschien wat te laat is om op te nemen, maar vond dit wel de juiste plek om deze overweging te delen!