Course API

Titel	Course API
Status	IN ONTWIKKELING BESLUITVORMING IN BEHEER
Versie	Documentatie: 0.0.2
Versie	schemaVersion: 0.0.2
Datum	13 December 2023
Auteur	Werkgroep Combineren en arrangeren
Acties	Geen openstaande acties

De Course API wordt gebruikt om informatie over de structuur van leermiddelen bestaande uit leermodules en leermaterialen te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Leermaterialen met de referentiecomponent Leermaterialencatalogus als Bron.

De leermaterialen bevat alle informatie noodzakelijk voor het combineren en arrangeren van leermaterialen in de uitvoering van het onderwijs. Ook bevat het leermateriaal de deeplink die benut kan worden in een Onderwijsleeromgeving. Deze deeplink wordt gebruikt om als onderwijsdeelnemer direct te navigeren naar digitaal leermateriaal binnen een leermiddel. De deeplink kan gebruikt worden om een digitaal leermiddel in gebruik te nemen. Hiervoor is er een vereiste aan het formaat van de deeplink.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst	Leermaterialen
Scopes	course
Entiteiten	Course CourseStructure
Bron	Leermaterialencatalogus
Afnemers	Overkoepelende leermiddelencatalogus Onderwijsleeromgeving Leermiddelendashboard
Endpoints	Leermaterialencatalogus GET Courses GET Course by ID GET CourseStructure by ID
Notifications	De Notifications API kan gebruikt worden om als afnemer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderde Course). Hiervoor dient zowel de bron als de afnemer dan de Berichteninfrastructuur en de Notifications API te hebben geïmplementeerd. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Berichtdefinitie: Course

Het bericht Course beschrijft een LeermiddelStructuur zijnde een LeermateriaalBeschrijving of een LeermoduleBeschrijving. In de LeermiddelStructuur is de titel, omschrijving en de laatste versie en de toepasbaarheid in het onderwijs (vakcode en levels) opgenomen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
courseId	string	string	De unieke identifier voor de Course		V	Waarde mag niet gewijzigd worden
title	string	string	De benaming voor de Course.		V
description	string	string	Korte omschrijving van de Course		O
lastPublished Version	string	string	Laatst gepubliceerde versie van de Course.	#1 #1.2 2022-03-24	V	Versienummer zoals gehanteerd door de leverancier. Bij iedere wijziging op de Course wordt het nummer verhoogd.
studies	array	study	De opleidingseenheden waar deze Course op gericht is.	Zie object study in de Catalogue API	V	Werkingsregel is om dit veld te vullen conform de waardelijst afspraken voor opleidingen, opleidingsjaren en niveaus.
subjects	array	subject	De vakken waar deze Course op gericht is.	Zie object subject in de Catalogue API	V	Werkingsregels is om dit veld te vullen conform de waardelijst afspraken voor vakken.

Berichtdefinitie: CourseStructure (xAPI CMI5)

Het bericht CourseStructure beschrijft een LeermiddelStructuur zijnde een LeermateriaalBeschrijving of een LeermoduleBeschrijving in detailniveau. In het bericht is de metadata, zijn de leerdoelen en is de structuur en de opbouw van de LeermiddelStructuur uit onderliggende Leermaterialen (assignable units, aus) en/of Leermodules (blocks) gespecificeerd. De Onderwijsleeromgeving kan deze boomstructuur tonen en zo onderwijsmedewerkers de mogelijkheid geven om specifieke leermaterialen te plannen voor onderwijsdeelnemers.

In deze eerste uitwerking wordt gebruik gemaakt van de xAPI CMI5 standaard voor het uitwisselen van gegevens over een Leermiddelstructuur in het XML-formaat. Het object is gebaseerd op de internationale CourseStructure standaard zoals beschreven in:

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/v1/CourseStructure.xsd

Deze standard is uitgebreid met een aantal velden conform een extensie zoals beschreven in:

http://www.sanoma.com/cmi5/ExtendedCourseStructureExtension.xsd

Vanwege de adoptie van deze internationale standaard is de conventie voor de benamingen van de velden overgenomen in de berichtdefinitie. Het veld publicationdate wordt daarom niet geschreven als publicationDate.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
course	object	course	Bevat de metadata over de Course	Zie course	V
objectives	array	objective	Bevat de leerdoelen van de Course	Zie objective	O
aus	array	au	Bevat de assignable units (Leermaterialen) van de Course	Zie au	O	Wordt gebruikt zodra de Course bestaat uit een enkel niveau en alleen bestaat uit een aantal Leermaterialen.
blocks	array	block	Bevat de blocks (Leermodules) van de Course	Zie block	O	Wordt gebruikt zodra de Course bestaat uit meerdere niveaus (zoals hoofdstukken en paragrafen).

Object course

In onderstaande tabel is het object Course nader gespecificeerd. In dit object wordt de relevante metadata van de Course beschreven.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	string	De unieke identifier voor deze Course		V	Komt overeen met courseId uit Course berichtdefinitie. Waarde mag niet gewijzigd worden
title	array	[lang, langstring]	Een titel (langstring) en de taal van de titel (lang)	[nl-NL, Hallo]	V	In XML te representeren als: <langstring lang=”nl-NL”>Hallo </langstring> Dit is niet mogelijk in openAPI3, zie issue
description	array	[lang, langstring]	Een beschrijving (langstring) en de taal van de beschrijving (lang)	[nl-NL, Cursusbeschrijving voor Stepping Stones]	V	Zie title
image	string	URI	URI naar een afbeelding om deze Course te representeren		O
publicationdate	string	date	Datum van publicatie van de huidige versie van de Course	2022-11-02	O*	Waarde is in CMI5 niet verplicht. Vullingsregel is om dit veld te vullen met de datum van publicatie van de versie
publisher	string	string	Naam van de uitgever van de Course	Noordhoff	O
streamcode	string	string	Benaming om de Course te identificeren	steppingstone-5e-4vwo	O
version	string	string	De versie van de Course	#1 #1.2 2022-03-24	O*	Waarde is in CMI5 niet verplicht. Vullingsregel is om deze gelijk te stellen aan lastPublished Version in Course bericht Bij iedere wijziging op de Course wordt het nummer verhoogd.
streams	array	stream	Aanduidingen voor streams die gebruikt worden als type in de assignable units. Helpt Leraren om individuele leerroutes voor leerlingen te plannen.	optioneel verdieping Zie stream	O

Object stream

In het Course Object bevat het veld streams één of meerdere stream objecten. Een stream object wordt gespecificeerd conform onderstaande tabel.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

Unieke identifier voor de stream

O

Waarde mag niet gewijzigd worden

description

string

Beschrijving van de stream

optioneel

verdieping

O

Object objective

Een Course bevat één of meerdere Leerdoelen (Objectives). De Leerdoelen worden gespecificeerd op het niveau van de CourseStructure. In de Blocks en Assignable Units is het mogelijk om vervolgens te verwijzen naar de identifiers (objective.id ). Zo is te achterhalen welk onderdeel van de Course bijdraagt aan welk leerdoel.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	string	Unieke identifier voor het leerdoel		V	Waarde mag niet gewijzigd worden
title	string	string	Benaming voor het leerdoel		O
description	string	string	Korte omschrijving van het leerdoel		O

Object assignable unit (au)

De assignable units vormen de basisonderdelen van de Course API. Deze assignable units kunnen worden gezien als een LeermateriaalBeschrijving. De CMI5 standaard ondersteunt geavanceerde launchmethoden, launchmethoden en moveon criteria. Dit is nog niet geïmplementeerd in deze specificatie. In deze beschrijving wordt de metadata van het Leermateriaal beschreven en is ook de Deeplink naar het leermateriaal opgenomen.

Deze deeplink wordt door de Onderwijsleeromgeving gebruikt om een onderwijsdeelnemer de mogelijkheid te bieden om direct te navigeren naar het digitaal leermateriaal binnen een leermethode. De deeplink kan gebruikt worden om een digitaal leermiddel in gebruik te nemen. Hiervoor is er een technische vereiste aan het formaat van de deeplink.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	string	Unieke identifier voor de assignable unit	-	V	Waarde mag niet gewijzigd worden
activity Type	string	string	Beschrijft hoe het leermateriaal te interpreteren.	Oefening Naslagwerk Arrangement Assignment Test Instructie Theorie	V	Dit is een vrij veld. Voorkeur heeft om hier op termijn afspraken over te maken.
launch Method	string	ENUM	Beschrijft hoe de content gepresenteerd dient te worden	AnyWindow OwnWindow	V	Exact gebruik van launchmethod en launchParameters is nog niet gedocumenteerd. Dit veld wordt genegeerd. Default: AnyWindow
moveOn	string	ENUM	Wordt gebruikt door een Onderwijsleeromgeving om te bepalen of een assignable unit volwaardig is afgerond.	Passed Completed CompletedAndPassed Completed OrPassed NotApplicable	V	Dit veld is verplicht maar wordt niet gebruikt. Default: CompletedOrPassed
title	array	[lang, langstring]	Een titel (langstring) en de taal van de titel (lang)	[nl-NL, Hallo]	V	In XML te representeren als: <langstring lang=”nl-NL”>Hallo </langstring> Dit is niet mogelijk in openAPI3, zie issue
description	array	[lang, langstring]	Een beschrijving (langstring) en de taal van de beschrijving (lang)	[nl-NL, Hallo]	O	Zie title
objectives	array	objective .id	Een array van ids van Objectives (Leerdoelen) waar dit Leermateriaal aan bijdraagt.	-	O
url	string	url	Deeplink naar het Leermateriaal	www.uitgever.nl/leermateriaal	V	Optioneel kan een Onderwijsleeromgeving gebruik maken van de parameter product om de Aanbieder een suggestie te geven van het Leermiddel waartoe het Leermateriaal behoort en waarop de onderwijsdeelnemer een aanspraak heeft.
launch Parameters	string	string	De parameters die meegestuurd worden in een Launched statement		O	Exact gebruik van launchmethod en launchParameters is nog geen onderdeel van de specificatie. Dit veld wordt genegeerd.
image	string	URI	URI naar een afbeelding om deze Assignable Unit te representeren	-	O
streamref	string	stream .id	Referentie naar een stream waar dit Leermateriaal binnen valt.	-	O

Object block

Assignable units (Leermaterialen) kunnen gecombineerd worden in een grotere eenheid, zijnde een Block (Leermodule). Een Block kan zelfs ook weer bestaan uit meerdere Blocks. Denk bijvoorbeeld aan een Hoofdstuk Block dat bestaat uit meerdere Paragraaf Blocks, waarbij een Paragraaf Block bestaat uit meerdere Leermateriaal Assignable Units. Deze vrijheid van combineren van Blocks en Assignable Units geven leveranciers van leermiddelen de mogelijkheid om hun content te structureren passend bij het Leermiddel dat ze aanbieden.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	string	Unieke identifier voor de assignable unit	-	V	Waarde mag niet gewijzigd worden
title	array	[lang, langstring]	Een titel (langstring) en de taal van de titel (lang)	[nl-NL, Hallo]	V	In XML te representeren als: <langstring lang=”nl-NL”>Hallo </langstring> Dit is niet mogelijk in openAPI3, zie issue
description	array	[lang, langstring]	Een beschrijving (langstring) en de taal van de beschrijving (lang)	[nl-NL, Hallo]	O	Zie title Veld wordt veelal gevuld met beschrijving van Hoofdstuk of Paragraaf.
blocks	array	block	Een array van Blocks die onderdeel zijn van dit Block	Zie deze Tabel	O	Een Block kan weer bestaan uit één of meerdere Blocks.
aus	array	au	Een array van Assignable Units die onderdeel zijn van dit Block	Zie Tabel 88	O	Een Block kan bestaan uit één of meerdere Assignable Units.
instructions	array	[lang, langstring]	Een instructie (langstring) en de taal van de instructie (lang)	[nl-NL, Hallo]	O	Zie title
image	string	URI	URI naar een afbeelding om dit Block te representeren	-	O
studyload indicator	integer	integer	Een relatieve indicator voor de zwaarte van de studielast	1,2,5	O	Deze informatie is zeer zinvol om te representeren in de studiewijzer. Waarde is een indicatie en geen betreft geen absolute duur in bijvoorbeeld dagen, uren of minuten.

Status- en foutcodes

Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.

Technisch: API specificatie

Release notes

0.0.1: Eerste draft van de API op basis van bestaande documentatie.
0.0.2: De volgende wijzigingen zijn gedaan:
- Conform wijziging in architectuur de schemaVersion als attribuut verwijderd uit de berichtspecificaties.
- De berichtdefinitie Course is bijgewerkt met de attributen studies en subjects conform dezelfde opzet als een Product uit de Catalogue API.