DirectoryApplicationMaintenance.yaml

openapi: 3.0.1
info:
  title: I_Directory_Application_Maintenance
  description: |
   # REST Schnittstelle zur Pflege der Fachanwendungsdaten der Verzeichniseinträge
     Über diese Schnittstelle können Fachanwendungsdaten der Verzeichniseinträge erzeugt, aktualisiert und gelöscht werden. 
  version: 1.1.4
  # Änderungen in Version 1.1.4
  #  - KOM-LE_Version wurde durch komLeData ersetzt. Dies erlaubt die Angabe von KIM-Versionen für einzelne KIM-Adressen. 
  #  - Die Client Authentisierung wurde auf mutualTLS angepasst (OAuth2 wurde gestrichen)
  #  - Server URLs hinzugefügt  
  # Änderungen in Version 1.1.3
  #  - Filtermöglichkeiten in Leseoperationen read_Directory_Entry 
  #    (Wildcard "*" & Vorhandensein \00) aufgenommen.
  #  - Suchparameter in Leseoperationen read_Directory_Entry aufgenommen:
  #    maxKOMLEadr, changeDateTimeFrom, changeDateTimeTo
  # Änderungen in Version 1.1.2
  #  - Fehlerbehandlung für Operation modify_Directory_FA-Attributes in den Kommentaren dieser Operation ausführlicher beschrieben.
  #  - Im Datenmodell für DirectoryEntry Attribut "userCertificates" maxItems auf 50 gesetzt
  #
  # Änderungen in Version 1.1.1
  #  - Im Datenmodell für Attribut "changeDateTime" den Format String "date-time" auskommentiert. Mit dieser Format Vorgabe ist kein Code mehr generierbar. Es soll sich aber weiterhin an das Format gehalten werden.
  #
  # Änderungen in Version 1.1.0
  #  - getInfo Operation - inklusive den dazugehörenden Schema Objekten "InfoObject", "Contact" und "License" - hinzugefügt.
  #  - Attribute professionOID und entryType zusätzlich in die Basisdaten - als Kopie aus den Zertifikatsdaten (userCertificate) aufgenommen. Diese Attribute wurden ebenfalls in die read_Directory_Entry Operation als Suchparameter aufgenommen.
  #
  # initiale Version
 
externalDocs:
  description: Weitere Dokumentationen
  url: http://www.gematik.de
servers:
- url: https://directory.vzd.telematik:9643/
  description: Production server (PU)
- url: https://directory-test.vzd.telematik-test:9643/
  description: Test server (TU)
- url: https://directory-ref.vzd.telematik-test:9643/
  description: Reference server (RU)


tags:
- name: getInfo Directory Application Maintenance
  description: Diese Operation liefert Metadaten über diese Schnittstelle
- name: DirectoryEntry Administration
  description: Pflege der Verzeichniseinträge (Basiseinträge)
- name: Certificate Administration
  description: Pflege der Zertifikatseinträge 
- name: Application Data Administration
  description: Pflege der Fachdaten

paths:
  /:
    get:
      tags:
      - getInfo Directory Application Maintenance
      summary: Diese Operation liefert Metadaten über Schnittstelle Directory Application Maintenance
      description: Liefert die Metadaten aus dem Info Object diese OpenAPI Spezifikation und ergänzt sie.
      operationId: getInfo
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/InfoObject'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}


  /DirectoryEntries:
    get:
      tags:
      - DirectoryEntry Administration
      summary: Gesamten Verzeichniseintrag lesen
      description: |
       Liefert alle zum Filter passenden Verzeichniseinträge (maximal 100 Einträge). Die angegebenen Parameter werden mit logischen UND verknüpft.
       
        Für die Leseoperationen read_Directory_Entry read_Directory_Entry_for_Sync der Schnittstellen I_Directory_Administration und I_Directory_Application_Maintenanc werden die folgenden Filtermöglichkeiten unterstützt: 
          - Suche mit Wildcard "*" in den Parametern
                  - givenName
                  - sn
                  - cn
                  - displayName
                  - streetAddress
                  - postalCode
                  - countryCode
                  - localityName
                  - stateOrProvinceName
                  - title
                  - organization
                  - otherName
                  - telematikID
                  - specialization
                  - domainID
                  - holder
                  - professionOID
          - Suche nach Vorhandensein oder leerem Inhalt eines Attributs des VZD Datensatzes mit dem Kode \00 in den Parametern
                  - givenName
                  - sn
                  - cn
                  - displayName
                  - streetAddress
                  - postalCode
                  - countryCode
                  - localityName
                  - stateOrProvinceName
                  - title
                  - organization
                  - otherName
                  - specialization
                  - domainID
                  - holder
                  - professionOID
                  - changeDateTimeFrom
                  - changeDateTimeTo

            Diese Suche findet sowohl Datensätze mit nicht vorhandenem Attribut wie auch vorhandenem aber leerem Attribut.
            Der Suchparameter darf nur den Kode \00 enthalten, keine weiteren Zeichen.
            Alle Filterparameter einer Leseoperationen werden mit einem UND (&) verknüpft.      
      operationId: read_Directory_Entry
      parameters:
      - name: uid
        in: query
        description: ID von dem Verzeichniseintrag (distinguishedName.uid)
        schema:
          type: string  
      - name: givenName
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs givenName.
        schema:
          type: string  
      - name: sn
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs sn.
        schema:
          type: string  
      - name: cn
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs cn.
        schema:
          type: string  
      - name: displayName
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs displayName.
        schema:
          type: string  
      - name: streetAddress
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs streetAddress.
        schema:
          type: string  
      - name: postalCode
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs postalCode.
        schema:
          type: string  
      - name: countryCode
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs countryCode.
        schema:
          type: string    
      - name: localityName
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs localityName.
        schema:
          type: string  
      - name: stateOrProvinceName
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs stateOrProvinceName.
        schema:
          type: string  
      - name: title
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs title.
        schema:
          type: string  
      - name: organization
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs organization.
        schema:
          type: string  
      - name: otherName
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs otherName.
        schema:
          type: string  
      - name: telematikID
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs telematikID (die telematikID in den Basisdaten).
        schema:
          type: string  
      - name: telematikID-SubStr
        in: query
        description: |
         Erlaubt die Suche nach einem Substring am Anfang der telematikID (die telematikID in den Basisdaten).
         Entspricht der LDAP Filters Substring Assertion vom Typ "subInitial Component".
        schema:
          type: string  
      - name: specialization
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs specialization. 
         Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
        schema:
          type: string  
      - name: domainID
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs domainID. 
         Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
        schema:
          type: string  
      - name: holder
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs holder. 
         Der Verzeichniseintrag wird selektiert, wenn der angegebene holder im Attribut holder (array) des Verzeichniseintrags enthalten ist.
          Wenn der Parameter mit dem eigenen Wert des Clients belegt wird, werden alle gefundenen Einträge zurückgegeben (maximal 100 Einträge).
          Zur Suche nach Einträge ohne holder ist der Parameter mit dem einem leeren String "" zu belegen. Auch in diesem Fall werden alle gefundenen Einträge zurückgegeben (maximal 100 Einträge).
        schema:
          type: string  
      - name: personalEntry
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs personalEntry. 
        schema:
          type: string  
      - name: dataFromAuthority
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs dataFromAuthority. 
        schema:
          type: string  
      - name: professionOID
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs professionOID. 
         Selektiert der Verzeichniseintrag, wenn der angegebene Wert in den professionOID's (array) des Basiseintrags vorhanden ist. 
        schema:
          type: string  
      - name: entryType
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs entryType. 
         Selektiert der Verzeichniseintrag, wenn der angegebene Wert in den entryType's (array) des Basiseintrags vorhanden ist. 
        schema:
          type: string  
      - name: maxKOMLEadr
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs maxKOMLEadr. 
        schema:
          type: string  
      - name: changeDateTimeFrom
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs changeDateTime. 
          Selektiert alle Datensätze mit 
           changeDateTime >= changeDateTimeFrom
        schema:
          type: string  
          # format: date-time
          example: "2017-07-21T17:32:28Z"          
      - name: changeDateTimeTo
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs changeDateTime. 
          Selektiert alle Datensätze mit 
           changeDateTime <= changeDateTimeTo
        schema:
          type: string  
          # format: date-time
          example: "2018-07-21T17:32:28Z"
      - name: baseEntryOnly
        in: query
        description: |
         Mit baseEntryOnly = "true" wird nur der Basiseintrag (baseDirectoryEntry) im Response zurückgegeben. Falls nicht angegeben oder mit "false" belegt, wird der gesamte Verzeichniseintrag mit Zertifikaten und Fachdaten im Response zurückgegeben.
        schema:
          type: boolean
          example: true
          
      responses:
        200:
          description: |
           OK
           Es werden alle zu dem Filter Parametern passenden Verzeichniseinträge - inklusive Zertifikaten und Fachdaten - zurückgegeben.
           Bei mehr als 100 gefundenen Einträgen nur 100 gefundenen Einträge zurückgegeben.   
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/DirectoryEntries'

        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not Found
          content: {}

  /DirectoryEntries/Certificates:
  
    get:
      tags:
      - Certificate Administration
      summary: Zertifikat lesen
      description: Liefert alle Zertifikate, die dem Filter (siehe 'parameters') entsprechen.
      operationId: read_Directory_Certificates
      parameters:
      - name: uid
        in: query
        description: ID vom übergeordneten Verzeichniseintrag
        schema:
          type: string
      - name: certificateEntryID
        in: query
        description: |
         ID von dem Zertifikat (dn.cn vom Zertifikatseintrag)
         - Wenn angegeben wird das adressierte (certificateEntryID) Zertifikat geliefert.
         - Wenn nicht angegeben werden alle Zertifikate des übergeordneten Verzeichniseintrags geliefert.
        schema:
          type: string
      - name: entryType
        in: query
        description: Erlaubt die Suche mit Hilfe des Attributs entryType.
        schema:
          type: string
      - name: telematikID
        in: query
        description: |
         telematikID von dem Zertifikat 
         Erlaubt die Suche nach Zertifikatseinträgen einer telematikID.
        schema:
          type: string
      - name: professionOID
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs professionOID. 
         Der Verzeichniseintrag wird selektiert, wenn die angegebene professionOID im Attribut professionOID (array) des Zertifikatseintrags enthalten ist.
        schema:
          type: string  
      - name: usage
        in: query
        description: |
         Erlaubt die Suche mit Hilfe des Attributs usage. 
         Der Verzeichniseintrag wird selektiert, wenn die angegebene usage im Attribut usage (array) des Zertifikatseintrags enthalten ist.
        schema:
          type: string  

      responses:
        200:
          description: |
           OK
           Es werden alle gefundenen Zertifikatseinträge zurückgegeben.
           Bei mehr als 100 gefundenen Einträgen nur 100 gefundenen Einträge zurückgegeben.                                                                                                         
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/userCertificates'

        401:
          description: |
           Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: |
           Not Found
           Certificate not found
          content: {}

  /DirectoryEntries/{telematikID}/KOM-LE_Fachdaten:
    post:
      tags:
      - Application Data Administration
      summary: Fachdateneintrag erzeugen
      description: Erzeugt einen neuen Fachdateneintrag
      operationId: add_Directory_FA-Attributes
      parameters:
       - name: fad
         in: query
         description: Identifikator vom anfragenden Fachdienstanbieter.
         schema:
          type: string
       - name: telematikID
         in: path
         description: telematikID von dem Verzeichniseintrag 
         schema:
          type: string
         required: true
      requestBody:
        content:
          application/json:
            schema:
             $ref: '#/components/schemas/FAD1'
   
      responses:
        201:
          description: |
           Created
           Der Fachdateneintrag wurde erfolgreich angelegt.
          content: {}
        400:
          description: |
           Bad Request
           Fehler in dem Request Body
          content: 
            application/json:
             schema:
              $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not Found
                    #  telematikID not found
          content: {}


  /DirectoryEntries/{telematikID}/KOM-LE_Fachdaten/{fad}:
  
    get:
      tags:
      - Application Data Administration
      summary: Fachdateneintrag lesen
      description: Liefert den adressierten Fachdateneintrag.
      operationId: get_Directory_FA-Attributes
      parameters:
      - name: telematikID
        in: path
        description: telematikID von dem Verzeichniseintrag
        schema:
          type: string
        required: true  
      - name: fad
        in: path
        description: FAD vom aufrufenden Fachdienst Anbieter
        schema:
          type: string
        required: true  

      responses:
        200:
          description: OK
                    #  Der Fachdateneintrag wird zurückgegeben.
 
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/FAD1'

        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not Found
                    #  telematikID not found
          content: {}

    put:
      tags:
      - Application Data Administration
      summary: Fachdateneintrag ändern
      description: Ändert den adressierten Fachdateneintrag.
      operationId: modify_Directory_FA-Attributes
      parameters:
      - name: telematikID
        in: path
        description: telematikID von dem Verzeichniseintrag
        schema:
          type: string
        required: true  
      - name: fad
        in: path
        description: FAD vom aufrufenden Fachdienst Anbieter
        schema:
          type: string
        required: true  
      requestBody:
        content:
          application/json:
            schema:
             $ref: '#/components/schemas/FAD1'
   
      responses:
        200:
          description: |
           OK
           Der Fachdateneintrag wurde erfolgreich geändert.
          content: {}
        400:
          description: | 
           Bad Request
           Fehler in dem Request Body
           
           Beispiele für Fehlerfälle:
            
             - Anzahl der zulässigen Mail Adressen (maxKOMLEadr) überschritten 
               Ein Response mit HTTP Status Kode 400 und folgenden Werten im Body wird zurück gegeben
               ```
                {
                    "attributeName": "mail",
                    "attributeError": "maxKOMLEadr wurde überschritten"
                  }
            - Unzulässiger Wert von Attribut KOM-LE_Version im Request
              Ein Response mit HTTP Status Kode 400 und folgenden Werten im Body wird zurück gegeben
              ```
                 {
                    "attributeName": "KOM-LE_Version",
                    "attributeError": "Unzulässiger Wert"
                   }
                       
          content: 
            application/json:
             schema:
              $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not Found
                    #  telematikID not found
          content: {}


    delete:
      tags:
      - Application Data Administration
      summary: Fachdateneintrag löschen
      description: Löscht den adressierten Fachdateneintrag.
      operationId: delete_Directory_FA-Attributes
      parameters:
      - name: telematikID
        in: path
        description: telematikID von dem Verzeichniseintrag
        schema:
          type: string
        required: true  
      - name: fad
        in: path
        description: FAD vom aufrufenden Fachdienst Anbieter
        schema:
          type: string
        required: true  

      responses:
        200:
          description: OK
                    #  Der Fachdateneintrag wurde erfolgreich gelöscht.
          content: {}
        400:
          description: Bad Request
                    #  Fehler in dem Request Body
          content: 
            application/json:
             schema:
              $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not Found
                    #  telematikID not found
          content: {}

components:

  schemas:
  
    userCertificate:
      description: Jeder Verzeichniseintrag muss mindestens ein Zertifikat enthalten.
      required:
      - dn
      type: object
      properties:
        dn:
          $ref: '#/components/schemas/distinguishedName'
        entryType:
          type: string
          description: |
           Eintragstyp Wird vom VZD anhand der in dem Zertifikat enthaltenen OID (Extension Admission, Attribut ProfessionOID) und der Spalte Eintragstyp in Tab_VZD_Mapping_Eintragstyp_und_ProfessionOID automatisch eingetragen. 
           Siehe auch [gemSpecOID]# Tab_PKI_402 und Tab_PKI_403'
          readOnly: true
        telematikID:
          type: string
          description: |
           Wird beim Anlegen des Eintrags vom VZD aus dem Zertifikat übernommen (Feld registrationNumber der Extension Admission).
           Falls der Basiseintrag (baseDirectoryEntry) ohne Zertifikat angelegt wird, kann in Operation add_Directory_Entry die telematikID angegeben werden.
           Damit ist der Verzeichniseintrag bereits über die telematikID auffindbar.
        professionOID:
          maxItems: 100
          minItems: 0
          type: array
          readOnly: true
          items:
            type: string
            description: |
             Profession OID / Wird vom VZD anhand der in den Zertifikaten enthaltenen OIDs (Extension Admission, Attribut ProfessionOID) und dem Mapping in ab_VZD_Mapping_Eintragstyp_und_ProfessionOID automatisch eingetragen.
             Siehe [gemSpecOID]# Tab_PKI_402 und Tab_PKI_403. 
             Kann mehrfach vorkommen (0..100)
        usage:
          maxItems: 100
          minItems: 0
          type: array
          description: |
           Nutzungskennzeichnung kann pro Zertifikat mehrfach
            vergeben werden. Vorgegebener Wertebereich [KOM-LE, ePA].
           Obligatorisch für LEI und KTR mit vorgegebenem Wert usage=ePA'
          items:
            type: string
            enum:
            - KOM-LE
            - ePA
        userCertificate:
          type: string
          description: |
           Zertifikat im DER Format. Base64 kodiert.
           Die pflegende Stelle erhält das Zertifikat vom TSP oder falls das nicht möglich ist wird ein Ersatzverfahren abgestimmt.
        description:
          type: string
          description: Dieses Attribut ermöglicht das Zertifikat zu beschreiben, um
             die Administration des VZD Eintrags zu vereinfachen.

    userCertificates:
      type: array
      items:
        $ref: '#/components/schemas/userCertificate'
            
    Fachdaten:
      required:
      - dn
      type: object
      properties:
        dn:
          $ref: '#/components/schemas/distinguishedName'
        FAD1:
          maxItems: 50
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/FAD1'

    FAD1:
      required:
      - dn
      type: object
      properties:
        dn:
          $ref: '#/components/schemas/distinguishedName'
        mail:
          type: array
          items:
            type: string
            description: 'E-Mail-Adresse'
        komLeData:
          type: array
          items:
            type: object
            properties:
              mail:
                type: string
                description: 'E-Mail-Adresse'
              version:
                type: string
                example: 1.5
                description: |
                 Die höchste KOM-LE_Version der KIM Clientmodule für die KIM Mail Adresse
                 Für jede Mail Adresse aus dem "mail" Attribut darf es nur einen Eintrag in Attribut KOM-LE_Version geben. Es dürfen in KOM-LE_Version keine Mail Adressen referenziert werden, die nicht im zugehörigen "mail" Attribut enthalten sind.
                 Wenn eine Mail Adresse gelöscht wird, muss auch ihre KOM-LE_Version gelöscht werden.
                 Geschrieben wird immer die gesamte Liste. Für Änderungen muss erst der aktuelle Eintrag gelesen werden und nach Änderung in der Liste der gesamte Eintrag wieder geschrieben werden.


    distinguishedName:
      required:
      - uid
      readOnly: true
      type: object
      properties:
        uid:
          type: string
          description: |
           entryID: Name/ID, den den Eintrag eindeutig identifiziert. 
           Hat für den Verzeichnisdienst_Eintrag, Certificate, KOM-LE_Fachdaten und FAD1 eines Verzeichniseintrags den gleichen Wert.
        dc:
          type: array
          items:
            type: string
            description: Domain Component
        ou:
          type: array
          items:
            type: string
            description: Organizational Unit
        cn:
          type: string
          description: Common Name

    baseDirectoryEntry:
      required:
      - cn
      - dn
      type: object
      properties:
        dn:
          $ref: '#/components/schemas/distinguishedName'
        givenName:
          type: string
          description: |
            HBA: Vorname, obligatorisch, wird aus dem Zertifikat übernommen
            SMC-B: nicht verwendet
          readOnly: true
          example:  Vorname
        sn:
          type: string
          description: |
            HBA: Name, obligatorisch, wird aus dem Zertifikat übernommen
            SMC-B: nicht verwendet
          readOnly: true
          example:  Nachname
        cn:
          type: string
          description: |
           HBA: Vorname und Nachname
           SMC-B: Bezeichner: Name Wird vom VZD aus dem Zertifikatsattribut commonName übernommen.
          readOnly: true
          example:  Vorname Nachname  
        displayName:
          type: string
          description: |
           Anzeigename, kann geändert werden. 
           Dieses Attribut wird genutzt um den Namen der Organisation gegenüber dem Anwender darzustellen (Verwendung als Filter-Attribut um die Suche einzuschränken und bei der Darstellung des Ergebnisses).
              Der Wert wird von der pflegenden Stelle festgelegt.
              Konvention für HBA Einträge: Name, Vorname
          example:  Name, Vorname
        streetAddress:
          type: string
          description: |
           Straße und Hausnummer
           Der Wert wird von der pflegenden Stelle festgelegt
          example: Friedrichstraße 136
        postalCode:
          type: string
          description: |
           Postleitzahl
           Der Wert wird von der pflegenden Stelle festgelegt'
          example: 10117
        countryCode:
          type: string
          maxLength: 2
          description: |
           Ländercode
           Entsprechend ISO-3166-1 ALPHA-2
           Falls das Attribut beim Anlegen des Datensatzes nicht beölegt wird, ergänzt der VZD den Code für Deutschland (Defaultwert).
          example: DE        
        localityName:
          type: string
          description: |
           Ort
           Der Wert wird von der pflegenden Stelle festgelegt
          example: Berlin
        stateOrProvinceName:
          type: string
          description: |
           Bundesland
           Der Wert wird von der pflegenden Stelle festgelegt
          example: Berlin
        title:
          type: string
          description: |
           HBA: Titel, optional
           SMC-B: nicht verwendet
        organization:
          type: string
          example: 12345670
          description: |
           Organisation
           Der Wert wird von der pflegenden Stelle festgelegt
        otherName:
          type: string
          description: |
           Anderer Name 
           Wird vom VZD aus dem Zertifikatsattribut otherName übernommen.
        telematikID:
          type: string
          description: |
           Wird beim Anlegen des Eintrags vom VZD aus dem Zertifikat übernommen (Feld registrationNumber der Extension Admission).
           Falls der Basiseintrag (baseDirectoryEntry) ohne Zertifikat angelegt wird, kann in Operation add_Directory_Entry die telematikID angegeben werden.
           Damit ist der Verzeichniseintrag bereits über die telematikID im baseDirectoryEntry auffindbar. Diese telematikID muss mit der telematikID aus dem Zertifikatseintrag (userCertificate) übereinstimmen. Simmten die telematikIDs nicht überein, wird die Operation mit Fehlercode 422 abgelehnt
        specialization:
          maxItems: 100
          type: array
          description: |
           Fachgebiet
           Der Wert wird von der pflegenden Stelle festgelegt
          items:
            type: string
        domainID:
          maxItems: 100
          type: array
          description: |
           Ärzte-> Betriebsstättennummer
           Der Wert wird aus dem Zertifikat übernommen (Attribut organizationName)
          items:
            type: string
            example: 345678975
        holder:
          maxItems: 100
          type: array
          description: |
           Identifiziert den Eigentümer dieses Verzeichniseintrags, der Änderungen an ihm vornehmen darf.
           Hat keinen Einfluss auf Fachdaten und Zertifikatsdaten.
           Beim Anlegen eines neuen Verzeichniseintrags (add_Directory_Entry)
              - Ist im add_Directory_Entry Request das Attribut "holder" nicht vorhanden oder enthält keine Werte
                 o Wird vom VZD aus dem ID_TOKEN claim scope der Wert entnommen und als "holder" in dieses Attribut eingetragen. 
              - Ist im add_Directory_Entry Request das Attribut "holder" vorhanden und mit Inhalten gefüllt
                 o Übernimmt der VZD die Werte aus dem Request und trägt sie - nach Prüfung ihrer Gültigkeit - in den Verzeuichniseintrag ein. 
                   Ist ein Wert aus dem Request nicht gültig, weist der VZD die Operation mit HTTP-Status-Code 422 ab.
            Beim Ändern eines neuen Verzeichniseintrags (modify_Directory_Entry)
              - Ist im modify_Directory_Entry Request das Attribut "holder" nicht vorhanden oder enthält keine Werte
                 o Die Werte im aktuellen "holder" Attribut des Verzeichniseintrags bleiben erhalten.
              - Ist im add_Directory_Entry Request das Attribut "holder" vorhanden und mit Inhalten gefüllt
                 o Übernimmt der VZD die Werte aus dem Request und trägt sie - nach Prüfung ihrer Gültigkeit - in den Verzeuichniseintrag ein. 
                   Ist ein Wert aus dem Request nicht gültig, weist der VZD die Operation mit HTTP-Status-Code 422 ab.
          items:
            type: string
            example: KartenHerausgeberABC
        maxKOMLEadr:
          type: string
          description: |
           Maximale Anzahl von mail Adressen in den KOM-LE Fachdaten. 
           Falls kein Wert eingetragen wurde, können beliebig viele mail Adressen in den KOM-LE Fachdaten eingetragen werden. Falls ein Wert eingetragen wurde, können maximal so viele mail Adressen in den KOM-LE Fachdaten eingetragen werden.
          example: 1
        personalEntry:
          type: boolean
          description: |
           Wird vom VZD eingetragen 
           Wert == TRUE, wenn alle Zertifikate den entryType 1 haben (Berufsgruppe), 
           Wert == FALSE sonst
          readOnly: true
          example: true
        dataFromAuthority:
          type: boolean
          description: |
           Wird vom VZD eingetragen
           Wert == TRUE, wenn der Verzeichnisdienst_Eintrag von dem Kartenherausgeber geschrieben wurde, 
           Wert == FALSE sonst 
          readOnly: true
          example: true
        changeDateTime:
          type: string
#          format: date-time Mit dieser Format Vorgabe ist kein Code mehr generierbar, deshalb auskommentiert. Es soll sich aber weiterhin an das Format gehalten werden.
          description: |
           Der VZD setzt dieses Attribut bei jeder Schreiboperation für den Datensatz (Basisdaten) auf die aktuelle Zeit. Format entsprechend RFC 3339, section 5.6.
          readOnly: true
          example: "2017-07-21T17:32:28Z"
        professionOID:
          maxItems: 100
          minItems: 0
          type: array
          readOnly: true
          items:
            type: string
            description: Erlaubt die Suche nach professionOID (als Kopie des Attributs aus dem Zertifikatseintrags).
        entryType:
          maxItems: 10
          minItems: 0
          type: array
          readOnly: true
          items:
            type: string
            description: Erlaubt die Suche nach entryType (als Kopie des Attributs aus dem Zertifikatseintrags).


    DirectoryEntry:
      type: object
      properties:
        DirectoryEntryBase:
          $ref: '#/components/schemas/baseDirectoryEntry'
        userCertificates:
          maxItems: 50
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/userCertificate'
        Fachdaten:
          maxItems: 50
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/Fachdaten'

    DirectoryEntries:
      type: array
      items:
        $ref: '#/components/schemas/DirectoryEntry'

            
    Error:
      type: object
      maxItems: 50
      minItems: 0
      properties:
        attributeName:
          description: Name des Attributs, in dem ein Fehler erkannt wurde
          type: string
        attributeError:
          description: Beschreibung des erkannten Fehlers
          type: string

    InfoObject:
      required:
      - title
      - version
      readOnly: true
      type: object
      properties:
        title:
          type: string
          description: Der Titel der Anwendung
          example: "I_Directory_Application_Maintenance"
        description:
          type: string
          description: Eine kurze Beschreibung der Anwendung
          example: "REST Schnittstelle zur Pflege der Fachanwendungsdaten der Verzeichniseinträge.
              Über diese Schnittstelle können Fachanwendungsdaten der Verzeichniseinträge erzeugt, aktualisiert und gelöscht werden."
        termsOfService:
          type: string
          format: uri
          description: Eine URL zu den Terms of Service für dieses API.
          example: "http://example.com/terms/"
        contact:
          $ref: '#/components/schemas/Contact'
        license:
          $ref: '#/components/schemas/License'
        version:
          type: string
          description: Die Version von dem OpenAPI Document (YAML Datei)
          example: "1.1.0"

    Contact:
      readOnly: true
      description: Die Kontaktinformationen für diese Schnittstelle.
      type: object
      properties:
        name:
          type: string
          description: Der Name von der Kontaktperson / -Organisation
          example: "Firma 123"
        url:
          type: string
          format: uri
          description: | 
            Eine URL zu den Kontaktinformationen für dieses API.
            In dem Dokument unter dieser URL muss ein Link zum Download der aktuell genutzten YAML Datei dieser Schnittstelle hinterlegt sein.
          example: "http://www.example.com/support"
        email:
          type: string
          format: email
          description: Der E-Mail Adresse der Kontaktperson / -Organisation.
          example: "support@example.com"

    License:
      required:
      - name
      readOnly: true
      description: Der Lizenzinformationen für diese Schnittstelle.
      type: object
      properties:
        name:
          type: string
          description: Der Lizenzname
          example: "Apache 2.0"
        url:
          type: string
          description: Eine URL zu den Lizenzinformationen für dieses API.
          example: "https://www.apache.org/licenses/LICENSE-2.0.html"

#  securitySchemes:
#    TLS:
#      type: mutualTLS
#   Da "mutualTLS" erst ab OpenAPI 3.1 möglich ist - welches viele Tools noch nicht unterstützen -
#   wird die beidseitige TLS Authentisierung nicht hier definiert.