Students API

Owned by Koen Voermans
Last updated: Jun 28, 2024
6 min read

Titel

Students API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.0

schemaVersion: 0.9.0

Datum

27 Juni 2024

Auteurs

Architectenraad Edu-V

Acties

  • Geen openstaande acties

De Students API wordt gebruikt om persoonsgegevens over onderwijsdeelnemers uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsdeelnemers met het Administratiesysteem onderwijsdeelnemer als Bron.

Scope: werkingsgebieden funderend onderwijs en vavo

De afspraken met betrekking tot de gegevensdiensten uit de administratiesystemen zijn van toepassing op de werkingsgebieden:

  • Primair onderwijs

  • Gespecialiseerd onderwijs

  • Voortgezet onderwijs

  • Voortgezet algemeen volwassenenonderwijs (vavo)

De gegevensdiensten zijn niet ontwikkeld voor het middelbaar beroepsonderwijs. In het middelbaar beroepsonderwijs wordt gebruik gemaakt van OOAPI.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

Onderwijsdeelnemers
Onderwijsdeelnemers Demografie
Onderwijsdeelnemers Communicatie
Onderwijsdeelnemers Toegankelijkheid
Onderwijsdeelnemers Adresgegevens fijndistributie

Scopes

  • student.basic

  • student.demographics

  • student.communication

  • student.accessibility

  • student.deliveryaddress

Objecten

Bron

Administratiesysteem onderwijsdeelnemer

Afnemer

student.basic en student.communication

  • Bestelomgeving leermiddelen

  • Dienst met SSO

  • Authenticerende Dienst

  • Authenticerende Identity Provider

  • Delegerende Identity Provider

student.demographics:

  • Digitaal toetssysteem

student.accessability:

  • Nog geen afnemers

student.deliveryaddress:

  • Bestelomgeving leermiddelen

Endpoints

Administratiesysteem onderwijsdeelnemer

  • POST Search Student

  • GET Student

  • GET Students for School

Notifications

De Notifications API kan gebruikt worden om als afnemer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd). Hiervoor dient zowel de bron als de afnemer dan de Berichteninfrastructuur en de Notifications API te hebben geïmplementeerd.

Object: Student (Onderwijsdeelnemer)

Het object Student beschrijft de identifiers, de namen van de onderwijsdeelnemer en overige kenmerken. Dit object is beschikbaar vanuit de scope student.basic.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

userMasterIdentifier

string

string

De primaire identifier voor de onderwijsmedewerker.

https://ketenid.nl/201703/1a5c9c7203901866532c2d72ce056e1d29cacc70836fe2bc3a517f3f9a53eed3d77ef370ad6dcf80b3f34ced1c547c7d2e679e8e47002355f938213b3656b206

V*

De werkingsregels is dat de primaire identifier wordt gehanteerd in het object.

De primaire identifier voor onderwijsdeelnemer is het ECKiD.

In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.

userIds

array

userId

Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.

[{userId: ‘pietjepukkelen@petteflatcollege', userIdType: 'nlEduPersonRealId’}]

Zie referentie naar eindgebruiker

V*

Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd.

Zie de pagina Identiteiten voor de toegestane secundaire identifiers.

givenName

string

string

De voornaam of voornamen van de onderwijsdeelnemer

 

V

 

preferredFirstName

string

string

De roepnaam van de onderwijsdeelnemer

 

V

 

familyName

string

string

De achternaam van de onderwijsdeelnemer

 

V

 

familyNamePrefix

string

string

Het tussenvoegsel uit de achternaam van de onderwijsdeelnemer

 

O

 

sourceId

string

string

Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsdeelnemer en binnen dit systeem uniek is.

 

V

De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie.

Deze identifier is betekenisloos en daarmee geen persoonsgegeven.

status

string

ENUM

De status van dit object.

active
tobedeleted

V

De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit is aangemaakt

2017-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2022-08-11T15:31:12Z

V

 

Attributen: StudentDemographics

De StudentDemographics attributen bevatten demografische gegevens over de onderwijsdeelnemer. Dit object is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.demographics.

Attribuut geslacht wordt in de basis niet gedeeld

Het attribuut gender wordt alleen gedeeld met gegevensafnemers die hier een strikte noodzaak toe hebben. In de huidige configuratie van verplichte en optionele gegevensdiensten heeft enkel het Digitaal toetssysteem het recht om dit attribuut te ontvangen.

Echter niet alle applicaties die deze referentiecomponent implementeren zullen het geslacht nodig hebben. Het geslacht wordt dan ook alleen gedeeld met de applicaties die hier aantoonbaar een verwerkingsgrondslag voor hebben en deze hebben opgenomen in hun verwerkersovereenkomst. Een voorbeeld van een verwerkersgrondslag is de itemanalyse die uitgevoerd wordt als deelstap in het bepalen en vaststellen van een landelijke normering.

In de doorontwikkeling van de praktijksituatie Toetsen en Examineren zullen de referentiecomponenten worden herzien. Dit kan ertoe leiden dat de referentiecomponent Digitaal toetssyteem wordt gesplitst in bijvoorbeeld een afnameomgeving, rapportageomgeving en analyseomgeving. Dit geeft de mogelijkheid om het de demografische gegevens (waaronder geslacht) expliciet toe te wijzen aan de referentiecomponent die de gegevens ook daadwerkelijk nodig heeft.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

gender

string

ENUm

Geslacht van de onderwijsdeelnemer. Er wordt een ENUM gehanteerd:

  • female

  • male

  • other

  • unspecified

unspecified

O

unspecified wordt gekozen indien de data niet beschikbaar is.

other wordt gekozen indien het geslacht wel bekend is maar geen female of male is.

dateOfBirth

string

date

Geboortedatum van de onderwijsdeelnemer.

2000-11-11

O

 

Attributen: StudentCommunication

De StudentCommunication attributen bevat het mailadres van de onderwijsdeelnemer bij de onderwijsaanbieder. Dit attribuut is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor dit attribuut. Voor dit attribuut geldt een separate scope student.communication.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

email

string

string

Het e-mailadres van de onderwijsdeelnemer zoals beschikbaar gesteld door de onderwijsaanbieder

student@school.nl

V

 

Attributen: StudentAccessibility

De StudentAccessibility attributen bevat de voorkeuren van de onderwijsdeelnemer op het vlak van toegankelijkheid en talen. Deze attributen zijn alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.accessibility.

Optioneel

Toegankelijkheid is een optioneel onderdeel van de Students API. Op basis van expliciete behoeften in ketenprocessen kunnen voorkeuren voor toegankelijkheid benut worden.

Er dient ook nader onderzocht te worden of toegankelijk op het niveau van een onderwijsdeelnemer zit of dat er ook een relatie is met een vak. Zodra dit laatste het geval is dan zal er ook gekeken moeten worden naar de Association API.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

language

string

string

De voorkeurstaal van de onderwijsdeelnemer.

nld

O

ISO369 set 3 waardes worden gehanteerd. Een voorbeeldlijst is beschikbaar op Wikipedia.

accessibility

array

AccessibilityPreference

Een voorkeur voor een toegankelijkheidsinstelling.

 

O

De voorkeuren worden gevuld op basis van de AfA of PnP voorkeuren zoals gedefineerd door 1EdTech.

In de YAML file is ter illustratie AdditionalTestingTime uitgewerkt.

Attributen: StudentDeliveryAddress

De StudentDeliveryAddress attributen bevat de adresgegevens van de onderwijsdeelnemers ten behoeve van de fijndistributie van fysieke leermiddelen. Deze attributen zijn alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.deliveryaddress.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

address

object

address

Het afleveradres waar de fysieke leermiddelen voor de onderwijsdeelnemer kunnen worden bezorgd.

Zie address

O

Zie Order API voor een uitwerking van het address object.

emailPrivate

string

string

Het persoonlijk e-mailadres van de onderwijsdeelnemer

 

O

 

emailsParents

array

string

Een lijst met e-mailadressen van de wettelijk vertegenwoordigers van de onderwijsdeelnemer

 

O

 

object address

Alle adresgegevens zijn samengevoegd in een blok. Dit adres kan in Nederland en ook in het buitenland zijn.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

street

string

string

Straatnaam van het adres

Rijnkade

V

 

houseNumber

integer

integer

Huisnummer

12

V

Huisnummer is verplicht.

houseNumberSuffix

string

string

Huisnummer toevoeging

a

O

Toevoeging is optioneel.

zipCode

string

string

Postcode

1000 AA

V

Waarde is bij een Nederlands adres volgens het patroon van 4 cijfers en 2 letters

city

string

string

De woonplaats

Arnhem

V

 

countryCode

string

string

Landcode

NL

O

Waarde is de Alpha-2 code (2 letters) uit de ISO 3166 standaard dat correspondeert met het land zoals aangegeven door het veld Country

country

string

string

Het land van het adres van de leerling

Nederland

V

 

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