Results API

Titel

Results API

Status

In ontwikkeling BEsluitvorming in beheer

Versie

0.0.8

Datum

17 Maart 2024

Auteur

Uitwisselen summatieve toetsresultaten

Acties

  • Review door werkgroep Toetsen en Examineren

De Results API wordt gebruikt om leerresultaten te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Leerresultaten met het Digitaal toetssysteem als Verzender.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

  • Leerresultaten

Scopes

  • result

Entiteiten

Verzender

  • Digitaal toetssysteem

Ontvanger

  • Administratiesysteem leerresultaten

Endpoints

Administratiesysteem leerresultaten

  • POST Accept AssessmentScoresAndResults message

Berichtdefinitie: Toetsresultaten

Het bericht “Toetsresultaten” bevat de “Toetsscores en -resultaten” in object AssessmentScoresAndResults, met onderliggende objecten StudentScoresAndResults, Assessment en ScoreScale.

afbeelding-20240411-083514.png
Figuur: Gegevensmodel van bericht Toetsresultaten

Dit bericht wordt gebruikt voor het uitwisselen van de toetsscores en/of toetsresultaten van één of meerdere toetsdeelnemers. Deze toetsresultaten worden bepaald door het Digitaal toetssysteem en op enig moment vrijgegeven; dit is het moment waarop de uitwisseling kan gaan plaatsvinden. Het bericht kan enkelvoudig zijn (scores en resultaten van 1 onderwijsdeelnemer) of meervoudig (scores en resultaten van meerdere onderwijsdeelnemers gebundeld).

Object AssessmentScoresAndResults

Het object AssessmentScoresAndResults (Toetsscores en -resultaten) inclusief onderliggende objecten StudentScoresAndResults (Deelnemerscores en -resultaten) met bijbehorende gegevensgroepen omvat de gegevens over de scores en resultaten door individuele onderwijsdeelnemers behaald bij een bepaalde toetsafname, en wordt in bovenstaande figuur weergegeven.

afbeelding-20240411-084501.png
Figuur: AssessmentScoresAndResults gegevensobject

In het gegevensobject AssessmentScoresAndResults bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

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.

assessment-System

string

string

Het toetssysteem waaruit de scores en resultaten zijn verzonden.

Toetssysteem A

O

 

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

 

schemaVersion

string

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

1.3.0

V

Conform Semantic Versioning 2.0.0

Object StudentScoresAndResults

Het gegevensobject StudentScoresAndResults bestaat uit een gegevensblok met de scores en resultaten van een individuele student (onderwijsdeelnemer), en wordt in onderstaand figuur weergegeven.

In het object StudentScoresAndResults bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

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, scoreScaleId]

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

[{ O, OVG },{ 5.1, 0.0-10.0 }]

O

Een resultaat-item bestaat uit de vier attributen resultValue, resultType, AssessmentId en scoreScaleId. 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/toetsonderdeel in Toetsdefinitie (assessment).

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

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, 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 vier attributen scoreValue, scoreType, 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.

Het assessmentId verwijst naar betreffende toets/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

 

 

 

Object Assessment

Het object Assessment (Toetsdefinitie) omvat de definitiegegevens van de toets en de toetsonderdelen die betrokken zijn bij de gegevens in het bericht Toetsresultaten, zoals in bovenstaande figuur is weergegeven.

In het gegevensobject Assessment bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

id

string

uuid

Unieke identifier voor de Toets

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

V

De assessmentId hoeft niet bekend te zijn bij de ontvanger.

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.

parts

object

[ id, name ]

De onderdelen van de toets voor de toetsresultaten

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

O

Een toets hoeft geen onderdelen te hebben.

Een onderdeel-item bestaat uit de attributen assessmentId en assessmentName. Beiden zijn verplicht,

 

Object ScoreScale

Het object ScoreScale (Scoreschaal) omvat de definitiegegevens van scoreschaal die betrokken is bij de scores en resultaten.

In het gegevensobject ScoreScale bevinden zich de gegevens zoals in navolgende tabel gespecificeerd.

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.

 

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.

  • 0.0.2: Berichtdefinities en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.

  • 0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:

    • Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.

    • Het transactiepatroon melding bevestiging is toegepast voor het uitwisselen van het Result berichten. Dit heeft geresulteerd in PUT endpoint voor de meldingen voor de relevante referentiecomponent Cijferadministratie.

    • BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.

    • De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.

    • In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.

    • De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.

  • 0.0.4: Het bericht Score is toegevoegd. Tevens zijn er een bundel van toetsresultaten en een bundel van toetsscores toegevoegd. In de YAML zijn deze berichten geïmplementeerd in PUT (enkele score/resultaat) en POST (meerdere scores/resultaten) endpoints.

  • 0.0.5: GET endpoints om een resultaat of een score op basis van id op te vragen bij het Digitaal toetssysteem zijn aan de YAML toegevoegd. Dit stelt een cijferadministratie in staat om bij onduidelijkheid over de status van een resultaat of een score de laatste gegevens op te vragen.

  • 0.0.6: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.

  • 0.0.7: De berichtdefinities zijn gewijzigd: de vier berichten score en resultaat (individueel en gebundeld) zijn gecombineerd tot 1 bericht met scores en resultaten van een toetsdeelnemer zoals door de werkgroep gewenst. Verwijzing naar cijferadministratie is weggepoetst.

  • 0.0.8: Correcties en verduidelijkingen aangebracht n.a.v. reviewcommentaren van de werkgroep. Naar aanleiding van bespreking zijn de volgende wijzigingen aangebracht:

    • Het object AssessmentScoresAndResults is uitgebreid met schoolPeriod, assessmentSystem en school,

    • Het object Assessment (Toetsdefinitie) is uitgebreid met toetsonderdelen in parts

    • Het object ScoreScale (Scoreschaal) is vervangen door definitie van meerdere scoreschalen in attribuut scoreScales binnen AssessmentScoresAndResults .

    • Het objectStudenttScoresAndResults is uitgebreid met attributen dateCreated en dateLastModified,

    • Individuele score (in object Score) en resultaat (in object Result) is uitgebreid met verwijzing naar betreffende toetsonderdeel (assessmentId) en scoreschaal (scoreScaleId).