Page Comparison

Titel

Employees API

Status

colour	Purple
title	In ontwikkeling

Status

title	BEsluitvorming

Status

title	in beheer

Versie

Documentatie: 0.0.23

schemaVersion: 0.0.3

Datum

15 maart 2024

Auteurs

Architectenraad Edu-V

Acties

Review en doorontwikkeling op basis van input LAS leveranciers

...

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
userMasterIdentifier	string	string	De primaire identifier voor de onderwijsmedewerker.		V*	De werkingsregels is dat de primaire identifier wordt gehanteerd in de berichten. Er is nog geen primaire identifier voor onderwijsmedewerkers. Enkel secundaire identifiers worden gehanteerd. 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.
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	0.0.2	V	Conform Semantic Versioning 2.0.0
givenName	string	string	De voornaam van de onderwijsmedewerker		V
familyName	string	string	De achternaam van de onderwijsmedewerker		V
familyNamePrefix	string	string	Het tussenvoegsel uit de achternaam van de onderwijsmedewerker		V
sourceId	string	uuid	Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsmedewerker 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 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

...

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
sourceId	string	uuid	De referentie naar het sourceID van de onderwijsmedewerker.		V	Er is in dit bericht bewust gekozen voor het sourceID om op deze manier een betekenisloze identifier te hebben in de uitwisseling.	schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	0.0.2
V	Conform Semantic Versioning 2.0.0	email	string	string	Het e-mailadres van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder	employee@school.nl	V
phone	string	string	Het vaste telefoonnummer van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder	010-1234567	O
mobile	string	string	Het mobiele telefoonnummer van de onderwijsmedewerker zoals beschikbaar gesteld door de onderwijsaanbieder	06-12345678	O

...

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

sourceId

string

uuid

De referentie naar het sourceID van de onderwijsdeelnemer.

V

Er is in dit bericht bewust gekozen voor het sourceID om op deze manier een betekenisloze identifier te hebben in de uitwisseling.

schemaVersion

string

Het versienummer van de berichtdefinitie die wordt gehanteerd.

0.0.2

V

Conform Semantic Versioning 2.0.0

organisationRoles

array

organisationRole

Een lijst met organisatierollen die de onderwijsmedewerker vervult bij onderwijsaanbieders.

V

...

Open api

filter	none
supportedSubmitMethods	none
showDownloadButton	true

openapi: 3.0.0
info:
  title: Employees API
  version: '0.0.23'
  description: |-
    The Employees API is implemented by the `Administratiesysteem onderwijsmedewerker`.
    
    Employee data is split into the following objects with corresponding attributes:
    - Basic data: identifiers and name
    - Communication: email, phone, and mobile
    - Roles: organisation roles of the employee within the school
    
    Not all Employee attributes are available to all consuming reference components.
    All objects have a different security scope which allows the `Administratiesysteem onderwijsmedewerker` to share the attributes only with the reference components that are allowed to receive the attributes.
    
    All consunming reference components require consent to request data from the Employees API.
    The Notifications API can be used by consuming reference components to receive notifications about new, modified, or deleted entitities within the Employees API.

    The Employees API has a scope of primary and secundary education. Vocational education is out of scope. For Vocational Education we advice to use the [Open Education API (OOAPI)](https://openonderwijsapi.nl/).
  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
  
    schemaVersion:
      type: string
      description: ' |
        Schema version of this event/objectAPI using semantic versioning 2.0.0'.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.0.23
          
    Employee:
      title: Employee
      description: 'The Employee object with its identifiers and name information.'
      type: object
      x-tags:
        - Employee
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for the Employee.
            For Employees this value is empty. There is no primary identifier for Employees.
        userIds:
          type: array
          description: |
            A secundary identifier for thea EmployeeUser. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
          items:  (either userMasterIdentifier or userIds is required)
     type: object    items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
          - nlPersonRealId       - BPI # Basispoort ID – value can be used for students -and Las-keyemployees
                  - BasispoortId
         eduID # eduID identifier – value can be used for students and employees
   required:               - userIdeckId # ECK iD – value can be used for employees only, eckId is userIdType for  - userIdTypeuserMasterIdentifier for students
            schemaVersionrequired:

         $ref: '#/components/schemas/schemaVersion'    - userId
   givenName:           type:- stringuserIdType
        familyNamegivenName:
          type: string
        familyName:
          type: string
        familyNamePrefix:
          type: string
        sourcedId:
          type: string
          format: uuid
          description: |
            The Source Identifier of the object. This is a GUID System ID for an object.
            This is the GUID that Consumers will refer to when making API calls, or when needing to identify an object.
            It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds they use to SourceId.
            The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
            
            The sourceId attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
        status:
          description: |
            The status field gives an indication to Consumers about the status of an object.
            Consumers can delete objects that are flagged `tobedeleted`  as such if they wish.

            The status attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
          type: string
          enum:
            - active
            - tobedeleted
        dateCreated:
          type: string
          description: 'Indicates the date and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          format: date-time
          example: "2017-07-21T17:32:28Z"
        dateLastModified:
          type: string
          description: 'Indicates the date and time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'
          format: date-time
          example: "2022-08-11T15:31:12Z"
      required:
        - userIds
        - schemaVersion
        - givenName
        - familyName
        - status
        - sourceId
        - dateCreated
        - dateLastModified
    
    EmployeeCommunication:
      title: EmployeeCommunication
      description: 'Communication data of the Employee. For Employees this is the e-mail address, phone number or mobile phone number as provided by the School.'
      type: object
      x-tags:
        - EmployeeCommunication
      properties:
        sourceId:
          type: string
          format: uuid
          description: 'The Source Identifier of the Employee.'
        schemaVersion:
          $ref: '#/components/schemas/schemaVersion'
        email:
          type: string
          description: 'E-mail address hosted by school (e.g. L123456@school.nl).'
        phone:
          type: string
          description: 'Phone number as provided by the school.'
        mobile:
          type: string
          description: 'Mobile phone number as provided by the school.'
      required:
        - sourceId
        - schemaVersion         - email

    EmployeeRoles:
      title: EmployeeRoles
      description: 'Roles of the Employee within the school.'
      type: object
      x-tags:
        - EmployeeRoles
      properties:
        sourceId:
          type: string
          format: uuid
          description: 'The Source Identifier of the Employee.'
        schemaVersion:
 
        $ref: '#/components/schemas/schemaVersion'
        organisationRoles:
          type: array
          description: 'The organisation roles the Employee has within the organisation.'
          items:
            type: object
            properties:
              organisation:
                $ref: '#/components/schemas/SchoolReference'
              organisationRole:
                type: string
                description: 'The organisation role the Employee has within the organisation.'
                enum:
                  - administratief-medewerker
                  - applicatiebeheerder
                  - begeleider
                  - invalkracht
                  - ibp-er
                  - leermiddelencoordinator
                  - leraar
                  - mentor
                  - onderwijsbestuurder
                  - onderwijsdirecteur
                  - stagiair
              beginDate:
                type: string
                description: 'The start date on which the role becomes active (inclusive). Format: YYYY-MM-DD (according to RFC3339).'
                format: date
                example: '2022-07-31'
              endDate:
                type: string
                description: 'The end date on which the role becomes inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
                format: date
                example: '2024-08-31'
            required:
              - organisation
              - organisationRoles
              - beginDate
      required:
        - sourceId
        - schemaVersion
        - organisationRoles

    # This UserReference might not be necessary for the Employees API. References are made based on the sourceId of the Employee object.
    UserReference:
      type: object
      title: UserReference
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for a User.
            For Students the ECK iD is used.
            For Employees this value is empty. There is no primary identifier for Employees.
            (either userMasterIdentifier or userIds is required)
        userIds:
          type: array
          description: |
            A secundary identifier for a User. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
            (either userMasterIdentifier or userIds is required)
          items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
          - nlPersonRealId       - BPI # Basispoort ID – value can be used for students -and Las-keyemployees
                  - BasispoortIdeduID # eduID identifier – value can be used for students and employees
      - Medewerkernummer           - NEPRI required:# nlPersonRealId – value can be used for students only
     - userId            - ASI # Las-key userIdType– value can be used for students only
  SchoolReference:       type: object       title: SchoolReference- eckId # ECK iD – value description:can 'Abe reference used for employees only, eckId is userIdType for userMasterIdentifier for students
            required:
              - userId
              - userIdType
    
    SchoolReference:
      type: object
      title: SchoolReference
      description: 'A reference to a School organisation.'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `Onderwijsaanbiedercode``OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secundary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - InstellingserkenningOIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VestigingserkenningVE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)
                  - BasispoortIdBP_ID # Door Basispoort gegenereerde identifier voor de school.
                  - DigiDeliveryIdDD_ID # Door de Centrale Registratie van Edu-iX gegenereerde identifierDigiDeliveryId van de school.
                  - LAS-keyAS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType

    StatusResponse:
      title: StatusResponse
      type: object
      description: 'Functional status code and status message.'
      properties:
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
      required:
        - status
  
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            employee.basic: 'a scope that gives access to employee identifers and name.'
            employee.communication: 'a scope that gives access to employee communication attributes.'
            employee.roles: 'a scope that gives access to employee organisation roles attributes.'
            
paths:
  
  /employees/:
    parameters:
      - schema:
          type: string
        name: edu_org_idsourceId
        in: query
        required: true
        description: |'Reference to the sourceId of the Employee object.'
   All data from the- Employeesschema:
API requires a consent from the School.    type: string
     The `edu_org_id` parameter isname: mandatoryorgMasterId
to request information from the `Administratiesysteem onderwijsmedewerker`.  in: query
       This allowsrequired: thefalse
`Administratiesysteem onderwijsmedewerker` to check if the requesting client hasdescription: an|
active data exchange (consent) for the specified edu_org_id.   The organisationMasterIdentifier of the -school.
schema:          This type:parameter stringis used when the primairy identifier for a  name: sourceId
school (being the `OnderwijsaanbiederId`) is available.
      - inschema:
 query         requiredtype: truestring
        descriptionname: 'Reference to the sourceId of the Employee object.'orgId
           - schemain: query
         typerequired: stringfalse
        namedescription: schemaVersion|
        in: query The organisationIdentifier (secundary identifier) of the school.
 required: false        This description:parameter 'Optionalis parameterused toin requestcombination awith responsethe inorgIdType awhen specificthe schemaorganisationMasterIdentifier version.is Ifnot noneavailable.
supplied, the server will choose its default- schema:
version.'     get:     type: string
summary:  'Get Employee'       x-tagsexample: DD_ID
       - Employee   enum:
   tags:         - AdministratiesysteemOIE_CODE
onderwijsmedewerker       operationId: get-employee    - VE_CODE
 description: |         Request an- EmployeeBP_ID
object based on its sourceId.        - TheDD_ID
Source Identifier is the GUID System ID for an object. This is the- GUIDAS_ID
that Consumers will refer to when making API calls.name: orgIdType
       The sourcedIdin: ofquery
an object is considered an addressable property of anrequired: entityfalse
and as such will not be treated as Personallydescription: Identifiable|
Information (PII).       responses:  The type of the organisationIdentifier.
  '200':        This parameter is description:used OKin combination with the orgId when the organisationMasterIdentifier is not available.
content:    get:
      summary:  application/json:'Get Employee'
      x-tags:
       schema: - Employee
      tags:
       $ref: '#/components/schemas/Employee'
  - Administratiesysteem onderwijsmedewerker
      '400'operationId: get-employee
      description: |
 description: Bad Request     Request an Employee object based on content:its sourceId.
        The Source Identifier application/json:is the GUID System ID for an object. This is the GUID that Consumers will schema:refer to when making API calls.
        The sourcedId of $ref: '#/components/schemas/StatusResponse'an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '401200':
          description: UnauthorizedOK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponseEmployee'
        '403400':
          description: ForbiddenBad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404401':
          description: Not FoundUnauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:  '403':
      - OAuth2:   description:   Forbidden
      - employee.basic    /employees/school/content:
    parameters:       - schemaapplication/json:
           type: string  schema:
      name: edu_org_id         in$ref: query
'#/components/schemas/StatusResponse'
        required'404':
 true         description: |Not Found
         All datacontent:
from the Employees API requires a consent from the School.   application/json:
       The `edu_org_id` parameter is mandatory to request informationschema:
from the `Administratiesysteem onderwijsmedewerker`.           This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.$ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
      - schema:     -   employee.basic

 $ref: '#/componentsemployees/schemasschool/SchoolReference':
    parameters:
   name: school  - schema:
     in: query    type: string
   required: true    name: orgMasterId
   description: 'Reference to the primary orin: secundaryquery
identifier of a school.'     required: false
- schema:       description: |
  type: integer       The organisationMasterIdentifier name:of startthe  school.
      in: query   This parameter is used when the description: 'Start pointprimairy identifier for paginationa ofschool results,(being defaultsthe to 0,'
`OnderwijsaanbiederId`) is available.
      - examplesschema:
          defaulttype: string
        name: orgId
 value: 0      in: query
     summary: The start pointrequired: forfalse
pagination       - schemadescription: |
         type: integerThe organisationIdentifier (secundary identifier) of the school.
    maximum: 100     This parameter is used name:in limitcombination with the orgIdType when the organisationMasterIdentifier is not in:available.
query      -   descriptionschema:
'Limit of number of results returned by page, defaults to 20type: withstring
max 100.'         examplesexample: DD_ID
          defaultenum:
            - value:OIE_CODE
20            - summary:VE_CODE
The default value if none is provided      - BP_ID
   max:         - DD_ID
  value: 100         - AS_ID
  summary: The largest recommended page size name: orgIdType
    - schema:   in: query
      type: string required: false
        formatdescription: date-time|
        in: query The type of the  organisationIdentifier.
  name: since       This parameter required:is falseused in combination with the orgId when the organisationMasterIdentifier is description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'not available.
      - schema:
          type: integer
        examplename: "2017-07-21T17:32:28Z" start
       - schemain: query
         typedescription: string'Start point for pagination of results, defaults to 0,'
name: schemaVersion        examples:
in: query         requireddefault:
false         description: 'Optional parameter tovalue: request0
a response in a specific schema version. If none supplied, the server willsummary: chooseThe itsstart defaultpoint schemafor version.'pagination
    get:  -     summaryschema:
Get Employees for School       x-tagstype: integer
       - Employee  maximum: 100
   tags:     name: limit
  - Administratiesysteem onderwijsmedewerker    in:  query
operationId: get-employees-for-school       description: 'RequestLimit allof Employeenumber objectsof includingresults basicreturned informationby (identifierspage, anddefaults names)to for20 awith specifiedmax school100.'
        responsesexamples:
          '200'default:
            descriptionvalue: 20
 OK           contentsummary: The default value if none is provided
     application/json:     max:
         schema:   value: 100
            typesummary: arrayThe largest recommended page size
      - schema:
    items:      type: string
           $refformat: '#/components/schemas/Employee'date-time
        '400'in: query
         descriptionname: Badsince
Request        required: false
 content:       description: 'Request all objects modified after application/json:the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339,  schema:section 5.6'
        example: "2017-07-21T17:32:28Z"
    get:
 $ref: '#/components/schemas/StatusResponse'    summary: Get Employees for School
'401':      x-tags:
    description: Unauthorized   - Employee
      contenttags:
        - Administratiesysteem onderwijsmedewerker
 application/json:     operationId: get-employees-for-school
      description: 'Request schema:all Employee objects including basic information (identifiers and names) for a specified school.'
      $ref: '#/components/schemas/StatusResponse'responses:
        '403200':
          description: ForbiddenOK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatusResponseEmployee'
        '404400':
          description: NotBad FoundRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        security'401':
         - OAuth2description: Unauthorized
          content:
 - employee.basic    /employees/communication/:     parameters application/json:
      -    schema:    schema:
      type: string         name$ref: edu_org_id'#/components/schemas/StatusResponse'
        in'403':
 query         requireddescription: trueForbidden
        description: | content:
         All data from theapplication/json:
Employees API requires a consent from the School.       schema:
   The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.  $ref: '#/components/schemas/StatusResponse'
       This allows'404':
the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has andescription: activeNot dataFound
exchange (consent) for the specified edu_org_id.     content:
 - schema           application/json:
          type    schema:
string         name: sourceId      $ref: '#/components/schemas/StatusResponse'
      insecurity:
query        - requiredOAuth2:
     true       - employee.basic
description:
'Reference to the sourceId of the Employee object.' /employees/communication/:
    parameters:
      - schema:
          type: string
        name: schemaVersionsourceId
        in: query
        required: falsetrue
        description: 'OptionalReference parameterto tothe requestsourceId aof responsethe inEmployee aobject.'
specific schema version. If none supplied, the- serverschema:
will choose its default schema version.'     gettype: string
     summary: 'Get Employee Communication'name: orgMasterId
     x-tags:   in: query
    - EmployeeCommunication   required: false
   tags:     description: |
  - Administratiesysteem onderwijsmedewerker      The operationId: get-employee-communication
 organisationMasterIdentifier of the school.
    description: |     This parameter is used Requestwhen the primairy communicationidentifier attributesfor ofa Employeeschool object(being basedthe on`OnderwijsaanbiederId`) itsis sourceIdavailable.
      - schema:
The Source Identifier is the GUID System ID for an object.type: Thisstring
is the GUID that Consumers will refer to whenname: makingorgId
API calls.       in: query
The sourcedId of an object is considered an addressablerequired: propertyfalse
of an entity and as such will not bedescription: treated|
as Personally Identifiable Information (PII).      The responses:organisationIdentifier (secundary identifier) of the school.
   '200':       This parameter is used description: OK
       in combination with the orgIdType when the organisationMasterIdentifier is not available.
  content:    - schema:
       application/json:   type: string
          schemaexample: DD_ID
               $refenum:
'#/components/schemas/EmployeeCommunication'         '400':   - OIE_CODE
      description: Bad Request    - VE_CODE
     content:       - BP_ID
    application/json:        - DD_ID
     schema:       - AS_ID
        $refname: '#/components/schemas/StatusResponse'orgIdType
        '401'in: query
         descriptionrequired: Unauthorizedfalse
        description: |
content:          The type of application/json:
the organisationIdentifier.
          This parameter is schema:used in combination with the orgId when the organisationMasterIdentifier is not available.
     $refget:
'#/components/schemas/StatusResponse'      summary: 'Get Employee Communication'403':
      x-tags:
    description: Forbidden   - EmployeeCommunication
      contenttags:
        - Administratiesysteem onderwijsmedewerker
 application/json:     operationId: get-employee-communication
        schemadescription: |
        Request the communication attributes of Employee object $ref: '#/components/schemas/StatusResponse'
 based on its sourceId.
      '404':  The Source Identifier is the GUID System ID for description:an Notobject. FoundThis is the GUID that Consumers will refer to when making API calls.
 content:       The sourcedId of an object  application/json:
              schema:
 is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
       $ref: '#/components/schemas/StatusResponse'200':
       security:   description: OK
    - OAuth2:     content:
       - employee.communication    /employees/communication/school/application/json:
    parameters:         - schema:
                type$ref: string'#/components/schemas/EmployeeCommunication'
        name'400':
edu_org_id         in description: queryBad Request
          requiredcontent:
   true         description: |application/json:
              schema:
     All data from the Employees API requires a consent from the School.
$ref: '#/components/schemas/StatusResponse'
        '401':
The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteemdescription: onderwijsmedewerker`.Unauthorized
          Thiscontent:
allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an activeapplication/json:
data exchange (consent) for the specified edu_org_id.       - schema:
                $ref: '#/components/schemas/SchoolReferenceStatusResponse'
        name'403':
 school         indescription: queryForbidden
          requiredcontent:
true         description: 'Reference to theapplication/json:
primary or secundary identifier of a school.'       - schema:
 
        type: integer         name$ref: start'#/components/schemas/StatusResponse'
        in'404':
 query         description: 'Start point for pagination of results, defaults to 0,'Not Found
          content:
 examples:           defaultapplication/json:
            value: 0 schema:
           summary: The start point for pagination
$ref: '#/components/schemas/StatusResponse'
     - schemasecurity:
        - OAuth2:
type: integer           maximum: 100- employee.communication

  /employees/communication/school/:
    nameparameters:
limit      - schema:
 in: query         descriptiontype: 'Limitstring
of number of results returned by page, defaults to 20 with max 100.'name: orgMasterId
        examplesin: query
         defaultrequired: false
           valuedescription: 20
  |
         summary: The defaultorganisationMasterIdentifier valueof ifthe noneschool.
is provided         This parameter max:is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`)  value: 100
       is available.
    summary: The largest recommended page size
      - schema:
          type: string
          formatname: date-timeorgId
        in: query
        namerequired: sincefalse
        requireddescription: false|
        description: 'Request The allorganisationIdentifier objects(secundary modifiedidentifier) afterof the school.
specified timestamp. Format: Conform openapi in ZULU time as specified inThis RFCparameter 3339,is section 5.6'
        example: "2017-07-21T17:32:28Z"used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
        name  example: schemaVersionDD_ID
          inenum:
query         required: false  - OIE_CODE
     description: 'Optional parameter to request a response in- aVE_CODE
specific schema version. If none supplied, the server will choose its default schema version.'- BP_ID
    get:       summary: Get- EmployeesDD_ID
Communication for School       x-tags:   - AS_ID
    - EmployeeCommunication   name: orgIdType
  tags:      in: query
 - Administratiesysteem onderwijsmedewerker     required: false
operationId: get-employees-communication-for-school       description: 'Request communication|
attributes for all Employee objects for a specified school.'  The type of the organisationIdentifier.
responses:         '200': This parameter is used in combination with the orgId when description:the OKorganisationMasterIdentifier is not available.
      - contentschema:
            application/jsontype: integer
        name: start
   schema:     in: query
          typedescription: array'Start point for pagination of results, defaults to 0,'
        itemsexamples:
          default:
        $ref: '#/components/schemas/EmployeeCommunication'   value: 0
    '400':           descriptionsummary: BadThe Requeststart point for pagination
      - contentschema:
            application/jsontype: integer
          maximum: 100
 schema:       name: limit
        $refin: '#/components/schemas/StatusResponse'query
        '401'description: 'Limit of number of results returned by page, defaults to description:20 Unauthorizedwith max 100.'
        contentexamples:
          default:
  application/json:          value: 20
   schema:         summary: The default value if none is provided
$ref: '#/components/schemas/StatusResponse'         '403'max:
            descriptionvalue: 100
Forbidden           content summary: The largest recommended page size
      - application/jsonschema:
          type: string
   schema:       format: date-time
        $refin: '#/components/schemas/StatusResponse'query
        '404'name: since
         descriptionrequired: Notfalse
Found        description: 'Request all content:objects modified after the specified timestamp. Format: Conform openapi in ZULU time as application/json:specified in RFC 3339, section 5.6'
         schema:example: "2017-07-21T17:32:28Z"
    get:
      summary: Get Employees Communication  $ref: '#/components/schemas/StatusResponse'for School
      securityx-tags:
        - OAuth2:EmployeeCommunication
      tags:
     - employee.communication  -  /employees/roles/:Administratiesysteem onderwijsmedewerker
      parametersoperationId: get-employees-communication-for-school
     - schemadescription: 'Request communication attributes for all Employee objects for a specified school.'
      typeresponses: string
        name'200':
 edu_org_id         indescription: OK
 query         requiredcontent:
true         description: |  application/json:
        All data from the Employees API requiresschema:
a consent from the School.           The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`. type: array
                items:
  This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.$ref: '#/components/schemas/EmployeeCommunication'
         - schema'400':
          typedescription: stringBad   Request
     name: sourceId    content:
    in: query         required: true
application/json:
       description: 'Reference to the sourceId of the Employeeschema:
object.'       - schema:
          $ref: '#/components/schemas/SchoolReferenceStatusResponse'
        name'401':
 school         indescription: queryUnauthorized
        required: false content:
       description: 'Optional filter to request theapplication/json:
organsiation roles of the Employee at the specified school. Reference to the primary or secundaryschema:
identifier of a school.'       - schema:     $ref: '#/components/schemas/StatusResponse'
        type'403':
 string         namedescription: schemaVersionForbidden
        in: query content:
       required: false    application/json:
    description: 'Optional parameter to request a response in a specific schema:
version. If none supplied, the server will choose its default schema version.'     get$ref: '#/components/schemas/StatusResponse'
     summary: 'Get Employee Roles'404':
      x-tags:    description: Not Found
  - EmployeeRoles       tagscontent:
        - Administratiesysteem onderwijsmedewerker  application/json:
    operationId: get-employee-roles       description: | schema:
       Request the organiation roles attributes of Employee object based on its sourceId.$ref: '#/components/schemas/StatusResponse'
      security:
  The Source Identifier is the GUID System- IDOAuth2:
for an object. This is the GUID that Consumers will refer to when making API calls.- employee.communication

  /employees/roles/:
    Theparameters:
sourcedId of an object is considered an- addressableschema:
property of an entity and as such will not be treatedtype: asstring
Personally Identifiable Information (PII).     name: sourceId
responses:         '200'in: query
         descriptionrequired: OKtrue
          contentdescription: 'Reference to the sourceId of the Employee  object.'
   application/json:   - schema:
          schematype: string
        name: orgMasterId
     $ref   in: '#/components/schemas/EmployeeRoles'query
        '400'required:  false
        description: |
 Bad Request        The organisationMasterIdentifier  content:of the school.
          This parameter application/json:is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.
 schema:     - schema:
          $reftype: '#/components/schemas/StatusResponse'string
        '401'name: orgId
        in: query
description: Unauthorized       required: false
  content:      description: |
     application/json:     The organisationIdentifier (secundary identifier) of the school.
   schema:       This parameter is used in combination with the orgIdType when $ref: '#/components/schemas/StatusResponse'
the organisationMasterIdentifier is not available.
      - '403'schema:
          descriptiontype: Forbiddenstring
          contentexample: DD_ID
           application/jsonenum:
            - OIE_CODE
schema:            - VE_CODE
   $ref: '#/components/schemas/StatusResponse'         '404':- BP_ID
          description: Not Found- DD_ID
         content:   - AS_ID
        application/jsonname: orgIdType
        in: query
   schema:     required: false
        description: |
$ref: '#/components/schemas/StatusResponse'       security:  The type of the organisationIdentifier.
  - OAuth2:       This parameter is used in combination -with employee.rolesthe orgId when  /employees/roles/school/:
    parameters:the organisationMasterIdentifier is not available.
    get:
      summary: 'Get Employee Roles'
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee-roles
      description: |
        Request the organiation roles attributes of Employee object based on its sourceId.
        The Source Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
        The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

  /employees/roles/school/:
    parameters:
      - schema:
          type: string
        name: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primairy identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
       - schema:description: |
          The organisationIdentifier (secundary identifier) of the school.
          This parameter is used in  type: string
combination with the orgIdType when the organisationMasterIdentifier is not available.
      - nameschema:
 edu_org_id         intype: string
 query         requiredexample: DD_ID
 true         descriptionenum:
     |       - OIE_CODE
  All data from the Employees API requires a consent from the School.- VE_CODE
          The `edu_org_id` parameter- isBP_ID
mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.     - DD_ID
    This allows the `Administratiesysteem onderwijsmedewerker` to check if the- requestingAS_ID
client has an active data exchange (consent) for thename: specified edu_org_id.orgIdType
       - schemain: query
         $refrequired: '#/components/schemas/SchoolReference'false
        namedescription: school|
        in: query The type of the organisationIdentifier.
    required: true     This parameter is used description:in 'Referencecombination towith the primaryorgId orwhen secundarythe identifierorganisationMasterIdentifier ofis anot schoolavailable.'
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        name: limit
        in: query
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.': Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
    get:
      summary: Get Employees Roles for School
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-roles-for-school
      description: 'Request organisation roles attributes for all Employee objects for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

x-tags:
  - name: Employee
  - name: EmployeeCommunication
  - name: EmployeeRoles

...

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: 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 regie op gegevens 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.
- 0.0.4: Berichtdefinities 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 Employees 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 volgende wijzigingen zijn gedaan:
- Wijzigingen in de architectuur:
  - Attribuut schemaVersion is verwijderd uit de berichtspecificaties.
  - 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.

Versions Compared

Old Version 11

New Version 12

Key