Results API

Titel

Results API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.2

schemaVersion: 0.9.2

Datum

11 November 2024

Auteur

Werkgroep Toetsen en examineren

Acties

• Geen openstaande acties

Gegevensdienst

• Leerresultaten

Scopes

• eduv.result

Entiteiten

• object AssessmentScoresAndResults

• object StudentScoresAndResults

• object Assessment

• object ScoreScale

Verzender

• Digitaal toetssysteem

Ontvanger

• Administratiesysteem leerresultaten

• Leermiddelendashboard

Endpoints

Administratiesysteem leerresultaten

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

OperatieID

postResults

Samenvatting

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

Beschrijving

Lijst van score & resultaat items per student, met voor ieder lijst item het verzoek nieuwe deelnemers scores/resultaten te creëren of bestaande deelnemers 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

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

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

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

[userMasterIdentifier, userIds]

Array van Onderwijsmedewerkers die het Toetsresultaat van de Leerling mogen administreren in het ontvangende systeem.

-

V

Minimaal 1 Onderwijsmedewerker is toegevoegd.

Onderwijsmedewerker is gespecificeerd met een userMasterIdentifier of een alternatieve identiteit in attribuut userIds.

Het userIds is wederom een array van het userId en het userIdType.

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

-

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

[organisation-MasterIdentifier, organisationIds]

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

-

V

School is verplicht.

School als organisatie is gespecificeerd met een organisationMaster-Identifier of een alternatieve identiteit in attribuut organisationIds.

Het organisationIds is wederom een array van het organisationId en het organisationIdType.

organisationIdType is conform de secundaire identifiers voor een Onderwijsorganisatie.

Zie pagina identiteiten.

schoolPeriod

string

string

De schoolperiode waarop de scores en resultaten betrekking hebben.

Schooljaar 2024-2025

V

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

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

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

[resultValue, resultType, assessmentId]

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

[
{ “O”, “OVG” },
{ “5.1”, “0.0-10.0”, “part3” }
]

O

Een resultaat-item bestaat uit de drie attributen resultValue, resultType en AssessmentId. Alleen resultValue en resultType zijn verplicht,

Het resultValue bevat de waarde van het resultaat en deze waarde moet voldoen aan typering in resultType . De waarde van resultType komt uit waardelijst.

Het assessmentId verwijst naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment).

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

[scoreValue, scoreType, scoreMaximum, assessmentId, scoreScaleId]

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

[
{ 64, “0-100”},
{ 6, “0-10” }
]

O

Een score-item bestaat uit de vijf attributen scoreValue, scoreType, scoreMaximum, assessmentId en scoreScaleId. Alleen scoreValue en ScoreType zijn verplicht,

Het scoreValue bevat de waarde van het scoregetal en deze waarde moet voldoen aan typering in scoreType. Het scoretype (in scoreType) komt uit waardelijst. scoreMaximum is de maximum te behalen score en moet daarmee voldoen aan scoreType; en scoreValue moet kleiner of gelijk aan dit maximum zijn.

Het assessmentId verwijst naar betreffende toets of toetsonderdeel in Toetsdefinitie (assessment).

Het scoreScaleId verwijst naar betreffende scoreschaal in Scoreschaaldefinities (scoreScales).

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

[userMasterIdentifier, userIds]

De Onderwijsdeelnemer die de scores en resultaten heeft behaald bij de betreffende toetsafname.

-

V

De Onderwijsdeelnemer is verplicht.

Onderwijsdeelnemer is gespecificeerd met een userMasterIdentifier of een alternatieve identiteit in attribuut userIds.

Het userIds is wederom een array van het userId en het userIdType.

userIdType is conform de secundaire identifiers voor een Onderwijsdeelnemer .

Zie pagina identiteiten.

dateCreated

string

datetime

Datum waarop de entiteit is aangemaakt

2024-07-21T17:32:28Z

V

dateLastModified

string

datetime

Tijdstempel 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

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.

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

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.