Course API

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

  • 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

  • eduv.course

Objecten

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.

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
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.

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
</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 object

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
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 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
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 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.