Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Titel

Association API

Status

Status
titleIn ontwikkeling
Status
titleROSA-Architectuurscan
Status
titleBEsluitvorming
Status
colourYellow
titleimplementatie
Status
titlein beheer

Versie

Documentatie: 0.9.12

schemaVersion: 0.9.12

Datum27 September 2024

7 maart 2025

AuteursArchitectenraad

Edu-VWerkgroep Administratiesystemen

Acties

  • Review en doorontwikkeling op basis van input LAS leveranciers

...

Gegevensdienst

Onderwijsinrichting

Scopes

  • eduv.association

Entiteiten

Bron

Administratiesysteem onderwijsdeelnemer

Afnemer

  • Bestelomgeving leermiddelen

  • Aanspraakmanager

  • Identitietsbeheervoorziening

Endpoints

Administratiesysteem onderwijsdeelnemer

  • GET SchoolPeriod

  • GET SchoolPeriods for School

  • GET Enrollment

  • GET Enrollments for School

  • POST Get Enrollments for Student at School

  • GET Assignment

  • GET Assignments for School

  • POST Get Assignments for Employee at School

  • GET Group

  • GET Group 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.

...

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

schoolPeriodId

stringstring

uuid

Een unieke identifier voor het object

V

title

string

string

Naam van de schoolperiode

2021-2022

2022H1

V

type

string

ENUM

Het type schoolperiode. Hierbij wordt een ENUM gehanteerd bestaande uit:

  • gradingPeriod

  • schoolYear

  • semester

  • term

schoolYear

O

De waardelijst is overgenomen vanuit OneRoster voor SessionType van een AcademicSession.

superSchoolPeriod

string

string

Een referentie naar een bovenliggend SchoolPeriod object.

O

De superSchoolPeriod van een semester is bijvoorbeeld het schoolYear

subSchoolPeriod

array

string

Referenties naar onderliggende SchoolPeriod objecten.

O

De subSchoolPeriods van een schoolYear zijn bijvoorbeeld de semesters

startDate

string

date

Startdatum van de schoolperiode

2022-08-01

V

 

endDate

string

date

Einddatum van de schoolperiode

2023-07-31

V

 

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

...

objectEen referentie naar een string AangebodenVak (SubjectOffering) object waarop de onderwijsdeelnemer is ingeschreven.V* subjectOfferingIdVerplicht subject schoolPeriod

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

enrollmentId

stringstring

uuid

Een unieke identifier voor het object

Vstudent

organisationId

string

UserReference

uuid

De unieke identifier van de Onderwijsaanbieder (Organisation) die gegenereerd is door het Administratiesysteem onderwijsdeelnemer.

Zie referentie Eindgebruiker

V*

enrollmentType

string

Verwijzing naar sourceId.

Verplicht indien het enrollmentType school betreft.

student

object

UserReference

Een referentie naar een onderwijsdeelnemer.

Zie referentie Eindgebruiker

V

enrollmentType

string

ENUM

Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit:

  • study

  • subject

  • school

study

V

Inschrijvingen op AangebodenOpleidingen worden minimaal beschikbaar gesteld.

De vullingsregels voor inschrijvingen op vakken moet nog bepaald worden.

study

stringstring

uuid

Een referentie naar een AangebodenOpleiding (StudyOffering) object waarop de onderwijsdeelnemer is ingeschreven.

V*

Verwijzing naar studyOfferingId

Verplicht indien het enrollmentType study betreft.subject

studyPublicId

string

uuid

Een referentie naar een

AangebodenOpleiding in RIO.

O

Verwijzing naar

id in RIO.

studyYear

integer

integer

Het opleidingsjaar waarop deze Inschrijving van toepassing is.

1

V*

Verplicht indien het enrollmentType

study of school betreft.

location

object

LocationReference

De locatie van de AangebodenOpleiding waar de Onderwijsdeelnemer op is ingeschreven.

Zie LocationReference

O

subject

stringstring

uuid

Een referentie naar een Schoolperiode AangebodenVak (SchoolPeriodSubjectOffering) object waarbinnen de waarop de onderwijsdeelnemer is ingeschreven.

V*

Verwijzing naar subjectOfferingId

Verplicht indien het enrollmentType subject betreft.

schoolPeriod

string

uuid

Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.

V

Verwijzing naar schoolPeriodId

Waarde mag niet gewijzigd worden

beginDate

string

date

Begindatum van de inschrijving

2022-08-01

V

De begindatum van de inschrijving kan afwijken van de startdatum van de schoolperiode.

endDate

string

date

Einddatum van de inschrijving

2023-07-31

O

De einddatum is een verplicht veld indien de inschrijving eerder afloopt dan de schoolperiode.

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

Anchor

...

locationreference

...

locationreference
Object:

...

referentie Locatie

Een referentie naar een locatie bevat de primaire identifier (eerste voorkeur) en indien deze niet beschikbaar is door een uitzonderingssituatie een secundaire identifier.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

assignmentId

locationMasterIdentifier

string

string

Een unieke

De primaire identifier voor

het object

V

employee

object

UserReference

Een referentie naar een onderwijsmedewerker.

Zie referentie Eindgebruiker

V

assignmentType

string

ENUM

Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit:

  • class-teacher

  • teacher

  • coach

teacher

V

een locatie.

112X995

V*

De werkingsregels is dat de primaire identifier wordt gehanteerd in de berichten.

De primaire identifier voor locatie is de onderwijslocatie (OL_CODE).

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

locationIds

array

locationId

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

[{“locationId”: “string”, “locationIdType”: “VE_CODE”}]

V*

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

De secundaire identifier voor locatie is de vestigingserkenning (VE_CODE).

name

string

string

Naam behorende bij de locatie.

V

Anchor
assignment
assignment
Object: Assignment (Toewijzing)

Het object Assignment beschrijft de toewijzing van een onderwijsmedewerker aan een groep of individu voor een schoolperiode op een onderwijsaanbieder.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

assignmentId

string

string

Een unieke identifier voor het object

V

employee

object

UserReference

Een referentie naar een onderwijsmedewerker.

Zie referentie Eindgebruiker

V

assignmentType

string

ENUM

Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit:

  • class-teacher

  • teacher

  • coach

teacher

V

Het toewijzingstype betreft één van:

  • Klassendocent (in het primair onderwijs ook wel leerkracht en in het voortgezet onderwijs mentor)

  • Vakdocent (in het primair onderwijs ook wel leerkracht voor een vak en in het voortgezet onderwijs de vakdocent)

  • Begeleider (in het primair onderwijs de individueel begeleider van een leerling en in het voortgezet onderwijs bijvoorbeeld de persoonlijke mentor)

group

string

string

Een referentie naar een Groep (Group) object waar de onderwijsmedewerker aan is toegewezen.

V*

Verwijzing naar groupId

Verplicht indien het assignmentType class-teacher of teacher betreft.

subject

string

string

Een referentie naar een AangebodenVak (SubjectOffering) object dat wordt onderwezen in de groep

V*

Verwijzing naar subjectOfferingId

Dit is een verplicht veld indien het assignmentType teacher betreft én de onderwijsmedewerker voor een enkel AangebodenVak toegewezen is aan de groep.

student

string

UserReference

Een referentie naar een onderwijsdeelnemer waar de onderwijsmedewerker aan is toegewezen.

Zie referentie Eindgebruiker

V*

Verplicht indien het assignmentType coach betreft.

schoolPeriod

string

string

Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.

V

Verwijzing naar schoolPeriodId

Waarde mag niet gewijzigd worden

beginDate

string

date

Begindatum van de toewijzing

2022-08-01

V

De begindatum van de toewijzing kan afwijken van de startdatum van de schoolperiode.

endDate

string

date

Einddatum van de toewijzing

2023-07-31

O

De einddatum is een verplicht veld indien de toewijzing eerder afloopt dan de schoolperiode.

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

...

  • 0.0.1: De Association 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 Association 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: Rostering API is hernoemd naar Association API. De informatie in de objecten Inschrijving, Toewijzing en Groep zijn gewijzigd:

    • Het AangebodenVak is gekoppeld aan de toewijzing en verwijderd uit de groep.

    • De groep is enkel de samenstelling van onderwijsdeelnemers en de toewijzingen vanuit onderwijsmedewerkers.

    • De toewijzingsrol is verwijderd en verwerkt in het toewijzingstype. Dit is aangepast naar klassendocent, docent en begeleider.

  • 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:

      • De documentatie van het Groep object en de YAML kwamen niet overeen.

  • 0.0.5: Typo’s in de YAML.

  • 0.0.6: / verwijderd aan einde van endpoints.

  • 0.0.7: de attributen children en parent van het object SchoolPeriod zijn hernoemd naar respectievelijksubSchoolPeriods en superSchoolPeriod. Dit wijkt af van OneRoster maar voorkomt semantische misverstanden over ouders en kinderen. Op deze manier is het duidelijk dat het gaat om hiërarchische relaties tussen SchoolPeriod objecten. Ook zijn de vullingsregels voor het opnemen van students in het Group object duidelijker gespecificeerd.

  • 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.De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatieafsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.

    • De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.

  • 0.9.2: Wijzigingen naar aanleiding van RFC’s:

    • Op basis van RFC0031 zijn attributen studyYear, location en studyPublicId aan het Enrollment object toegevoegd.

    • Op basic van RFC0039 is de mogelijkheid om in te schrijven op een School toegevoegd; enrollmentType school. Hiervoor is het attribuut organisationId in het Enrollment object opgenomen.