Results API 2.0.1

Titel

Results API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 2.0.1

schemaVersion: 2.0.0

Datum

15 September 2025

Auteur

Werkgroep Toetsen en examineren

Acties

Gegevensdienst

• Leerresultaten

Scopes

• eduv.result

Entiteiten

• object AssessmentScoresAndResults

• object Assessment

• object ScoreScale

• object StudentScoresAndResults

  • object ScoreEntry

  • object ResultEntry

Verzender

• Digitaal toetssysteem

• Gebruiksomgeving digitale leermiddelen

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 onderwijsdeelnemer of groep van onderwijsdeelnemers.

Beschrijving

Lijst van score & resultaat items per onderwijsdeelnemer, 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 onderwijsdeelnemer. 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 van dit object wijzigt wordt hetzelfde id gehanteerd.

additionalInfo

string

string

Additionele informatie of opmerking over de afname

HAVO-normering

Betrapt op spieken

Internet viel uit

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.

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 eventuele toetsonderdelen bestaande uit identifier en naam van toets en toetsonderdelen.

V

Deze toetsdefinitie is gespecificeerd in het object Assessment.

De toetsdefinitie hoeft niet bekend te zijn bij de ontvanger.

Vanuit individuele score of resultaat kan worden verwezen naar de toets of een toetsonderdeel uit deze toetsdefinitie.

employees

array

object EmployeeReference

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

[{ “userMasterIdentifier”: “ABC456”, “userIds”: [ { “userId”: “XYZ456”, “userIdType”: “ASI” } ] }]

V*

In po is dit veld niet verplicht.
In vo is voor uitwisseling naar referentiecomponent Administratiesysteem leerresultaten (zoals de cijferadministratie van Magister of Somtoday) minimaal 1 onderwijsmedewerker in dit veld ‘employees’ verplicht om de resultaten in het ontvangende systeem formeel door te kunnen zetten, aangezien deze resultaten doorgaans meetellen voor het PTO/PTA.
Voor uitwisseling naar referentiecomponent Leermiddelendashboard (zoals een LVS-dashboard binnen een LAS) geldt de verplichting van minimaal 1 onderwijsmedewerker in dit veld ‘employees’ niet.
De leverancier van een systeem die beide referentiecomponenten aanbiedt, heeft de keuze per component een specifiek aanleverpunt (endpoint) beschikbaar te stellen. Verzendende systemen koppelen vervolgens aan het (voor de ontvanger) best passende aanleverpunt (met bijbehorende verplichting van onderwijsmedewerker) voor de resultaten van de toetsen/examens.
Is het gebruik van de resultaten voor de verzender onbekend (bijvoorbeeld of deze meetellen voor PTO/PTA), dan moet worden aangeleverd bij het referentiecomponent Administratiesysteem leerresultaten. Het ontvangende systeem verzorgt dan eventueel zelf de interne gegevensoverdracht naar het referentiecomponent Leermiddelendashboard.

Een verwijzing naar een onderwijsmedewerker is gespecificeerd in een object EmployeeReference met de attributenuserMasterIdentifier en userIds. Element userIds is een array van de velden userId en userIdType, zie Object: referentie eindgebruiker.

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 object in het Digitaal toetssysteem.

Door het volgen van deze URL kan aanvullende informatie over de resultaten worden ingezien.

https://toetssysteem.nl/review123abc

O

Het moet een complete en geldige URL zijn.

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

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” } ] }]

V

Deze verplichte verwijzing naar de school/organisatie is gespecificeerd in een object SchoolReference met de attributen organisationMasterIdentifier en organisationIds. Element organisationIds is een array van de velden organisationId en organisationIdType, zie Object: referentie onderwijsorganisatie.

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.

O

Deze scoreschaal is gespecificeerd in het object ScoreScale.

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

studentScores-AndResults

array

StudentScoresAndResults

De scores en resultaten van een individuele onderwijsdeelnemer.

O

Deze lijst van objecten StudentScoresAndResults bevat per object de scores en -resultaten van een onderwijsdeelnemer.

Deze lijst mag ontbreken als alle scores en resultaten van alle onderwijsdeelnemers 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 bij de score of het resultaat kan worden getoond, bijvoorbeeld 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.

Bij kleine wijzigingen in de normering blijft het id van de methodetoets gelijk en is er een nieuwe versie; die versie wordt geduid in dit veld.
Oude toetsresultaten moeten dus genormeerd blijven worden tegen de vorige versie van de toets.

subjects

array

[ subjectPrefix, subjectName ]

Vakken of leergebieden van de toets

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

O

Deze optionele lijst van vakken/leergebieden van objecten Subject met per object de verplichte attributen afkorting (subjectPrefix) en naam (subjectName), zoals in Catalogue API.

Dit object Subject moet worden gevuld 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 onderwijsniveau in Object StudyLevel (zoals in Education API) en gevuld met waarden uit Waardelijst Onderwijsniveaus, gebaseerd op de niveaus van SLO (deze is hier te vinden).

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

parts

array

[ id, name, index ]

De onderdelen van de toets voor duiding van een score of resultaat

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

O

Deze lijst bestaat uit objecten AssessmentPart met de velden id, name en index, zie de volgende tabelregels voor specificatie.

Een toets hoeft geen onderdelen te hebben, dus deze lijst is optioneel.

• id

string

string

Unieke identifier voor het toetsonderdeel

part3

V

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

• name

string

string

Naam van het toetsonderdeel die bij de score of het resultaat kan worden getoond, bijvoorbeeld in de administratie om de toetsresultaten aan een resultaatkolom toe te wijzen

Module 3

V

De naam van het toetsonderdeel is herkenbaar binnen de toets.

• index

integer

integer

Het volgnummer van het toetsonderdeel om toetsonderdelen in volgorde van voorkeur te kunnen tonen

3

V

Getal groter gelijk aan 1. Er mogen geen
dubbele volgnummers voorkomen.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor de scoreschaal.

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

V