SIS API

Titel	SIS API
Status	DRAFT WERKGROEP KLANKBORDgroep ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.3
Datum	12 Juli 2023
Auteurs	Werkgroep Verwerven en in gebruik nemen Werkgroep Uitwisselen summatieve toetsresultaten
Acties	Geen acties

Via de SIS API kunnen Business rollen in het Ecosysteem beschikken over relevante informatie over de Onderwijsorganisatie.

De technische specificatie bestaat uit:

Samenvatting

Scopes	sis.school sis.student-teacher-group sis.student-delivery
Entiteiten	Student StudentDelivery Employee Class Group SchoolSubject SchoolPeriod
Producer	Administratiesysteemaanbieder – Administratiesysteem onderwijsdeelnemer
Consumer	Leermiddelenshop – Faciliteit voor leveren (of arrangeren) van digitale leermiddelen Leermiddelenaanbieder – Licentiekantoor Leermiddelenaanbieder – Educatieve software of Digitaal toetssysteem Leerportaalaanbieder – Mijn leermiddelen Leerportaalaanbieder – Learning Management System Dashboardaanbieder – Overkoepelend dashboard gebruik
Endpoints	Administratiesysteem onderwijsdeelnemer GET all Students from a School POST get a Student from a School by ID GET delivery information for all Students from a School POST get delivery information for a Student by ID GET all Employees from a School POST get an Employee from a School by ID GET all Classes from a School GET a Class from a School by ID GET all Groups from a School GET a Group from a School GET all SchoolSubjects from a School GET a SchoolSubject from a School by ID GET all SchoolPeriods from a School
Events API	De Events API kan gebruikt worden om als Consumer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd). Hiervoor dient zowel de Producer als de Consumer dan de Berichteninfrastructuur en de Events API te hebben geïmplementeerd. Berichteninfrastructuur voor het versturen en ontvangen van berichten Events API

Berichtdefinitie: SchoolPeriod (SchoolPeriode)

Het bericht SchoolPeriod wordt gebruikt om van een bepaalde Onderwijsorganisatie alle periodes uit te wisselen. Alleen het veld name is verplicht. Dit veld wordt gehanteerd om Students, Teachers, SchoolSubjects en Groups in een bepaalde periode uit te wisselen. Het is aan te raden om ook de startdatum en einddatum te vullen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
name	string	string	Naam van de schoolperiode	2021-2022 2022H1	V	Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
startDate	string	date	Startdatum van de schoolperiode	2022-08-01	O
endDate	string	date	Einddatum van de schoolperiode	2023-07-31	O

Berichtdefinitie: SchoolSubject (SchoolVak)

Via het SchoolSubject bericht wordt alle door de onderwijsorganisatie aangeboden SchoolVakken uitgewisseld. In de definitie van het bericht is uitgegaan van de combinatie tussen enerzijds de officiële vakcode vanuit het Minsiterie van OCW en anderzijds de vrijheid binnen scholen om eigen benamingen te kiezen voor het Vak.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolSubjectId	string	uuid	Unieke identifier voor dit schoolSubject	bd8e0494-168d-418f-8e01-1a58d9effd54	V	Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
subjectCode	string	string	Officiële vakcode voor het vak	0131	O	Conform vakcodes uit de officiële vakcodetabel van Ministerie van OCW Indien voor het vak een officiële vakcode beschikbaar is dan wordt deze gehanteerd. Deze code wijzigt niet meer, uitgezonderd foutcorrecties.
schoolSubjectAbbr	string	string	Door onderwijsorganisatie gehanteerde afkorting voor het vak	ak	V
schoolSubjectName	string	string	Door onderwijsorganisatie gehanteerde naam voor het vak	aardrijkskunde	V
schoolLevel	string	string	Door onderwijsorganisatie gehanteerd niveau voor het vak	HAVO-2	V
levels	array	levels	Een of meerdere niveaus en leerjaren waarop het Vak wordt gegeven.	Zie object levels	O	Dit kunnen er meerdere zijn in het geval van schoolLevel “Brugklas” of “Onderbouw” Indien voor het vak levelsbeschikbaar zijn dan worden deze toegevoegd. De levels wijzigen niet meer, uitgezonderd foutcorrecties.

object levels

Een SchoolVak bestaat uit de combinatie tussen Vak, Niveau en Leerjaar. Dit laatste niveau en leerjaar wordt gecombineerd in de array levels. De velden hierin zijn:

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
level	string	ENUM	Officieel niveau	VO-HAVO	V	Conform de officiële onderwijsniveaus.
levelYear	integer	integer	Het leerjaar dat gecombineerd wordt met het niveau.	1	V	Waarde 1-6

Voor level hanteren we een ENUM met de volgende officiële onderwijsniveaus (conform onderwijsniveaus van Dienst Uitvoering Onderwijs):

· BO: Basisonderwijs

· SO: Speciaal onderwijs

· SBO: Speciaal basisonderwijs

· VO-PRO: Praktijkonderwijs

· VO-VMBO-BB: Voorbereidend middelbaar beroepsonderwijs, basisberoepsgerichte leerweg

· VO-VMBO-KB: Voorbereidend middelbaar beroepsonderwijs, kaderberoepsgerichte leerweg

· VO-VMBO-GL: Voorbereidend middelbaar beroepsonderwijs, gemengde leerweg

· VO-VMBO-TL: Voorbereidend middelbaar beroepsonderwijs, theoretische leerweg

· VO-HAVO: Hoger algemeen voortgezet onderwijs

· VO-VWO: Voorbereidend wetenschappelijk onderwijs

· VSO: Voortgezet speciaal onderwijs

· MBO-Niveau-1: middelbaar beroepsonderwijs, niveau 1

· MBO-Niveau-2: middelbaar beroepsonderwijs, niveau 2

· MBO-Niveau-3: middelbaar beroepsonderwijs, niveau 3

· MBO-Niveau-4: middelbaar beroepsonderwijs, niveau 4

Berichtdefinitie: Student (Onderwijsdeelnemer)

In het Student bericht wordt alle relevante informatie over de opleiding, de stamklas en het vakkenpakket van de onderwijsdeelnemer in een bepaalde schoolperiode gedeeld. In dit bericht wordt geen informatie gedeeld over de lesgroepen waarin de onderwijsdeelnemer zich bevindt. Deze informatie wordt via het bericht Groups uitgewisseld.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer		V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden Waarde mag niet gewijzigd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie object userId	O*	Verplicht zodra eckId onbekend is. Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
firstName	string	string	Voornaam van de onderwijsdeelnemer	Jan	V
surname	string	string	Achternaam van de onderwijsdeelnemer	Wit	V
surnamePrefix	string	string	Tussenvoegsel van de onderwijsdeelnemer	de	O
schoolPeriod	string	string	Referentie naar schoolperiode voor deze onderwijsdeelnemer	2021-2022	V	Referentie naar schoolPeriod.name Waarde mag niet gewijzigd worden
school	object	school	De onderwijsorganisatie waar de onderwijsdeelnemer is ingeschreven	Zie object school	V	Waarde mag niet gewijzigd worden
study	object	study	De opleiding die de onderwijsdeelnemer volgt	Zie object study	V	Een onderwijsdeelnemer volgt slechts één opleiding.
schoolSubjects	array	school Subjects	Het vakkenpakket dat de onderwijsdeelnemer in de schoolperiode volgt.	Zie object schoolSubjects	O	Per schoolVak is de start- en einddatum aangegeven waarbinnen de onderwijsdeelnemer het vak volgt.

object userId

Zodra het ECK iD niet bekend is kan gebruik gemaakt worden van een alternatieve identifier voor een onderwijsdeelnemer. Op de pagina Identiteiten is hier meer informatie over te vinden. Bij het gebruiken van een alternatieve userId wordt verzocht om de gekozen variant mee te sturen. Hierbij hanteren we een additioneel veld UserIdType met de volgende opties:

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
userId	string	string	Het userId conform de specificatie van het userIdType	95312@1.kennisnet.nl	V
userIdType	string	ENUM	Het type userId dat gehanteerd wordt.	nlPersonProfileId nlPersonRealId Las-key Leerlingnummer	V	Conform de waardelijst voor userIdType

object school

Het object school bestaat uit de identifier van de onderwijsorganisatie en de naam van de onderwijsorganisatie. Op de pagina Identiteiten is meer informatie te vinden over de identifiers voor onderwijsorganisaties.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolId	string	digiDeliveryId	digiDeliveryId van de onderwijsorganisatie	22461075-07B8-4A17-AB18-71B8455AA7A3	V
schoolName	string	string	Naam van de onderwijsorganisatie	De Basisschool	V

object study

Een onderwijsdeelnemer is in een bepaalde schoolperiode ingeschreven voor een officiële opleiding. Deze opleiding wordt als attribuut van de onderwijsdeelnemer uitgewisseld. De velden van deze opleiding bestaan enerzijds uit de officiële opleidingscode en opleidingsnaam en anderzijds uit de naam zoals deze door de onderwijsorganisatie wordt gehanteerd. Deze specifieke afkortingen en namen worden uitgewisseld om zo herkenbaarheid voor de onderwijsorganisatie te behouden.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
studyCode	string	string	De officiële opleidingscode die verwijst naar een erkende opleiding.	0170	V	Waarde is elementcode uit de Elementcodetabel van Ministerie van OCW
studyName	string	string	De officiële naam van de opleiding die bepaald wordt door de opleidingscode	VWO-ATH prf Nat/Tech	V	Waarde uit de kolom ‘korte omschrijving’ dat correspondeert met de opleiding zoals aangegeven door de code
schoolStudyAbbr	string	string	Door de onderwijsorganisatie gehanteerde code of afkorting voor de opleiding	ATH_N&T	O
schoolStudyName	string	string	Door de onderwijsorganisatie gehanteerde naam voor de opleiding	VWO Natuur en Techniek	O
studyYear	string	ENUM	De jaargroep waarin de onderwijsdeelnemer zich bevindt	14	V	Conform waardelijst jaargroep, zie Tabel 39

waardelijst studyYear

Voor studyYear worden de volgende waarden gehanteerd:

Code	Betekenis	Opmerking voor toepassing
B	Baby’s, leeftijd 0 tot 12 maanden	Buiten scope van Ecosysteem
D	Dreumesen, leeftijd 1 tot 2 jaar	Buiten scope van Ecosysteem
0	PO groep 0	Toepassen bij regulier PO
1	PO groep 1	Toepassen bij regulier PO
2	PO groep 2	Toepassen bij regulier PO
3	PO groep 3	Toepassen bij regulier PO
4	PO groep 4	Toepassen bij regulier PO
5	PO groep 5	Toepassen bij regulier PO
6	PO groep 6	Toepassen bij regulier PO
7	PO groep 7	Toepassen bij regulier PO
8	PO groep 8	Toepassen bij regulier PO
S	S(B)O (speciaal (basis) onderwijs)	Toepassen bij S(B)O
11	VO leerjaar 1	Toepassen bij regulier VO
12	VO leerjaar 2	Toepassen bij regulier VO
13	VO leerjaar 3	Toepassen bij regulier VO
14	VO leerjaar 4	Toepassen bij regulier VO
15	VO leerjaar 5	Toepassen bij regulier VO
16	VO leerjaar 6	Toepassen bij regulier VO
V	VSO (voortgezet speciaal onderwijs	Toepassen bij VSO
21	MBO leerjaar 1	Toepassen bij MBO
22	MBO leerjaar 2	Toepassen bij MBO
23	MBO leerjaar 3	Toepassen bij MBO
24	MBO leerjaar 4	Toepassen bij MBO
N	Niet PO / VO	Buiten scope van Ecosysteem
C	Combinatiegroep cq heterogene groep	Buiten scope van Ecosysteem
H	Historisch	Buiten scope van Ecosysteem

object schoolSubjects

Tot slot volgt een onderwijsdeelnemer een aantal vakken. Deze vakken zijn opgenomen bij de onderwijsdeelnemer om zo voorbereid te zijn op individuele leerroutes voor onderwijsdeelnemer. In de berichtdefinitie hanteren we het schoolSubjectId dat verwijst naar de combinatie van het schoolVak en het niveau en leerjaar. In aanvulling hierop geven we de mogelijkheid om aan te geven vanaf welke startdatum en tot welke einddatum de onderwijsdeelnemer het vak volgt. Hierbij is de vullingsregel dat de start- en einddatum binnen de start- en einddatum van de schoolperiode vallen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolSubjectId	string	uuid	Referentie naar een SchoolSubject	bd8e0494-168d-418f-8e01-1a58d9effd54	V
startDate	string	date	Datum vanaf wanneer de onderwijsdeelnemer het vak volgt.	2022-08-01	V	Na startDate schoolPeriod en voor endDate schoolPeriod
endDate	string	date	Datum tot wanneer de onderwijsdeelnemer het vak volgt.	2023-07-31	O	Na startDate en voor endDate schoolPeriod Veld kan leeg blijven zodra er de onderwijsdeelnemer in de gehele schoolperiode het vak volgt.

Berichtdefinitie Employee (Onderwijsmedewerker)

In het Teacher bericht wordt alle relevante informatie over de onderwijsmedewerker in een bepaalde schoolperiode gedeeld. In dit bericht wordt geen informatie gedeeld over de lesgroepen waar de onderwijsmedewerker les aan geeft. Deze informatie wordt via het bericht Groups uitgewisseld.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
eckId	string	ECK iD	Het ECK iD van de onderwijsmedewerker		V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden Waarde mag niet gewijzigd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie object userId	O*	Verplicht zodra eckId onbekend is. Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
firstName	string	string	Voornaam van de onderwijsmedewerker	Jan	V
surname	string	string	Achternaam van de onderwijsmedewerker	Wit	V
surnamePrefix	string	string	Tussenvoegsel van de onderwijsmedewerker	de	O
role	string	ENUM	De rol van de onderwijsmedewerker	teacher administrator	V	De rollen die en onderwijsmedewerker kan hebben zijn nog in ontwikkeling. Voor meer informatie hierover zie ook Onderwijsorganisaties en actoren.
schoolPeriod	string	string	Referentie naar schoolperiode voor deze onderwijsmedewerker	2021-2022	V	Referentie naar schoolPeriod.name Waarde mag niet gewijzigd worden
school	object	school	De onderwijsorganisatie waar de onderwijsmedewerker onderwijs verzorgt	Zie object school	V	Waarde mag niet gewijzigd worden

Berichtdefinitie: Class (Stamklas of Stamgroep)

In het Class bericht worden de stamklassen (of stamgroepen) van een onderwijsorganisatie in een bepaalde schoolperiode uitgewisseld. Een Class bevat de combinatie van onderwijsdeelnemers en onderwijsmedewerkers. In de stamklas zijn de onderwijsdeelnemers organisatorisch ingedeeld. Dit staat los van de lesgroepen waarin een onderwijsdeelnemer een vak kan volgen. Deze lesgroepen worden uitgewisseld via een separaat bericht genaamd Group.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
classId	string	uuid	De unieke identifier van de Stamklas (of Stamgroep)		V	Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
className	string	string	Naam van de stamklas	Groep 3	V
schoolPeriod	string	string	Referentie naar schoolperiode voor deze stamklas	2021-2022	V	Referentie naar schoolPeriod.name Waarde mag niet gewijzigd worden
school	string	school	De onderwijsorganisatie van de stamklas	Zie object school	V	Waarde mag niet gewijzigd worden
students	array	student Reference	De onderwijsdeelnemers die in deze stamklas zijn ingedeeld.	Zie object studentReference	V
employees	array	employee Reference	De onderwijsmedewerkers die deze stamklas begeleiden	Zie object #employeeReference	V	In het voortgezet onderwijs kan dit bijvoorbeeld de Mentor van de stamklas zijn. In het primair onderwijs kunnen dit de leerkrachten zijn die les geven aan de leerlingen uit deze stamgroep.

object studentReference

De onderwijsdeelnemers zijn in een lijst opgenomen in het bericht. In deze lijst wordt enkel de verwijzing in de vorm van de identifier opgenomen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer		V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	zie object userId	O*	Verplicht zodra eckId onbekend is.

object employeeReference

De onderwijsmedewerkers zijn in een lijst opgenomen in het bericht. In deze lijst wordt enkel de verwijzing in de vorm van de identifier opgenomen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
eckId	string	ECK iD	Het ECK iD van de onderwijsmedewerker		V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	zie object userId	O*	Verplicht zodra eckId onbekend is.

Berichtdefinitie: Group (LesGroep)

In het Group bericht worden de lesgroepen van een onderwijsorganisatie in een bepaalde schoolperiode uitgewisseld. Een Group bevat de combinatie van onderwijsdeelnemers, onderwijsmedewerkers en vak(ken). In de lesgroepen wordt onderwijs verzorgt in het vak (of de vakken) door de onderwijsmedewerkers aan de onderwijsdeelnemers.

De werkingsregel is dat de onderwijsmedewerker die gekoppeld is aan de Group ook daadwerkelijk alle voortgang en resultaten van de onderwijsdeelnemers in het vak mag inzien. In de praktijk betekent dit het volgende:

Voor iedere lesgroep waarbij de samenstelling aan onderwijsdeelnemers verschilt wordt een nieuwe Group uitgewisseld.
Lesgroepen in het voortgezet onderwijs met dezelfde samenstelling aan leerlingen kunnen verschillende vakken volgen. Voor dit vak hebben ze veelal ook een andere docent. In dat geval wordt voor iedere unieke combinatie van leerlingen, vak en docent een nieuwe Group uitgewisseld.
Een leerling in het voortgezet onderwijs zit vaak ook in een Stamklas. De stamklas wordt niet uitgewisseld via het bericht Group. De Stamklas is een separaat bericht genaamd Class.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
groupId	string	uuid	De unieke identifier van de SchoolLesGroep		V	Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
groupName	string	string	Naam van de lesgroep	A4bBiol	V
schoolPeriod	string	string	Referentie naar schoolperiode voor deze lesgroep	2021-2022	V	Referentie naar schoolPeriod.name Waarde mag niet gewijzigd worden
school	string	school	De onderwijsorganisatie van de groep	Zie object school	V	Waarde mag niet gewijzigd worden
students	array	student Reference	De onderwijsdeelnemers die in deze lesgroep les krijgen in de vakken.	Zie object studentReference	V
employees	array	employee Reference	De onderwijsmedewerkers die onderwijs verzorgen in deze lesgroep	Zie object employeeReference	V	De onderwijsmedewerkers zijn allen ingeroosterd om de vakken te onderwijzen aan de onderwijsdeelnemers.
subjects	array	subjects	De vakken die worden onderwezen in de lesgroep.	Zie object subjects	O	Zie werkingsregel boven tabel

object subjects

In het Group bericht kunnen optioneel vakken worden toegevoegd. De vullingsregel is om deze vakken indien bekend altijd te vullen. In deze vakken is de officiële vakcode niet verplicht. Hierdoor kunnen ook lesgroepen uitgewisseld van vakken die niet gerelateerd zijn aan een officieel vak, zoals bijvoorbeeld de mentorles.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
subjectCode	string	string	Officiële vakcode voor het vak	0131	O	Conform vakcodes uit de officiële vakcodetabel van Ministerie van OCW
schoolSubjectAbbr	string	string	Door onderwijsorganisatie gehanteerde afkorting voor het vak	ak	V
schoolSubjectName	string	string	Door onderwijsorganisatie gehanteerde naam voor het vak	aardrijkskunde	V

Berichtdefinitie StudentDelivery (Adresgegevens voor fijndistributie)

In aanvulling op de algemene gegevens van de onderwijsdeelnemer (zoals uitgewisseld in het bericht Student), dient in het geval van fijndistributie de Leermiddelenshop met de referentiecomponent Distributiefaciliteit voor leveren fysieke leermiddelen aanvullende adres- en contactgegevens van de Onderwijsdeelnemer te verkrijgen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
eckId	string	ECK iD	Het ECK iD van de onderwijsdeelnemer		V*	eckId is verplicht. Indien onbekend dan kan userId gehanteerd worden Waarde mag niet gewijzigd worden
userId	array	userId	Alternatief userId indien eckId onbekend is	Zie Tabel 35	O*	Verplicht zodra eckId onbekend is. Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
dateOfBirth	string	date	Geboortedatum van de onderwijsdeelnemer	2005-05-05	V
gender	string	ENUM	Geslacht van de onderwijsdeelnemer	0	V	Dit volgt de codering conform de codelijst gender
address	object	address	Specificeert de exacte adressering van de onderwijsdeelnemer	Zie object address	V	Een onderwijsdeelnemer heeft 1 adres.
emailSchool	string	email	E-mailadres van de onderwijsdeelnemer zoals verstrekt door de onderwijsorganisatie	leerling@ onderwijs.nl	V*	Dit gegeven is verplicht als het gegeven emailPrivate ontbreekt omdat minimaal 1 e-mailadres van de onderwijsdeelnemer verplicht is.
emailPrivate	string	email	Privé e-mailadres van de onderwijsdeelnemer	leerling@ prive.nl	V*	Zie emailSchool.
emailParents	array	emailParent	Blok met e-mailadressen van de ouders en verzorgers.	Zie object emailParent	O	Emailadressen worden in een blok toegevoegd. Dit geeft de vrijheid om meerdere emailadressen uit te wisselen.

codelijst gender

Voor Gender wordt de volgende codelijst gehanteerd:

0: Onbekend
1: Jongen/Man
2: Meisje/Vrouw
X: Genderneutraal
9: Ontbrekend

object address

Alle adresgegevens zijn samengevoegd in een blok. De onderwijsdeelnemer beschikt over 1 compleet adres dat door de Faciliteit voor distribueren fysieke leermiddelen gebruikt kan worden voor het leveren van de leermiddelen. 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	string	string	Huisnummer inclusief toevoeging	12	V	Huisnummer is verplicht. 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

object emailParent

De emailaddressen van de ouders/verzorgers zijn samengevoegd in een blok. Dit geeft de flexibiliteit om meerdere emailadressen toe te voegen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
emailParent	string	email	E-mailadres van een Ouder/Verzorger	ouder@thuis.nl	V

Event processor: Leerportaalaanbieder (Mijn leermiddelen)

Er zijn specifieke regels voor het verwerken van wijzigingen van entiteiten door de component Mijn Leermiddelen van de Leerportaalaanbieder. Het betreft de entiteiten:

Student
Group

Een wijziging in het Student en het Group bericht kan ertoe leiden dat een Onderwijsdeelnemer aanspraak kan maken op een Leermiddel. In dat geval moet de Toegangslink worden toegevoegd aan of verwijderd uit het overzicht van Leermiddelen van de Onderwijsdeelnemer.

Bericht	Wijziging		Verwerking door Leerportaalaanbieder
Student	Alle velden	Nieuw	Voor iedere nieuwe Student wordt voor ieder SchoolSubject uit het vakkenpakket van deze onderwijsdeelnemer (SchoolSubjects) gekeken of de school voor dit SchoolSubject een aanspraak heeft verworven. Indien dit het geval is wordt de toegangslink voor deze onderwijsdeelnemer beschikbaar gemaakt in de activatie- en gebruiksperiode.
Student	SchoolSubject	Nieuw	Zodra bij een Student een nieuw SchoolSubject gaat volgen wordt gekeken of de onderwijsorganisatie voor dit SchoolSubject een aanspraak heeft verworven. Indien dit het geval is wordt de toegangslink voor deze onderwijsdeelnemer beschikbaar gesteld in de activatie- en gebruiksperiode
Student	SchoolSubject	Verwijderd	Zodra bij een Student een SchoolSubject wordt verwijderd dan wordt gekeken of de Student op basis van het SchoolSubject een toegangslink heeft in zijn overzicht van leermiddelen. Indien de Student het bijbehorende leermiddel nog niet in gebruik heeft genomen dan wordt de toegangslink verwijderd uit het overzicht van leermiddelen van de onderwijsdeelnemer. Indien de Student het bijbehorende leermiddel al wel in gebruik heeft genomen dan is er geen voorgeschreven gedrag voor het LMS. De Student mag het leermiddel blijven gebruiken. Een mogelijke oplossing is om de toegangslink voor de Student te archiveren aangezien deze niet meer relevant is voor de onderwijsdeelnemer.
Group	Students	Nieuw	Zodra er een Student wordt toegevoegd aan een Group dan wordt er gekeken of de onderwijsorganisatie voor deze Group een SchoolGroup aanspraak heeft verworven. Indien dit het geval is wordt de toegangslink voor deze onderwijsdeelnemer beschikbaar gemaakt in de activatie- en gebruiksperiode.
Group	Students	Verwijderd	Zodra er een Student wordt verwijderd uit een Group dan wordt er gekeken of de Student een toegangslink heeft op basis van een SchoolGroup aanspraak. Indien de Student het bijbehorende leermiddel nog niet in gebruik heeft genomen dan wordt de toegangslink verwijderd uit het overzicht van leermiddelen van de onderwijsdeelnemer. Indien de Student het bijbehorende leermiddel al wel in gebruik heeft genomen dan is er geen voorgeschreven gedrag voor het LMS. De Student mag het leermiddel blijven gebruiken. Een mogelijke oplossing is om de toegangslink voor de Student te archiveren aangezien deze niet meer relevant is voor de onderwijsdeelnemer.

Status- en foutcodes

Status code	Status	statusMessage	Toelichting
200	0	OK	Verzoek succesvol verwerkt
400	1	schema validation unsuccessful	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gevraagde SchemaVersion niet aanbieden.
401	3	scope required	Client is niet geautoriseerd voor scope.
403	4	consent required	De gegevenssoort is van classificatie II of IV. Dit vereist een activering van de gegevensuitwisseling. Dit is in dit foutscenario niet het geval.
403	5	edu_org_id unknown	De Verzender communiceert in de context van een Onderwijsorganisatie die niet bekend is bij Ontvanger.
404	6	School unknown	De identifier van de onderwijsorganisatie is onbekend.
404	7	Student unknown	De identifier van de onderwijsdeelnemer is onbekend.
404	8	Employee unknown	De identifier van de onderwijsmedewerker is onbekend.
404	9	Class unknown	De identifier van de stamklas of stamgroep is onbekend.
404	10	Group unknown	De identifier van de lesgroep is onbekend.
404	11	SchoolSubject unknown	De identifier van het SchoolVak is onbekend.
404	12	SchoolPeriod unknown	De schoolperiode is onbekend.
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

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:
- GET all endpoints zijn toegevoegd voor alle objecten.
- Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van het activeren en deactiveren van gegevensuitwisselingen en de M2M identificatie en authenticatie.
- Bericht Teacher is hernoemd naar Employee inclusief het attribuut role. In dezelfde lijn is ook teacherReference hernoemd naar employeeReference
- De waardelijst studyYear is verduidelijkt.
- Het attribuut class van de Student is een separaat bericht geworden inclusief employees.
- De status- en foutcodes zijn toegevoegd aan de documentatie en de YAML.
- In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
- De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.