Skip to content

GraphQL naar Linked Data: De Enhancer

In de sectie omtrent GraphQL beschrijven wij reeds hoe we GraphQL kunnen gebruiken om data te leveren in een JSON (JavaScript Object Notation) formaat. Wij gebruiken dit - naast een ontsluitingskanaal richting de eindgebruiker - ook als mogelijkheid om Linked Data te genereren.

JSON-LD

In de omzetting van JSON naar Linked Data maken wij veel gebruik van de open standaard JSON-LD, zoals gestandaardiseerd door het W3C. JSON-LD - in zijn essentie - biedt de mogelijkheid om van JSON data lichtgewicht Linked Data te genereren.

Logo JSON-LD

Deze documentatie is gebaseerd op JSON-LD 1.1, zoals beheerd door de W3C.

Enhancer

Het Data Science Team heeft een component ontwikkeld dat op basis van een GraphQL endpoint in staat is JSON-LD te bevragen. De enhancer neemt de volgende configuratie:

  • JSON-LD Context
  • Een GraphQL endpoint

Vervolgens dient de Enhancer als een additioneel endpoint waar op basis van een accept header data data wordt teruggeven in een bepaald formaat:

  • application/n-quads
  • application/ld+json

Vervolgens zijn er twee manieren om de enhancer aan te spreken:

Bevragen obv een query

Het enhancer endpoint kan benaderd worden met een POST request met in de body een GraphQL query, zoals

{
    "query": "{ bag2nummeraanduiding(first:10 ) { jsonldid jsonldtype objecteindtijd objectbegintijd tijdstipregistratie eindregistratie tijdstipregistratielv tijdstipeindregistratielv primaryTopic { jsonldid jsonldtype identificatie { jsonldid jsonldtype }} inonderzoek geconstateerd documentnummer documentdatum aanduidingrecordinactief aanduidingrecordcorrectie huisnummer huisletter huisnummertoevoeging postcode nummeraanduidingstatus ligtin ligtaan }}"
}

en de headers

{
    "content-type": "application/json", 
    "accept": "application/ld+json"
}

Het reusltaat van deze bevraging is een JSON-LD respons van de desbetreffende GraphQL query.

Bevragen obv voorgedefiniëerde queries

Voor het omzetten van de GraphQL levering naar Linked Data bereiden we vaak voorgedefiniëerde queries voor in de enhancer, waarmee op basis van (paginatie) parameters een set aan objecten opgevraagd kan worden. Dit is bijvoorbeeld bruikbaar in een full load van een dataset als Linked Data.

Het configureren van deze voorgedefiniëerde queries werkt momenteel door in de Enhancer een graphql query toe te voegen onder de directory /query. Zie bijvoorbeeld de query /bag/pand.graphql.

{ 
    "query": "{ bag2pand(#filter#) { jsonldid jsonldtype jsonldbase jsonldvocab jsonldlabel voorkomenidentificatie begingeldigheid eindgeldigheid tijdstipregistratie eindregistratie tijdstipregistratielv tijdstipeindregistratielv primaryTopic { jsonldid jsonldtype identificatie { jsonldid jsonldtype namespace lokaalid } } geometrie geconstateerd documentnummer documentdatum oorspronkelijkbouwjaar pandstatus vorigeGeldigeVersie vorigeGeregistreerdeVersie } } " 
}

Tip voor de developer: Gebruik deze website om een GraphQL query te verlossen van newlines.

Vervolgens kan de data bevraagd worden met een request naar http://enhancer-endpoint/bag/pand/0/1000 waarbij de laatste twee (paginatie) parameters zijn die gedefiniëerd zijn in de enhancer. Door gebruik te maken van deze parameters kan over de gehele set aan objecten worden gelopen.

JSON-LD Context

Een voorbeeld van een (ingekorte) JSON-LD Context (van de BAG) is hieronder te vinden:

{
  "@context": {
    "@base": "https://bag2.basisregistraties.overheid.nl/bag/id/registratie/",
    "@version": 1.1,
    "@vocab": "https://bag2.basisregistraties.overheid.nl/bag/def/",
    "adresseerbaarobjectstatus": {
      "@context": {
        "@base": "https://bag2.basisregistraties.overheid.nl/bag/id/status/"
      },
      "@id": "status",
      "@type": "@id"
    },
    "begingeldigheid": {
      "@id": "nen3610:beginGeldigheid",
      "@type": "xsd:date"
    },
    "bronhouder": {
      "@context": {
        "@base": "https://bag2.basisregistraties.overheid.nl/bag/id/bronhouder/"
      },
      "@type": "@id"
    },
    "data": "@nest",
    "dct": "http://purl.org/dc/terms/",
    "documentdatum": {
      "@id": "dct:created",
      "@type": "xsd:date"
    },
    "documentnummer": {
      "@id": "dct:identifier"
    },
    "eindgeldigheid": {
      "@id": "nen3610:eindGeldigheid",
      "@type": "xsd:date"
    },
    "eindregistratie": {
      "@id": "eindRegistratie",
      "@type": "xsd:dateTime"
    }
}

waarbij keys in de JSON-LD context verwijzen naar attributen en/of objecten in de GraphQL typedefs (bijv. documentnummer, eindgeldigheid, etc.). Op deze manier weet de Enhancer hoe deze attributen om te zetten zijn naar een Linked data formaat (zoals nquads).

Linked Data

In de pipeline van het omzetten van een GraphQL levering hebben we een manier nodig om (in batch) over de totale set aan objecten cq. voorkomens heen te lopen. We gebruiken de volgende header:

{
    "accept": "application/n-quads"
}

en lopen over de gehele set heen die we willen bevragen middels de voorgedefinieerde queries. Deze batch bevragingen worden aangeroepen vanuit een minimaal stuk code wat wij tot voorheen de microservice noemden. Dit proces wordt verder toegelicht in de documentatie rondom onze ETL Pipeline.