Education API

Titel	Education API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 0.9.2
Versie	schemaVersion: 0.9.2
Datum	15 Oktober 2024
Auteurs	Architectenraad Edu-V
Acties	Review en doorontwikkeling op basis van input LAS leveranciers

De Education API wordt gebruikt om informatie over aangeboden opleidingen en vakken uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsaanbod 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:

1 Samenvatting
2 Object: Organisation (Onderwijsaanbieder)
3 Object: StudyOffering (AangebodenOpleiding)
4 Object: SubjectOffering (AangebodenVak)
5 Status- en foutcodes
6 Technisch: API specificatie
7 Release notes

Samenvatting

Gegevensdienst	Onderwijsaanbod
Scopes	eduv.education
Objecten	Organisation StudyOffering SubjectOffering
Bron	Administratiesysteem onderwijsdeelnemer
Afnemer	Selectieomgeving leermiddelen Bestelomgeving leermiddelen Aanspraakmanager Leermiddelenportaal Onderwijsleeromgeving Leermiddelendashboard Identiteitsbeheervoorziening
Endpoints	Administratiesysteem onderwijsdeelnemer GET Organisation GET Organisations GET StudyOffering GET StudyOfferings for School GET SubjectOffering GET SubjectOfferings 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. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Object: Organisation (Onderwijsaanbieder)

Het object Organisation beschrijft een onderwijsaanbieder die als administratieve eenheid beschikbaar is in het Administratiesysteem onderwijsdeelnemer.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
organisation MasterIdentifier	string	string	De primaire identifier voor een onderwijsaanbieder.	104A158	V*	De werkingsregels is dat de primaire identifier wordt gehanteerd in het object. De primaire identifier voor onderwijsaanbieders is de OnderwijsaanbiederCode. In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.
organisationIds	array	organisationId	Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.	[{organisationId: ‘09QQ00', organisationIdType: 'Vestigingserkenning’}]	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.
name	string	string	De naam van de onderwijsaanbieder	Marienbornschool	V
boards	array	BoardReference	Referenties naar de onderwijsbesturen waaronder deze onderwijsaanbieder valt.	Zie referentie naar onderwijsorganisatie	O
locations	array	LocationReference	Referentie naar de onderwijslocaties waar deze onderwijsaanbieder onderwijs aanbiedt.	Zie referentie naar onderwijsorganisatie	O
sourceId	string	string	Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsdeelnemer.		V	De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie.
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

Object: StudyOffering (AangebodenOpleiding)

Het object StudyOffering beschrijft de opleidingen op basis van de opleidingseenheden in combinatie met het leerjaar aangeboden door de onderwijsaanbieder. In het object worden verwijzingen gemaakt naar de waardelijsten die onder beheer zijn van de werkgroep Waardelijsten RIO.

*Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
studyOfferingId	string	uuid	Een unieke identifier voor het object		V
studyOfferingName	string	string	De naam die de onderwijsaanbieder heeft gegeven aan deze AangebodenOpleiding.	Gymnasium brugklas	V
studyName	string	string	De opleidingseenheid korte naam erkende opleiding die van toepassing is op deze AangebodenOpleiding.	vwo-gymnasium-onderbouw basisonderwijs	V*	Indien de AangebodenOpleiding erkend is dan is dit veld verplicht. Werkingsregel is om per sector de volgende waardelijsten te gebruiken: Primair onderwijs: po-opleidingseenheden korte naam conform erkende opleiding in waardelijst RIO po Voortgezet onderwijs: vo-opleidingseenheden korte naam conform erkende opleiding in waardelijst RIO vo
studyCode	string	string	De opleidingseenheidcode (po en vo) van de AangebodenOpleiding,	1002O0222 1000O0001	V*	Indien de AangebodenOpleiding erkend is dan is dit veld verplicht. Werkingsregel is om per sector de volgende waardelijsten te gebruiken: Primair onderwijs: erkendeopleidingscode conform waardelijst RIO po Voortgezet onderwijs: erkendeopleidingscode conform waardelijst RIO vo
studyCharacteristics	array	string	De opleidingskenmerken van deze AangebodenOpleiding.	VERRIJKT_PROGRAMMA_VWO PILOT_TPO CULTUURPROFIEL_PO HBGO	O	Werkingsregel is om per sector de volgende waardelijsten te gebruiken: Primair onderwijs: po-opleidingskenmerken conform waardelijst RIO po Voortgezet onderwijs: vo-opleidingskenmerken conform waardelijst RIO vo
studyLevel	object	StudyLevel	Het onderwijsniveau van deze AangebodenOpleiding.	Zie StudyLevel object	O	Formaat conform het Niveau van SLO. Voor meer informatie zie Waardelijst onderwijsniveaus en leerjaren.
studyYear	integer	integer	Het opleidingsjaar van deze AangebodenOpleiding	1	O	Dit attribuut specificeert het jaar van de opleiding. Bijvoorbeeld: Basisonderwijs: 0, 1, 2, 3, 4, 5, 6, 7 of 8 VMBO: 0, 1, 2, 3 of 4 HAVO: 0, 1, 2, 3, 4 of 5 VWO: 0, 1, 2, 3, 4, 5 of 6 Het gespecialiseerd onderwijs kan optioneel gebruik maken van dit attribuut. Uit het studyLevel valt op te maken dat de opleiding van het niveau speciaal onderwijs of voortgezet speciaal onderwijs is.
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

Object: SubjectOffering (AangebodenVak)

Het object SubjectOffering beschrijft de vakken aangeboden door de onderwijsaanbieder. In het object worden verwijzingen gemaakt naar de waardelijsten die onder beheer zijn van de werkgroep Waardelijsten RIO.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
subjecOfferingtId	string	uuid	Een unieke identifier voor het object		V
subjectOfferingName	string	string	De naam die de onderwijsaanbieder heeft gegeven aan dit vak.	Cambridge Engels	V
subjectOfferingAbbr	string	string	De afkorting voor dit vak	en	O
subjectCode	string	string	De vakcode voor dit vak.		V*	Indien het vak onderdeel is van het curriculum uit een opleiding dan is dit veld verplicht. Er vindt overleg plaats met de werkgroep Waardelijsten RIO voor het opstellen van een lijst met vakcodes voor veelvoorkomende vakken in het po en vo.
studyOfferings	array	string	Een referentie naar de AangebodenOpleiding (StudyOffering) objecten waar dit AangebodenVak onder valt.		V*	Verwijzing naar studyOfferingId Indien het vak onderdeel is van het curriculum uit een opleiding dan is dit veld verplicht.
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

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: De Rostering API was voorheen een onderdeel van de SIS API. Hierin waren de volgende wijzingen gedaan:
- 0.0.1: Eerste draft van de API.
- 0.0.2: Objecten 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 regie op gegevens en de M2M identificatie en authenticatie.
  - Object 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 object 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.
- 0.0.4: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.
- 0.0.5: Terminologie in YAML bijgewerkt.
- 0.0.6: Gegevensdiensten van SIS API opgesplitst in:
  - Onderwijsorganisatie
  - Adresgegevens fijndistributie
  - Onderwijsaanbod
0.0.2: De Education API is opgesteld op basis van een herziening van de SIS API. In deze herziening is aansluiting gezocht bij de best practices uit bestaande standaarden en een uiteenzetting van ontwerpeisen vanuit de flexibilisering van het onderwijs.
0.0.3: De benamingen zijn gewijzigd naar StudyOffering en SubjectOffering.
0.0.4: De volgende wijzigingen zijn gedaan:
- Wijzigingen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de objecten.
  - Query parameter schemaVersion is verwijderd uit de koppelvlakken.
  - Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
  - Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
- Wijzigingen in de documentatie en de YAML:
  - Objecten in documentatie en YAML gecontroleerd.
  - studyLevel gewijzigd naar het object studyLevel zoals gespecificeerd in de waardelijst onderwijsniveaus en leerjaren.
0.0.5: Query parameter name toegevoegd aan GET organisations om zoeken van organisaties op naam mogelijk te maken.
0.0.6: StudyAbbr attribuut verwijderd uit de StudyOffering object.
0.0.7: studyCharacteristics attribuut van StudyOffering verandert in een array. Pattern voor studyCode verwijderd uit de YAML. De studyCode kan verschillende vormen hebben in RIO.
0.0.8: Het attribuut studyYears (array) is vervangen door het attribuut studyYear (enkele waarde). Een eerder wijzigingsvoorstel is ingetrokken en weer teruggebracht naar de eerdere versie.
0.0.9: Toelichting op opleidingsjaar (studyYear) aangepast in de tabel en in de YAML.
0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.
0.9.1: Wijzigingen naar aanleiding van RFC’s:
- Op basis van RFC002 is de scope aangepast met een prefix eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.
- De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.
- In de documentatie bij het attribuut studyYear van het object StudyOffering in de documentatie voor de volledigheid ook leerjaar 0 toegevoegd.
- De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.
0.9.2: Wijziging naar aanleiding van RFC:
- Op basis van RFC019 is in het StudyOffering object voor het attribuut studyCode de verwerkingsregel gewijzigd. Hierbij wordt de opleidingseenheidcode gehanteerd. en niet langer de erkendeopleidingscode. Op deze manier is de code uniek en persistent over sectoren heen.
- Op basis van RFC019 zijn de voorbeelden in het StudyOffering object voor het attribuut studyCharacteristics verduidelijkt met karakteristieken die van toepassing kunnen zijn op een opleiding.