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