Results API v1.1.0 (Concept 24-02-2025)

Titel

Results API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 1.1.0

schemaVersion: 1.1.0

Datum

24 Februari 2025

Auteur

Werkgroep Toetsen en examineren

Acties

• Review door werkgroep (wijzigingen ten opzichte van versie 0.9.2 zijn geel gemarkeerd)

Gegevensdienst

• Leerresultaten

Scopes

• eduv.result

Entiteiten

• object AssessmentScoresAndResults

• object Assessment

• object ScoreScale

• object StudentScoresAndResults

  • object ScoreEntry

  • object ResultEntry

Verzender

• Digitaal toetssysteem

Ontvanger

• Administratiesysteem leerresultaten

• Leermiddelendashboard

Endpoints

Administratiesysteem leerresultaten

• POST /results: Process assessment scores and/or results

Leermiddelendashboard

• POST /results: Process assessment scores and/or results

OperatieID

postResults

Samenvatting

Het verzoek om bij het ontvangende systeem de toetsscores & -resultaten te verwerken voor een individuele student of groep van studenten.

Beschrijving

Lijst van score & resultaat items per student, met het verzoek nieuwe scores/resultaten te creëren of bestaande scores/resultaten te wijzigen. Het bericht is ingericht op groepsgewijze aanlevering of aanlevering van individuele student. Bij de lijst is algemene informatie gevoegd zoals toets/examen, afnamemoment en opmerkingen.

Tags

Administratiesysteem leerresultaten
Leermiddelendashboard

Parameters bij request

-

Object in request body

Object AssessmentScoresAndResults, met onderliggende objecten StudentScoresAndResults, Assessment en ScoreScale.

Antwoorden (statuscodes)

201 (Created): “Het verzoek is geaccepteerd de verwerking heeft plaatsgevonden; dit heeft tot de creatie van een resource geleid.“
In dit geval gaat het om volledige ontvangst, acceptatie en verwerking van het gehele bericht. Is er afwijzing op basis van een onderdeel van het bericht dan wordt het hele bericht afgewezen. Bij grote berichten kan een afwijzing lastig zijn voor de verzender; mogelijke oplossing is het bericht dan in stukken te verzenden.

202 (Accepted): “Het verzoek is geaccepteerd voor verwerking, maar de verwerking heeft nog niet plaatsgevonden; in feite zou de verwerkingen nog niet gestart kunnen zijn. De verwerking zal later wel of niet plaatsvinden, waarbij het verzoek bij de verwerking eventueel zou kunnen worden afgewezen.“
Ontvanger heeft nog geen mechanisme om fouten die bij de verwerking naar voren komen terug te melden aan verzender (bijvoorbeeld een bericht met het verwerkingsresultaat sturen naar verzender). Verzender heeft nog geen mechanisme om de verwerking te controleren (bijvoorbeeld een specifiek onderdeel uit het bericht opvragen bij ontvanger).

In deze eerste versie kunnen ontvangende systemen alleen terugkoppeling geven op bericht niveau. Ofwel, een bericht is volledig geaccepteerd (202 of 201), of een bericht is volledig geweigerd (400). Fouten die door middel van HTTP-resultaatcodes 400, 401 en 403 kunnen worden teruggeven, hebben dus alleen betrekking op het bericht. Niet op de individuele resultaten.

Antwoorden (foutcodes)

400 (Bad request)

401 (Unauthorized)

403 (Forbidden)

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor dit object .

ad80f160- cd06-48dd-af15-84263e173082

V

Indien de status of het result wijzigt wordt hetzelfde id gehanteerd.

additionalInfo

string

string

Additionele informatie of opmerking over de afname

HAVO-normering
Betrapt op spieken

O

Dit veld kan bijvoorbeeld gebruikt worden om onderscheid te maken in toetsresultaten van dezelfde onderwijsdeelnemer met een normering op HAVO en VWO niveau.

Ook kan het veld gebruikt worden om een reden op te geven waarom de afname is afgebroken. Bijvoorbeeld internet viel uit.

assessment-
DateTime

string

datetime

Tijdstempel van moment waarop de toetsafname gestart of afgesloten is.

2017-07-21T17:32:28Z

V

assessment-Definition

object

Assessment

Definitie van toets en toetsonderdelen bestaande uit identifier en naam van toets en toetsonderdelen.

Zie Object Assessment

V

Vanuit individuele score of resultaat kan worden verwezen naar een toets/toetsonderdeel. De toetsdefinitie hoeft niet bekend te zijn bij de ontvanger.

employees

array

object EmployeeReference

Lijst van verwijzingen naar onderwijsmedewerkers die het Toetsresultaat van de Leerling mogen administreren in het ontvangende systeem.

[{ “userMasterIdentifier”: “ABC456”, “userIds”: [ { “userId”: “XYZ456”, “userIdType”: “ASI” } ] }], zie Object: referentie eindgebruiker

V*

In vo is minimaal 1 onderwijsmedewerker verplicht om de resultaten in het ontvangende systeem te kunnen doorzetten.

Een verwijzing naar een onderwijsmedewerker is gespecificeerd in een object met de attributen userMasterIdentifier en userIds. Attribuut userIds is een array van de velden userId en userIdType.

Waarde van userIdType is conform de secundaire identifiers voor een Onderwijsmedewerker, zie pagina identiteiten.

reviewUrl

string

url

Een URL naar de details over alle scores en resultaten van dit bericht in het Digitaal toetssysteem

https://toetssysteem.nl/review123abc

O

In andere (internationale) standaarden wordt dit veld ook wel deeplink of submission review url genoemd.

Een onderwijsmedewerker kan door het klikken op deze reviewUrl bij aanvullende informatie komen over de resultaten.

school

object

object SchoolReference

Verwijzing naar de onderwijsorganisatie waar de onderwijsdeelnemers de opleiding volgen waarvoor ze deelnemen aan de toetsafname.

[{ “organisationMasterIdentifier”: “ABC123”, “organisationIds”: [ { “organisationId”: “XYZ123”, “organisationIdType”: “AS_ID” } ] }], zie Object: referentie onderwijsorganisatie

V

Dit veld is verplicht.

Een verwijzing naar de school/organisatie is gespecificeerd in een object met de attributen organisationMaster-Identifier en organisationIds. Attribuut organisationIds is een array van de velden organisationId en organisationIdType.

Waarde van organisationIdType is conform de secundaire identifiers voor een Onderwijsorganisatie, zie pagina identiteiten.

schoolPeriod

string

string

Een referentie naar een Schoolperiode (SchoolPeriod) waarop de scores en resultaten betrekking hebben.

2024-2025

V

Binnen po en vo wordt hier alleen het bekende, vaste formaat “eejj-eejj“ voor schooljaar gebruikt (e staat voor eeuw, j staat voor jaar).​

scoreScale-Definitions

array

ScoreScale

Definitie van de scoreschalen die van toepassing zijn op de scores en resultaten.

Zie Object ScoreScale

O

Vanuit individuele score of resultaat kan worden verwezen naar een of meer scoreschalen.

studentScores-AndResults

array

StudentScoresAndResults

De scores en resultaten van een individuele student (onderwijsdeelnemer)

Zie Object StudentScoresAndResults

O

Kan leeg zijn als alle scores en resultaten van alle studenten ontbreken, bijvoorbeeld door calamiteit.

timestamp

string

datetime

Tijdstempel waarop het bericht is samengesteld.

2017-07-21T17:32:28Z

V

toolName

string

string

De naam van het systeem (de tool) waaruit de scores en resultaten zijn verzonden.

Toetssysteem A

O

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

string

Unieke identifier voor de Toets

6c92d082- 0d03-4194-b352-988b2e6f9ae6

TV_GRA-01

V

Dit id hoeft niet bekend te zijn bij de ontvanger.

Dit id van maximaal 36 karakters kan een toetscode zijn uit de OSO toetscodelijst of een leverancier-eigen uuid.

name

string

string

Naam van de Toets die wordt getoond in de Administratie om de toetsresultaten aan een resultaatkolom toe te wijzen

Schoolexamen
Kijk- en Luistertoetsen HAVO5

V

De naam van de Toets is herkenbaar voor de medewerkers.

version

string

string

Versie van de Toets

2

O

Voor verwijzing naar de versie van de toets, met name bedoeld voor methodetoetsen.

subjects

array

[ subjectPrefix, subjectName ]

Vakken of leergebieden van de toets

[
{“PO/spe”, “Spelling”}, {“PO/verk”, “Verkeer”}
]

O

Deze lijst van vakken/leergebieden is optioneel.

Een vak/leergebied (object Subject) bestaat uit de attributen afkorting (subjectPrefix) en naam (subjectName), zoals in Catalogue API. Beiden zijn verplicht,

Werkingsregel is om dit object Subject te vullen conform de waardelijst afspraken voor vakken, zie Waardenlijst vakken: subjectPrefix uit kolom “Prefix” en subjectName uit kolom “Vaknaam” van dit Excel-bestand.

studyLevelId

string

uuid

Code als verwijzing naar het onderwijsniveau van de toets

82ca4442-246c-44b3-a562-7b101793feb4

O

Waarde is de referentie naar het betreffende Object StudyLevel in Education API en Waardelijst Onderwijsniveaus, gebaseerd op de niveaus van SLO (deze is hier te vinden).

Binnen po worden alleen de enkelvoudige onderwijsniveaus gebruikt, zoals referentie naar “PO groep 1” of “PO groep 8”.

parts

array

[ id, name, index ]

De onderdelen van de toets voor de toetsresultaten

[
{ “part1”, “Module 1”, 1},
{ “part2”, “Module 2”, 2 }
]

O

Een toets hoeft geen onderdelen te hebben.

Een onderdeel-item bestaat uit de attributen id, name en index. Allen zijn verplicht,

Het id van maximaal 36 karakters kan een toetscode zijn uit de OSO toetscodelijst of een leverancier-eigen uuid.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor de Scoreschaal.

6c92d082- 0d03-4194-b352-988b2e6f9ae7

V

Deze identifier hoeft niet bekend te zijn bij de ontvanger.

name

string

string

Naam van de Scoreschaal die wordt/is gebruikt om scores in resultaten om te zetten.

O

De naam van de Scoreschaal is herkenbaar voor de medewerkers.

scoreScaleEntries

array

[ LHS , RHS ]

De items van scoreschaal in combi LHS en RHS die de scoreschaal definiëren.

[{ “0.0-5.4”, “Onvoldoende”},{“5.5-10.0”, “Voldoende”}]

V

Geeft voor een interval aan waarden (LHS) aan welke resultaatwaarde (RHS) daarvoor geldt.

Het formaat van LHS is een enkele getalswaarde ('x') of een bereik van twee getallen ('x-y'). In het eerste geval is de waarde de ondergrens van het interval. Bij het bereik zijn de getallen de onder- respectievelijk bovengrens van het interval. Intervallen zijn inclusief de grenswaarden.

RHS is een tekstuele waarde.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor dit item met individuele scores en resultaten

14d807e9-8684-4a84-bc08-d48cd20eb733

V

Indien de status of het resultaat wijzigt wordt hetzelfde id gehanteerd.

additionalInfo

string

string

Additionele informatie of opmerking over deze scores en resultaten van deze deelnemer

HAVO-normering
Betrapt op spieken

O

Dit veld kan bijvoorbeeld gebruikt worden om onderscheid te maken in toetsresultaten van dezelfde onderwijsdeelnemer met een normering op HAVO en VWO niveau.

Ook kan het veld gebruikt worden om een reden op te geven waarom er een resultaat ontbreekt. Bijvoorbeeld fraude of niet aanwezig.

missing

boolean

{True,False}

Geeft aan of scores en resultaten ontbreken

True, False

O

Verplicht als scores en results leeg zijn

results

array

object

Een of meerdere resultaat-items die zijn behaald door een individuele deelnemer bij deze afname.

zie object ResultEntry

O

reviewUrl

string

url

Een URL naar de details over deze scores en resultaten van deze deelnemer in het Digitaal toetssysteem

-

O

In andere (internationale) standaarden wordt dit veld ook wel deeplink of submission review url genoemd.

Een onderwijsmedewerker kan door het klikken op deze reviewUrl bij aanvullende informatie komen.

scores

array

object

Een of meerdere score-items die zijn behaald door een individuele deelnemer bij deze afname.

zie object ScoreEntry

O

status

string

ENUM

De status van dit deelnemer scores/resultaten item

in progress
final
canceled

O

Dit veld is additioneel toegevoegd en kan gebruikt worden om toetsresultaten in verschillende stadia door te sturen.

Defaultwaarde is final

student

object

StudentReference

Verwijzing naar de onderwijsdeelnemer die de scores en resultaten heeft behaald bij de betreffende toetsafname.

[{ “userMasterIdentifier”: “ABC123”, “userIds”: [ { “userId”: “XYZ123”, “userIdType”: “ASI” } ] }], zie Object: referentie eindgebruiker

V

Dit attribuut is verplicht.

Een verwijzing naar een onderwijsdeelnemer is gespecificeerd in een object met de attributen userMasterIdentifier en userIds. Het attribuut userIds is een array van de velden userId en userIdType.

Waarde van userIdType is conform de secundaire identifiers voor een Onderwijsdeelnemer, zie pagina identiteiten.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit (dit object StudentScoresAndResults) is aangemaakt.

2024-07-21T17:32:28Z

V

Let op, dit is dus niet datumtijdstip van afname!

dateLastModified

string

datetime

Datum en tijdstip waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2024-08-11T15:31:12Z

V

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

resultValue

string

string

De resultaatwaarde zoals behaald door de toetsdeelnemer.

Onvoldoende

5.1

V

Bevat de waarde van het scoregetal en deze waarde moet voldoen aan de typering in resultType.

resultType

string

string

Type van resultaatwaarde (In veld resultValue)

OVG

Grade0.0-10.0

V

De waarde komt uit waardelijst ResultTypes.

assessmentId

string

string

Verwijzing naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment) waartoe het resultaat behoort.

part3

O

Let op, kan verwijzen naar toetsonderdeel (object assessmentPart) of de gehele toets (object Assessment).

AE

AE

Niveauaanduiding volgens schaal A tot en met E.​

{A,B,C,D,E}​

PO​

AVI

AVI

Niveauaanduiding voor leesvaardigheid.

{AVI-Start, AVI-M3, AVI-E3, AVI-M4, AVI-E4, AVI-M5, AVI-E5, AVI-M6, AVI-E6, AVI-M7, AVI-E7, AVI-Plus}​

PO​

CAE

Gecorrigeerde AE

Gecorrigeerd niveauaanduiding volgens schaal A tot en met E, als de toets is afgenomen op een afwijkende datum. ​

{A,B,C,D,E}​

PO​

CIV

Gecorrigeerde IV

Gecorrigeerd niveauaanduiding volgens schaal I tot en met V, als de toets is afgenomen op een afwijkende datum. ​

{I,II,III,IV,V}​

PO​

DLE​

DLE​

Geeft aan hoeveel maanden onderwijs een gemiddelde leerling nodig heeft om hetzelfde niveau te bereiken. DLE is de afkorting van Didactische Leeftijd Equivalent. ​

Getal uit [0,60]​

PO​

Education-Level

Onderwijs-niveau

Onderwijsniveau​

{PrO, VMBO-BB, VMBO-KB, VMBO-GL/TL, HAVO, VWO}​

PO en VO​

Functioning-Level

Functionerings-niveau

Functioneringsniveau​

Toelichting: het functioneringsniveau geeft een indruk van het vaardigheidsniveau van de leerling in relatie tot het landelijk gemiddelde niveau. 
Bijvoorbeeld functioneringsniveau M4E4 betekent het vaardigheidsniveau tussen het landelijk gemiddelde niveau voor medio groep 4 en eind groep 4 ligt.

Bijvoorbeeld functioneringsniveau <M3 geeft aan dat het resultaat lager dan de M3 is maar omdat de doelgroep van de toets vanaf groep 3 is, is geen exactere duiding van het niveau mogelijk.

Bijvoorbeeld functioneringsniveau >E5 geeft aan dat het resultaat hoger dan de E5 is maar omdat de doelgroep van de toets tot en met groep 5 is, is geen exactere duiding van het niveau mogelijk.

{<M3, M3, M3E3, E3, E3M4, M4 tot en met E7, E7M8, M8, >M8}​ en eventueel Mx of Ex voorafgegaan door < of >.

PO​

Grade0-10​

Schoolcijfer 0-10​

Resultaat is een schoolcijfer (geheel getal van 0 tot en met 10)​

Getal uit [0,10]​

PO en VO​

Grade0.0-10.0​

Schoolcijfer 0.0-10.0​

Resultaat is een schoolcijfer (decimaal getal van 0.0 tot en met 10.0)​

Getal uit [0.0,10.0]​

PO en VO​

IV

IV

Niveauaanduiding volgens schaal I tot en met V.​

{I,II,III,IV,V}​

PO​

LA

Leer-achterstand

Het gegeven dat met behulp van de waarde van DL en van DLE volgens de formule 1- (DLE/DL) kan worden uitgerekend.​

Toelichting: DL (Didactische Leeftijd) geeft het aantal maanden aan dat een leerling onderwijs heeft gevolgd vanaf groep 3 (bijvoorbeeld aan eind groep 3 is de DL 10). DLE geeft het niveau van een kind aan dat is behaald bij de toets.

Voorbeeld: Het DL van een kind is 22. Als de behaalde DLE 18 is, dan is de leerachterstand 1 - (18 / 22) = 0,18 (afgerond).

Decimaal getal uit [-1,1]​

PO​

LGH

Laag-Gemiddeld-Hoog

Geeft aan of leerling/student lager dan gemiddeld, gemiddeld of hoger dan gemiddeld heeft gepresteerd.​

{Laag,Gemiddeld,Hoog}​

PO en VO​

OVG​

Onvoldoende-Voldoende-Goed

Geeft aan in welke mate de leerling/student de leerstof of vaardigheid beheerst; is waarde uit waardelijst {Onvoldoende, Voldoende, Goed}.​

{Onvoldoende, Voldoende, Goed}​

PO en VO​

PassOrFail​

Geslaagd/Gezakt​

Geeft aan of leerling/student geslaagd of gezakt is (PassOrFail)​

{Geslaagd, Gezakt}​

VO​

Percentiel​

Percentiel-score​

Score volgens de indeling in gelijke percentielen; het is de maat die aangeeft hoe een score zich verhoudt tot de scores van een groep.​

Getal uit [0,100]​

PO en VO​

RnERK​

Referentie-niveau ERK​

Het Referentieniveau Europees ReferentieKader (ERK) onderscheidt 6 taalcompententieniveaus (dus voor MVT): van beginner tot near-native.​

{<A1,A1,A2, B1,B2, C1,C2}​

PO en VO​

RnTR​

Referentie-niveau Taal en Rekenen​​

De referentieniveaus Taal en Rekenen (volgens Meijerink) zijn landelijke standaarden die beschrijven welk niveau leerlingen op specifieke momenten in hun onderwijsloopbaan moeten behalen op het gebied van taal en rekenen. ​

Toelichting: Het niveau <1F wordt door toetsaanbieders omschreven als ‘Lager dan 1F' of ook wel 'Op weg naar 1F’.

{<1F,1F,1S, <2F,2F,2S, <3F,3F,3S, 4F,4S}​

PO en VO​

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

scoreValue

string

string

De scorewaarde zoals behaald door de toetsdeelnemer.

64
6

V

Bevat de waarde van het scoregetal en deze waarde moet voldoen aan de typering in scoreType.

scoreType

string

string

Type van scorewaarde (In veld scoreValue)

zie Waardelijst ScoreTypes

V

De waarde komt uit waardelijst ScoreTypes.

scoreMaximum

integer

integer

De maximaal te behalen scorewaarde (in veld scoreValue)

100

O

Waarde voldoet aan scoreType en de scoreValue is kleiner of gelijk aan deze waarde.

assessmentId

string

string

Verwijzing naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment) waartoe de score behoort.

Module3

O

Let op, kan verwijzen naar toetsonderdeel (object assessmentPart) of de gehele toets (object Assessment).

scoreScaleIds

array

string

De verwijzingen naar de betreffende scoreschalen voor omzettingen van score naar resultaat.

[“OVG-schaal“, “Schoolcijfer“]

O

Iedere verwijzing moet zijn gedefinieerd in scoreScales (object ScoreScale).

NumberItems​

Aantal gemaakte items​

Aantal door leerling/student gemaakte opgaven/items.​

Getal uit [0,n]​

PO en VO​

Number-Incorrect​

Aantal fout gemaakt​

Aantal fout gemaakte opgaven/items door leerling/student.​

Getal uit [0,n]​

PO en VO​

Number-Correct​

Aantal goed gemaakt​

Aantal goed gemaakte opgaven/items door leerling/student.​

Getal uit [0,n]​

PO en VO​

Percentage-Correct​

Percentage goed​

Percentage goed gemaakte opgaven door leerling/student​
(=Aantal goed gemaakte opgaven / Aantal opgaven).​

Getal uit [0,n]​

PO en VO​

DurationIn-Seconds​

Tijdsduur (in seconden)​

Totaal aantal seconden dat de toetsafname voor de leerling/student heeft geduurd.​

Getal uit [0,n]​

PO en VO​

ScorePoints​

Scorepunten​

Aantal door leerling/student behaalde punten na nakijk/correctie​. Merk op, bij opgaven/items met gelijk gewicht is dit Aantal goed gemaakt.​

Getal uit [0,n]​

PO en VO​

SkillScore​

Vaardigheids-score​

Het getal dat aangeeft wat een leerling kan op een leergebied; getal is de gemeten eenheid op de vaardigheidsschaal (ook wel Ontwikkelscore genoemd).
Toelichting: Scores op dezelfde toets zijn vergelijkbaar met scores van dezelfde leerling of leeftijdsgenoten.

Getal uit eenheden van de vaardigheidsschaal​

PO​