Course API
- Koen Voermans
Titel | Course API |
Status | In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer |
Versie | Documentatie: 0.0.4 |
schemaVersion: 0.0.4 | |
Datum | 27 September 2024 |
Auteur | Werkgroep Combineren en arrangeren |
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 |
|
Objecten | |
Bron |
|
Afnemers |
|
Endpoints | Leermaterialencatalogus
|
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. |
Object: Course
Het object 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 | 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. |
Object: CourseStructure (xAPI CMI5)
Het object CourseStructure beschrijft een LeermiddelStructuur zijnde een LeermateriaalBeschrijving of een LeermoduleBeschrijving in detailniveau. In het object 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 het object. 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 object. 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 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 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 | string | Unieke identifier voor de stream |
| O | Waarde mag niet gewijzigd worden |
description | string | 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 | 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 | string | ENUM | Beschrijft hoe de content gepresenteerd dient te worden | AnyWindow OwnWindow | V | Exact gebruik van launchmethod en launchParameters is nog niet gedocumenteerd. Default: AnyWindow |
moveOn | string | ENUM | Wordt gebruikt door een Onderwijsleeromgeving om te bepalen of een assignable unit volwaardig is afgerond. | Passed Completed CompletedAndPassed Completed 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 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 | Een array van ids van Objectives (Leerdoelen) waar dit Leermateriaal aan bijdraagt. | - | O |
|
url | string | url | Deeplink naar het 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 | 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. |
image | string | URI | URI naar een afbeelding om deze Assignable Unit te representeren | - | O |
|
streamref | string | stream | 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 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 object Assignable Unit | 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 | 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 objecten.
Het object Course is bijgewerkt met de attributen studies en subjects conform dezelfde opzet als een Product uit de Catalogue API.
0.0.3: Typo’s in the YAML.
0.0.4: Wijzigingen naar aanleiding van RFC’s:
Op basis van RFC002 is de scope aangepast met een prefix
eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.