Het datamodel – Werken met de Onderwijsloket API (2/4)

Door dit model te begrijpen, wordt het veel eenvoudiger om data uit de API te combineren en nieuwe toepassingen te bouwen.

In dit artikel kijken we daarom naar de structuur achter het platform: hoe de data van het Onderwijsloket is georganiseerd en met elkaar verbonden.

Van informatie naar datasets

Alle informatie in het Onderwijsloket-platform is georganiseerd in zogeheten collecties. Je kunt een collectie zien als een dataset waarin een bepaald type informatie wordt opgeslagen.

Een collectie bevat meerdere items. Elk item vertegenwoordigt één concreet stuk informatie.

Bijvoorbeeld:

• de collectie articles bevat kennisbankartikelen

• de collectie faqs bevat veelgestelde vragen

• de collectie programs bevat opleidingen

• de collectie educational_institutions bevat onderwijsinstellingen

Ontwikkelaars kunnen deze collections via de Content API opvragen en combineren in hun eigen toepassingen.

Verschillende soorten collecties

Binnen het platform onderscheiden we verschillende typen collecties. Elk type vervult een eigen rol binnen het datamodel.

Contentcollecties

Dit zijn de belangrijkste datasets van het platform. Ze bevatten de informatie die uiteindelijk aan gebruikers wordt getoond.

Voorbeelden zijn:

• artikelen uit de kennisbank

• FAQ’s

• opleidingen

• video’s en podcasts

• ervaringsverhalen

Deze collecties vormen de basis van vrijwel alle toepassingen die met de API worden gebouwd.

Categorisatiecollecties

Naast de inhoud zelf bevat het platform ook datasets die worden gebruikt om informatie te classificeren.

Deze collecties maken het mogelijk om content te filteren en te groeperen. Samen vormen ze de taxonomie van het Onderwijsloket-platform: een set categorieën en labels waarmee informatie logisch kan worden geordend en teruggevonden.

Voorbeelden zijn:

• onderwerpen (topics)

• rollen binnen het onderwijs

• sectoren

• doelgroepen

• kwalificaties

Dankzij deze taxonomie kunnen ontwikkelaars bijvoorbeeld:

• artikelen filteren op onderwerp

• opleidingen tonen per sector

• content tonen voor een specifieke doelgroep

Doordat deze categorisatiecollecties in meerdere datasets worden gebruikt, kunnen verschillende soorten informatie met elkaar worden verbonden en in context worden weergegeven.

Metacollecties

Sommige datasets bevatten aanvullende informatie over andere content.

Voorbeelden zijn:

• auteurs van artikelen

• bronnen die in artikelen worden gebruikt

• locaties van onderwijsinstellingen

Deze metadata zorgen ervoor dat informatie context krijgt en beter kan worden hergebruikt.

Block collecties

Block collecties worden gebruikt binnen contentdocumenten om modulaire onderdelen van een pagina op te slaan.

In plaats van een artikel als één grote, platte tekst op te slaan, wordt de inhoud opgebouwd uit verschillende blokken, wat het mogelijk maakt om dynamisch content te embedden in een tekst. Elk blok verwijst naar een record in een aparte collectie.

Voorbeelden van zulke blokken zijn:

• callouts

• afbeeldingen

• knoppen

• mediaplayers

• gerelateerde contentlijsten

Deze blokken worden opgeslagen als relaties binnen het veld editor_nodes. De daadwerkelijke inhoud van het document staat in een JSON-structuur (Tiptap), waarin wordt verwezen naar deze blokken.

Voor ontwikkelaars betekent dit dat een artikel vaak bestaat uit:

1. een JSON-document met de structuur van de pagina

2. een set gerelateerde blokken die de inhoud van specifieke componenten bevatten

Meer hierover lees je in het artikel over Content Documents in de developer documentatie.

Junctioncollecties

Veel relaties in het platform zijn many-to-many relaties. Dat betekent dat één item met meerdere andere items verbonden kan zijn.

Bijvoorbeeld:

• een artikel kan meerdere onderwerpen hebben

• een opleiding kan door meerdere instellingen worden aangeboden

• een instelling kan meerdere opleidingen hebben

Om deze relaties te beheren gebruikt het platform zogenaamde junctioncollecties. Deze collecties slaan de verbinding tussen datasets op.

Voor ontwikkelaars betekent dit dat data vaak via relaties wordt opgehaald in plaats van via losse tabellen, waarbij je door de junctions heen je query opbouwt.

De belangrijkste datasets van het platform

Om het datamodel overzichtelijk te houden, hebben we de collecties gegroepeerd in een aantal logische secties. Deze indeling heeft geen technische functie, maar helpt om het platform beter te begrijpen.

De kennisbank

De kennisbank bevat objectieve informatie over werken in het onderwijs.

Hier vind je onder andere:

• artikelen over het onderwijs

• veelgestelde vragen

• bronnen en documenten

Deze datasets vormen de basis van de kennisbank op onderwijsloket.com en kunnen ook in andere platforms worden geïntegreerd.

De navigator

De navigator bevat informatie over organisaties en opleidingen binnen het onderwijs.

Belangrijke collecties zijn bijvoorbeeld:

• opleidingen

• onderwijsinstellingen

• locaties

• regionale onderwijsloketten

Deze datasets maken het mogelijk om navigators of studiezoekers te bouwen. Veel van deze data zijn afkomstig van externe databronnen en worden periodiek gesynchroniseerd.

Media

Naast feitelijke informatie bevat het platform ook verhalen en ervaringen uit het onderwijs.

De Media-sectie bevat bijvoorbeeld:

• video-interviews

• podcasts (series, seizoenen, afleveringen)

• persoonlijke ervaringsverhalen

Deze content helpt gebruikers om een beter beeld te krijgen van het werken in het onderwijs.

Routes

Een van de meest unieke datasets in het platform zijn de routes naar het onderwijs. Er bestaan duizenden mogelijke routes naar een functie in het onderwijs. Door een aantal vragen te beantwoorden over hun achtergrond en ambities kunnen gebruikers ontdekken welke routes voor hen relevant zijn.

Deze functionaliteit wordt mogelijk gemaakt door een combinatie van datasets zoals:

• vragen

• antwoordopties

• route-stappen

• volledige routes

Relaties tussen datasets

Wat het datamodel van het Onderwijsloket krachtig maakt, is dat de verschillende datasets met elkaar verbonden zijn.

Een paar voorbeelden:

• artikelen kunnen gekoppeld zijn aan onderwerpen en sectoren

• opleidingen zijn gekoppeld aan de kwalificatie die je ermee behaald en de functies die je ermee kunt beoefenen

• podcasts en video’s kunnen gekoppeld zijn aan gasten, sectoren, functies en andere categorieën.

• routes refereren aan artikelen waar je meer info vindt over een betreffende routestap

Aan de slag met het datamodel

In de developer documentatie vind je een volledig overzicht van alle collecties, velden en relaties binnen het platform.

Daar kun je onder andere:

• alle beschikbare datasets verkennen in de API Explorer

• zien welke relaties er bestaan tussen collecties

• voorbeeldqueries bekijken

In het volgende artikel

In het volgende artikel in deze serie focussen we op de zoeklaag van de Onderwijsloket API. Hierin ontdek je hoe je met de search engine je gebruikers snel naar relevante artikelen, opleidingen en meer leidt.