diff --git a/misc/BreCalApi.yaml b/misc/BreCalApi.yaml
index 66a598d..0d0c02f 100644
--- a/misc/BreCalApi.yaml
+++ b/misc/BreCalApi.yaml
@@ -37,6 +37,9 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/credentials'
+            example:
+              username: alfred
+              password: '123456'
       responses:
         '200':
           description: Successful response
@@ -44,6 +47,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/login_result'
+              example:
+                id: 42
+                participant_id: 5
+                first_name: John
+                last_name: Doe
+                user_name: johndoe
+                user_phone: '1234567890'
+                user_email: no@where.com
+                exp: 1630000000
+                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
         '400':
           $ref: '#/components/responses/400'
         '403':
@@ -66,6 +79,12 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/user_details'
+            example:
+              id: 42
+              first_name: John
+              last_name: Doe
+              user_phone: '1234567890'
+              user_email: no@where.de
       responses:
         '200':
           $ref: '#/components/responses/200'
@@ -91,6 +110,7 @@ paths:
           description: 'number of days in the past to include in the result. *Example: 7*.'
           schema:
             type: integer
+          example: 7
       responses:
         '200':
           description: ship call list
@@ -98,6 +118,73 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/shipcalls'
+              example:
+                - id: 6
+                  ship_id: 8
+                  type: arrival
+                  eta: '2023-08-21T08:23:35Z'
+                  voyage: Voyage 123
+                  etd: '2023-08-21T08:23:35Z'
+                  arrival_berth_id: 3
+                  departure_berth_id: 4
+                  tug_required: true
+                  pilot_required: true
+                  flags: 1
+                  pier_side: false
+                  bunkering: false
+                  replenishing_terminal: false
+                  replenishing_lock: false
+                  draft: 10.5
+                  tidal_window_from: '2023-08-21T08:23:35Z'
+                  tidal_window_to: '2023-08-21T08:23:35Z'
+                  rain_sensitive_cargo: false
+                  recommended_tugs: 2
+                  anchored: false
+                  moored_lock: false
+                  canceled: false
+                  evaluation: yellow
+                  evaluation_message: Time window too short
+                  time_ref_point: 1
+                  participants:
+                    - participant_id: 5
+                      type: 4
+                    - participant_id: 6
+                      type: 8
+                  created: '2023-08-21T08:23:35Z'
+                  modified: '2023-08-21T08:23:35Z'
+                - id: 7
+                  ship_id: 8
+                  type: departure
+                  eta: '2023-08-21T08:23:35Z'
+                  voyage: Voyage 123
+                  etd: '2023-08-21T08:23:35Z'
+                  arrival_berth_id: 3
+                  departure_berth_id: 4
+                  tug_required: true
+                  pilot_required: true
+                  flags: 1
+                  pier_side: false
+                  bunkering: false
+                  replenishing_terminal: false
+                  replenishing_lock: false
+                  draft: 10.5
+                  tidal_window_from: '2023-08-21T08:23:35Z'
+                  tidal_window_to: '2023-08-21T08:23:35Z'
+                  rain_sensitive_cargo: false
+                  recommended_tugs: 2
+                  anchored: false
+                  moored_lock: false
+                  canceled: false
+                  evaluation: yellow
+                  evaluation_message: Time window too short
+                  time_ref_point: 1
+                  participants:
+                    - participant_id: 5
+                      type: 4
+                    - participant_id: 6
+                      type: 8
+                  created: '2023-08-21T08:23:35Z'
+                  modified: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -119,6 +206,38 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/shipcall'
+            example:
+              id: 6
+              ship_id: 8
+              type: arrival
+              eta: '2023-08-21T08:23:35Z'
+              voyage: Voyage 123
+              etd: '2023-08-21T08:23:35Z'
+              arrival_berth_id: 3
+              departure_berth_id: 4
+              tug_required: true
+              pilot_required: true
+              flags: 1
+              pier_side: false
+              bunkering: false
+              replenishing_terminal: false
+              replenishing_lock: false
+              draft: 10.5
+              tidal_window_from: '2023-08-21T08:23:35Z'
+              tidal_window_to: '2023-08-21T08:23:35Z'
+              rain_sensitive_cargo: false
+              recommended_tugs: 2
+              anchored: false
+              moored_lock: false
+              canceled: false
+              evaluation: yellow
+              evaluation_message: Time window too short
+              time_ref_point: 1
+              participants:
+                - participant_id: 5
+                  type: 4
+                - participant_id: 6
+                  type: 8
       responses:
         '201':
           $ref: '#/components/responses/201'
@@ -143,6 +262,37 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/shipcall'
+            example:
+              ship_id: 8
+              type: arrival
+              eta: '2023-08-21T08:23:35Z'
+              voyage: Voyage 123
+              etd: '2023-08-21T08:23:35Z'
+              arrival_berth_id: 3
+              departure_berth_id: 4
+              tug_required: true
+              pilot_required: true
+              flags: 1
+              pier_side: false
+              bunkering: false
+              replenishing_terminal: false
+              replenishing_lock: false
+              draft: 10.5
+              tidal_window_from: '2023-08-21T08:23:35Z'
+              tidal_window_to: '2023-08-21T08:23:35Z'
+              rain_sensitive_cargo: false
+              recommended_tugs: 2
+              anchored: false
+              moored_lock: false
+              canceled: false
+              evaluation: yellow
+              evaluation_message: Time window too short
+              time_ref_point: 1
+              participants:
+                - participant_id: 5
+                  type: 4
+                - participant_id: 6
+                  type: 8
       responses:
         '200':
           $ref: '#/components/responses/200'
@@ -168,6 +318,25 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ship_list'
+              example:
+                - id: 2
+                  name: MS Bremen
+                  imo: 1234567
+                  type: 1
+                  length: 200
+                  width: 30
+                  draft: 10
+                  created: '2023-08-21T08:23:35Z'
+                  modified: '2023-08-21T08:23:35Z'
+                - id: 3
+                  name: MS Helgoland
+                  imo: 7654321
+                  type: 1
+                  length: 150
+                  width: 12
+                  draft: 5
+                  created: '2023-08-21T08:23:35Z'
+                  modified: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -189,6 +358,13 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/ship'
+            example:
+              name: MS Bremen
+              imo: 1234567
+              type: 1
+              length: 200
+              width: 30
+              draft: 10
       responses:
         '201':
           $ref: '#/components/responses/201'
@@ -213,6 +389,13 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/ship'
+            example:
+              id: 2
+              imo: 1234567
+              name: Ship name
+              type: 1
+              created: '2023-08-21T08:23:35Z'
+              modified: '2023-08-21T08:23:35Z'
       responses:
         '200':
           $ref: '#/components/responses/200'
@@ -232,10 +415,12 @@ paths:
       operationId: shipDelete
       parameters:
         - name: id
+          description: '**Id of ship**. *Example: 42*. Id of ship to be deleted.'
           in: query
           required: true
           schema:
             type: integer
+            example: 42
       responses:
         '200':
           $ref: '#/components/responses/200'
@@ -261,13 +446,23 @@ paths:
           description: '**Id of user**. *Example: 2*. User id returned by verify call.'
           schema:
             type: integer
+            example: 2
       responses:
         '200':
-          description: ship call list
+          description: one or all participants as list
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/participant_list'
+              example:
+                - id: 5
+                  name: BSMD
+                  type: 1
+                  created: '2023-08-21T08:23:35Z'
+                - id: 6
+                  name: Terminal 1
+                  type: 2
+                  created: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -291,6 +486,8 @@ paths:
           description: '**Id**. *Example: 42*. Id of referenced ship call.'
           schema:
             type: integer
+            example: 42
+          example: 42
       responses:
         '200':
           description: list of recorded times
@@ -298,6 +495,31 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/times_list'
+              example:
+                - id: 2
+                  eta_berth: '2023-08-21T08:23:35Z'
+                  eta_berth_fixed: true
+                  etd_berth: '2023-08-21T08:23:35Z'
+                  etd_berth_fixed: true
+                  lock_time: '2023-08-21T08:23:35Z'
+                  lock_time_fixed: true
+                  zone_entry: '2023-08-21T08:23:35Z'
+                  zone_entry_fixed: true
+                  operations_start: '2023-08-21T08:23:35Z'
+                  operations_end: '2023-08-21T08:23:35Z'
+                  remarks: Please be aware of the strong current
+                  shipcall_id: 23
+                  participant_id: 34
+                  berth_id: 1
+                  berth_info: 200m length
+                  pier_side: true
+                  participant_type: 4
+                  ata: '2023-08-21T08:23:35Z'
+                  atd: '2023-08-21T08:23:35Z'
+                  eta_interval_end: '2023-08-21T08:23:35Z'
+                  etd_interval_end: '2023-08-21T08:23:35Z'
+                  created: '2023-08-21T08:23:35Z'
+                  modified: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -319,6 +541,28 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/times'
+            example:
+              eta_berth: '2023-08-21T08:23:35Z'
+              eta_berth_fixed: true
+              etd_berth: '2023-08-21T08:23:35Z'
+              etd_berth_fixed: true
+              lock_time: '2023-08-21T08:23:35Z'
+              lock_time_fixed: true
+              zone_entry: '2023-08-21T08:23:35Z'
+              zone_entry_fixed: true
+              operations_start: '2023-08-21T08:23:35Z'
+              operations_end: '2023-08-21T08:23:35Z'
+              remarks: Please be aware of the strong current
+              shipcall_id: 23
+              participant_id: 34
+              berth_id: 1
+              berth_info: 200m length
+              pier_side: true
+              participant_type: 4
+              ata: '2023-08-21T08:23:35Z'
+              atd: '2023-08-21T08:23:35Z'
+              eta_interval_end: '2023-08-21T08:23:35Z'
+              etd_interval_end: '2023-08-21T08:23:35Z'
       responses:
         '201':
           $ref: '#/components/responses/201'
@@ -343,6 +587,31 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/times'
+            example:
+              id: 2
+              eta_berth: '2023-08-21T08:23:35Z'
+              eta_berth_fixed: true
+              etd_berth: '2023-08-21T08:23:35Z'
+              etd_berth_fixed: true
+              lock_time: '2023-08-21T08:23:35Z'
+              lock_time_fixed: true
+              zone_entry: '2023-08-21T08:23:35Z'
+              zone_entry_fixed: true
+              operations_start: '2023-08-21T08:23:35Z'
+              operations_end: '2023-08-21T08:23:35Z'
+              remarks: Please be aware of the strong current
+              shipcall_id: 23
+              participant_id: 34
+              berth_id: 1
+              berth_info: 200m length
+              pier_side: true
+              participant_type: 4
+              ata: '2023-08-21T08:23:35Z'
+              atd: '2023-08-21T08:23:35Z'
+              eta_interval_end: '2023-08-21T08:23:35Z'
+              etd_interval_end: '2023-08-21T08:23:35Z'
+              created: '2023-08-21T08:23:35Z'
+              modified: '2023-08-21T08:23:35Z'
       responses:
         '200':
           $ref: '#/components/responses/200'
@@ -362,6 +631,7 @@ paths:
       operationId: timesDelete
       parameters:
         - name: id
+          description: '**Id of times**. *Example: 42*. Id of times entry to be deleted.'
           in: query
           required: true
           schema:
@@ -397,7 +667,18 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/notification'
+                $ref: '#/components/schemas/notification_list'
+              example:
+                - id: 2
+                  shipcall_id: 52
+                  participant_id: 5
+                  message: Please be aware of the strong current
+                  created: '2023-08-21T08:23:35Z'
+                - id: 3
+                  shipcall_id: 52
+                  participant_id: 6
+                  message: Please be aware of the strong current
+                  created: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -420,6 +701,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/berth_list'
+              example:
+                - id: 3
+                  name: Pier 1
+                  owner_id: 5
+                - id: 4
+                  name: Pier 2
+                  owner_id: 5
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -439,7 +727,7 @@ paths:
         - name: shipcall_id
           in: query
           required: true
-          description: '**Id of ship call**. *Example: 52*. Id given in ship call list'
+          description: '**Id of ship call**. *Example: 3*. Id given in ship call list'
           schema:
             $ref: '#/components/schemas/shipcallId'
       responses:
@@ -449,6 +737,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/history_list'
+              example:
+                - id: 2
+                  shipcall_id: 3
+                  participant_id: 5
+                  operation: insert
+                  type: shipcall
+                  created: '2023-08-21T08:23:35Z'
+                - id: 3
+                  shipcall_id: 3
+                  participant_id: 6
+                  operation: update
+                  type: shipcall
+                  created: '2023-08-21T08:23:35Z'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -460,22 +761,30 @@ paths:
 components:
   schemas:
     credentials:
+      description: Login credentials for the user
       type: object
       properties:
         username:
           type: string
+          example: alfred
         password:
           type: string
           format: password
+          example: '123456'
       required:
         - username
         - password
+      example:
+        username: alfred
+        password: '123456'
     timesId:
       description: The unique identifier for a times entry
       type: integer
+      example: 2
     shipcallId:
       description: The unique identifier of a ship call
       type: integer
+      example: 6
     participant_assignment:
       description: Participant assigned to a shipcall with a given role (type)
       type: object
@@ -485,479 +794,944 @@ components:
       properties:
         participant_id:
           type: integer
+          example: 5
         type:
-          description: 'Currently this is encoded as an integer, since in OpenAPI 3.0 there are no enumerations supported with discrete integer values like a bitwise flag array used here. Each bit corresponds to a role. Since a participant can have multiple roles, these bits are combined by OR. Individual values: 1: BSMD 2: TERMINAL, 4: PILOT, 8: AGENCY, 16: MOORING, 32: PORT_ADMINISTRATION, 64: TUG'
+          description: 'Possible role values: 1: BSMD 2: TERMINAL, 4: PILOT, 8: AGENCY, 16: MOORING, 32: PORT_ADMINISTRATION, 64: TUG.   A participant may appear multiple times with different roles.'
           type: integer
+          example: 4
+      example:
+        participant_id: 5
+        type: 4
     shipcall:
       type: object
+      description: Ship call data
+      example:
+        id: 6
+        ship_id: 8
+        type: arrival
+        eta: '2023-08-21T08:23:35Z'
+        voyage: Voyage 123
+        etd: '2023-08-21T08:23:35Z'
+        arrival_berth_id: 3
+        departure_berth_id: 4
+        tug_required: true
+        pilot_required: true
+        flags: 1
+        pier_side: false
+        bunkering: false
+        replenishing_terminal: false
+        replenishing_lock: false
+        draft: 10.5
+        tidal_window_from: '2023-08-21T08:23:35Z'
+        tidal_window_to: '2023-08-21T08:23:35Z'
+        rain_sensitive_cargo: false
+        recommended_tugs: 2
+        anchored: false
+        moored_lock: false
+        canceled: false
+        evaluation: yellow
+        evaluation_message: Time window too short
+        time_ref_point: 1
+        participants:
+          - participant_id: 5
+            type: 4
+          - participant_id: 6
+            type: 8
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
       properties:
         id:
-          $ref: '#/components/schemas/shipcallId'
+          type: integer
+          example: 6
         ship_id:
           type: integer
+          example: 8
         type:
           $ref: '#/components/schemas/ShipcallType'
         eta:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
           nullable: true
         voyage:
           type: string
           maxLength: 16
+          example: Voyage 123
           nullable: true
         etd:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
           nullable: true
         arrival_berth_id:
           type: integer
+          example: 3
           nullable: true
         departure_berth_id:
           type: integer
+          example: 4
           nullable: true
         tug_required:
           type: boolean
+          example: true
           nullable: true
         pilot_required:
           type: boolean
+          example: true
           nullable: true
         flags:
           type: integer
+          example: 1
           nullable: true
         pier_side:
           type: boolean
+          example: false
           nullable: true
         bunkering:
           type: boolean
+          example: false
           nullable: true
         replenishing_terminal:
           type: boolean
+          example: false
           nullable: true
         replenishing_lock:
           type: boolean
+          example: false
           nullable: true
         draft:
           type: number
           format: double
+          example: 10.5
           nullable: true
         tidal_window_from:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
           nullable: true
         tidal_window_to:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
           nullable: true
         rain_sensitive_cargo:
           type: boolean
+          example: false
           nullable: true
         recommended_tugs:
           type: integer
+          example: 2
           nullable: true
         anchored:
           type: boolean
+          example: false
           nullable: true
         moored_lock:
           type: boolean
+          example: false
           nullable: true
         canceled:
           type: boolean
+          example: false
           nullable: true
         evaluation:
           $ref: '#/components/schemas/EvaluationType'
         evaluation_message:
-          readOnly: true
           maxLength: 512
           type: string
+          example: Time window too short
           nullable: true
+          readOnly: true
         time_ref_point:
           type: integer
-          nullable: true
           description: Physical reference point for all times given in shipcall and depending times entries
+          example: 1
+          nullable: true
         participants:
           type: array
+          example:
+            - participant_id: 5
+              type: 4
+            - participant_id: 6
+              type: 8
           items:
             $ref: '#/components/schemas/participant_assignment'
         created:
           type: string
           format: date-time
-          description: Readonly field set by the database
+          description: Readonly field set by the database when shipcall was created
+          example: '2023-08-21T08:23:35Z'
         modified:
           type: string
           format: date-time
+          description: Readonly field set by the database when shipcall was last modified
+          example: '2023-08-21T08:23:35Z'
           nullable: true
-          description: Readonly field set by the database
       required:
-        - id
         - ship_id
         - type
     shipcalls:
+      description: List of ship calls
       type: array
       items:
         $ref: '#/components/schemas/shipcall'
+      example:
+        - id: 6
+          ship_id: 8
+          type: arrival
+          eta: '2023-08-21T08:23:35Z'
+          voyage: Voyage 123
+          etd: '2023-08-21T08:23:35Z'
+          arrival_berth_id: 3
+          departure_berth_id: 4
+          tug_required: true
+          pilot_required: true
+          flags: 1
+          pier_side: false
+          bunkering: false
+          replenishing_terminal: false
+          replenishing_lock: false
+          draft: 10.5
+          tidal_window_from: '2023-08-21T08:23:35Z'
+          tidal_window_to: '2023-08-21T08:23:35Z'
+          rain_sensitive_cargo: false
+          recommended_tugs: 2
+          anchored: false
+          moored_lock: false
+          canceled: false
+          evaluation: yellow
+          evaluation_message: Time window too short
+          time_ref_point: 1
+          participants:
+            - participant_id: 5
+              type: 4
+            - participant_id: 6
+              type: 8
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+        - id: 7
+          ship_id: 8
+          type: departure
+          eta: '2023-08-21T08:23:35Z'
+          voyage: Voyage 123
+          etd: '2023-08-21T08:23:35Z'
+          arrival_berth_id: 3
+          departure_berth_id: 4
+          tug_required: true
+          pilot_required: true
+          flags: 1
+          pier_side: false
+          bunkering: false
+          replenishing_terminal: false
+          replenishing_lock: false
+          draft: 10.5
+          tidal_window_from: '2023-08-21T08:23:35Z'
+          tidal_window_to: '2023-08-21T08:23:35Z'
+          rain_sensitive_cargo: false
+          recommended_tugs: 2
+          anchored: false
+          moored_lock: false
+          canceled: false
+          evaluation: red
+          evaluation_message: Disagreement on time windows
+          time_ref_point: 1
+          participants:
+            - participant_id: 5
+              type: 4
+            - participant_id: 6
+              type: 8
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
     times:
       type: object
       description: 'the id parameter needs to be missing on POST and to be present on PUT (Update) calls, otherwise a 400 response will be generated'
       properties:
         id:
           type: integer
+          example: 2
         eta_berth:
           type: string
           format: date-time
           nullable: true
           description: Arrival time at berth
+          example: '2023-08-21T08:23:35Z'
         eta_berth_fixed:
           type: boolean
           nullable: true
-          description: currently unused
+          description: 'If true, the eta is fixed and cannot be changed'
+          example: true
         etd_berth:
           type: string
           format: date-time
           nullable: true
           description: departure time from berth
+          example: '2023-08-21T08:23:35Z'
         etd_berth_fixed:
           type: boolean
           nullable: true
-          description: currently unused
+          description: 'If true, the etd is fixed and cannot be changed'
+          example: true
         lock_time:
           type: string
           format: date-time
           nullable: true
           description: arrival time at lock
+          example: '2023-08-21T08:23:35Z'
         lock_time_fixed:
           type: boolean
           nullable: true
-          description: currently unused
+          description: 'If true, the lock time is fixed and cannot be changed'
+          example: true
         zone_entry:
           type: string
           format: date-time
           nullable: true
-          description: currently unused
+          description: Expected time of entry into the zone
+          example: '2023-08-21T08:23:35Z'
         zone_entry_fixed:
           type: boolean
           nullable: true
-          description: currently unused
+          description: 'If true, the zone entry time is fixed and cannot be changed'
+          example: true
         operations_start:
           type: string
           format: date-time
           nullable: true
           description: Start time for terminal operations
+          example: '2023-08-21T08:23:35Z'
         operations_end:
           type: string
           format: date-time
           nullable: true
           description: End time for terminal operations
+          example: '2023-08-21T08:23:35Z'
         remarks:
           type: string
           maxLength: 512
           nullable: true
+          description: Additional remarks
+          example: Please be aware of the strong current
         shipcall_id:
           type: integer
           description: Reference to a shipcall id
+          example: 23
         participant_id:
           type: integer
           description: Reference to a participant id
+          example: 34
         berth_id:
           type: integer
           nullable: true
           description: Reference to a berth id
+          example: 1
         berth_info:
           type: string
           nullable: true
           maxLength: 512
           description: Additional info text for berth
+          example: 200m length
         pier_side:
           description: 'true if ship is rotated, false otherwise'
           type: boolean
           nullable: true
+          example: true
         participant_type:
           type: integer
+          example: 4
         ata:
           type: string
           format: date-time
           nullable: true
-          description: can be set by mooring if actual times are different from planned
+          description: ata can be set by mooring if actual times are different from planned
+          example: '2023-08-21T08:23:35Z'
         atd:
           type: string
           format: date-time
           nullable: true
-          description: can be set by mooring if actual times are different from planned
+          description: atd can be set by mooring if actual times are different from planned
+          example: '2023-08-21T08:23:35Z'
         eta_interval_end:
           type: string
           format: date-time
           nullable: true
           description: Optional end of the interval for the times eta entry
+          example: '2023-08-21T08:23:35Z'
         etd_interval_end:
           type: string
           format: date-time
           nullable: true
           description: Optional end of the interval for the times etd entry
+          example: '2023-08-21T08:23:35Z'
         created:
           type: string
           format: date-time
-          description: Readonly field set by the database
+          description: Readonly field set by the database when times record was created
+          example: '2023-08-21T08:23:35Z'
         modified:
           type: string
           format: date-time
           nullable: true
-          description: Readonly field set by the database
+          description: Readonly field set by the database when times record was last modified
+          example: '2023-08-21T08:23:35Z'
       required:
         - shipcall_id
         - participant_id
+      example:
+        id: 2
+        eta_berth: '2023-08-21T08:23:35Z'
+        eta_berth_fixed: true
+        etd_berth: '2023-08-21T08:23:35Z'
+        etd_berth_fixed: true
+        lock_time: '2023-08-21T08:23:35Z'
+        lock_time_fixed: true
+        zone_entry: '2023-08-21T08:23:35Z'
+        zone_entry_fixed: true
+        operations_start: '2023-08-21T08:23:35Z'
+        operations_end: '2023-08-21T08:23:35Z'
+        remarks: Please be aware of the strong current
+        shipcall_id: 23
+        participant_id: 34
+        berth_id: 1
+        berth_info: 200m length
+        pier_side: true
+        participant_type: 4
+        ata: '2023-08-21T08:23:35Z'
+        atd: '2023-08-21T08:23:35Z'
+        eta_interval_end: '2023-08-21T08:23:35Z'
+        etd_interval_end: '2023-08-21T08:23:35Z'
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
     times_list:
+      description: List of times entries
       type: array
       items:
         $ref: '#/components/schemas/times'
+      example:
+        - id: 2
+          eta_berth: '2023-08-21T08:23:35Z'
+          eta_berth_fixed: true
+          etd_berth: '2023-08-21T08:23:35Z'
+          etd_berth_fixed: true
+          lock_time: '2023-08-21T08:23:35Z'
+          lock_time_fixed: true
+          zone_entry: '2023-08-21T08:23:35Z'
+          zone_entry_fixed: true
+          operations_start: '2023-08-21T08:23:35Z'
+          operations_end: '2023-08-21T08:23:35Z'
+          remarks: Please be aware of the strong current
+          shipcall_id: 23
+          participant_id: 34
+          berth_id: 1
+          berth_info: 200m length
+          pier_side: true
+          participant_type: 4
+          ata: '2023-08-21T08:23:35Z'
+          atd: '2023-08-21T08:23:35Z'
+          eta_interval_end: '2023-08-21T08:23:35Z'
+          etd_interval_end: '2023-08-21T08:23:35Z'
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+        - id: 3
+          eta_berth: '2023-08-21T08:23:35Z'
+          eta_berth_fixed: true
+          etd_berth: '2023-08-21T08:23:35Z'
+          etd_berth_fixed: true
+          lock_time: '2023-08-21T08:23:35Z'
+          lock_time_fixed: true
+          zone_entry: '2023-08-21T08:23:35Z'
+          zone_entry_fixed: true
+          operations_start: '2023-08-21T08:23:35Z'
+          operations_end: '2023-08-21T08:23:35Z'
+          remarks: Please be aware of the strong current
+          shipcall_id: 23
+          participant_id: 34
+          berth_id: 1
+          berth_info: 200m length
+          pier_side: true
+          participant_type: 4
+          ata: '2023-08-21T08:23:35Z'
+          atd: '2023-08-21T08:23:35Z'
+          eta_interval_end: '2023-08-21T08:23:35Z'
+          etd_interval_end: '2023-08-21T08:23:35Z'
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
     berth:
       type: object
       description: Ship berth used for a ship call
       properties:
         id:
           type: integer
+          example: 3
         name:
           type: string
           maxLength: 128
+          example: Pier 1
         owner_id:
           type: integer
           nullable: true
           description: Optional reference to a participant (terminal)
+          example: 5
         authority_id:
           type: integer
           nullable: true
           description: Optional reference to a participant (port authority)
+          example: 6
         lock:
           type: boolean
           nullable: true
           description: If true lock must be passed
+          example: true
         created:
+          description: Readonly field set by the database when berth was created
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
         modified:
+          description: Readonly field set by the database when berth was last modified
           type: string
           format: date-time
           nullable: true
+          example: '2023-08-21T08:23:35Z'
         deleted:
+          description: marks the berth as logically deleted
           type: boolean
           default: false
+          example: false
+      example:
+        id: 3
+        name: Pier 1
+        owner_id: 5
+        authority_id: 6
+        lock: true
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
+        deleted: false
     berth_list:
       type: array
+      description: List of berths
       items:
         $ref: '#/components/schemas/berth'
+      example:
+        - id: 3
+          name: Pier 1
+          owner_id: 5
+          authority_id: 6
+          lock: true
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+          deleted: false
+        - id: 4
+          name: Pier 2
+          owner_id: 5
+          authority_id: 6
+          lock: true
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+          deleted: false
     ship:
       type: object
       description: a ship
       properties:
         id:
           type: integer
+          example: 8
         name:
           type: string
           maxLength: 64
+          example: MS Bremen
         imo:
           type: integer
           nullable: true
+          example: 1234567
         callsign:
           type: string
           maxLength: 8
           nullable: true
+          example: DBRE
         participant_id:
           type: integer
           nullable: true
           description: Optional reference to participant (tug role)
+          example: 9
         length:
           type: number
           format: double
           nullable: true
+          example: 200
         width:
           type: number
           format: double
           nullable: true
+          example: 30
         is_tug:
           type: boolean
           default: false
+          example: false
         bollard_pull:
           type: integer
           nullable: true
+          example: 100
         eni:
           type: integer
           nullable: true
           description: BSMD internal use
+          example: 1234567
         created:
           type: string
           format: date-time
+          description: Readonly field set by the database when ship was created
+          example: '2023-08-21T08:23:35Z'
         modified:
           type: string
           format: date-time
           nullable: true
+          description: Readonly field set by the database when ship was last modified
+          example: '2023-08-21T08:23:35Z'
         deleted:
           type: boolean
           default: false
+          description: marks the ship as logically deleted
+          example: false
+      example:
+        id: 8
+        name: MS Bremen
+        imo: 1234567
+        callsign: DBRE
+        participant_id: 9
+        length: 200
+        width: 30
+        is_tug: false
+        bollard_pull: 100
+        eni: 1234567
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
+        deleted: false
     ship_list:
       type: array
+      description: List of ships
       items:
         $ref: '#/components/schemas/ship'
+      example:
+        - id: 8
+          name: MS Bremen
+          imo: 1234567
+          callsign: DBRE
+          participant_id: 9
+          length: 200
+          width: 30
+          is_tug: false
+          bollard_pull: 100
+          eni: 1234567
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+          deleted: false
+        - id: 9
+          name: MS Alfred
+          imo: 1234568
+          callsign: DBRF
+          participant_id: 9
+          length: 200
+          width: 30
+          is_tug: false
+          bollard_pull: 100
+          eni: 1234567
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+          deleted: false
     history:
       type: object
       description: Single history entry with references
       properties:
         id:
           type: integer
+          example: 3
         participant_id:
           type: integer
+          example: 5
         shipcall_id:
           type: integer
+          example: 42
         timestamp:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
         eta:
           type: string
           format: date-time
+          example: '2023-08-21T08:23:35Z'
         operation:
           $ref: '#/components/schemas/OperationType'
         type:
           $ref: '#/components/schemas/ObjectType'
+      example:
+        id: 3
+        participant_id: 5
+        shipcall_id: 42
+        timestamp: '2023-08-21T08:23:35Z'
+        eta: '2023-08-21T08:23:35Z'
+        operation: update
+        type: shipcall
     history_list:
       type: array
+      description: List of history items
       items:
         $ref: '#/components/schemas/history'
       x-stoplight:
         id: 93b5ff080c12a
+      example:
+        - id: 3
+          participant_id: 5
+          shipcall_id: 42
+          timestamp: '2023-08-21T08:23:35Z'
+          eta: '2023-08-21T08:23:35Z'
+          operation: insert
+          type: shipcall
+        - id: 4
+          participant_id: 5
+          shipcall_id: 42
+          timestamp: '2023-08-21T08:23:35Z'
+          eta: '2023-08-21T08:23:35Z'
+          operation: update
+          type: shipcall
     notification:
       type: object
       description: a notification created by the engine if a times entry violates a rule
       properties:
         id:
           type: integer
+          example: 42
         shipcall_id:
           type: integer
+          example: 5
         notification_type:
           $ref: '#/components/schemas/NotificationType'
         message:
           type: string
+          example: Entry XY violates rule Z
         created:
           type: string
           format: date-time
-          description: Readonly field set by the database
+          description: Readonly field set by the database when notification was created
+          example: '2023-08-21T08:23:35Z'
         modified:
           type: string
           format: date-time
           nullable: true
-          description: Readonly field set by the database
+          description: Readonly field set by the database when notification was last modified
+          example: '2023-08-21T08:23:35Z'
+      example:
+        id: 42
+        shipcall_id: 5
+        notification_type: email
+        message: Entry XY violates rule Z
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
+    notification_list:
+      type: array
+      description: List of notifications
+      items:
+        $ref: '#/components/schemas/notification'
+      example:
+        - id: 42
+          shipcall_id: 5
+          notification_type: email
+          message: Entry XY violates rule Z
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+        - id: 43
+          shipcall_id: 7
+          notification_type: email
+          message: Entry AB violates rule C
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
     participant:
       type: object
       description: A organisational entity that participates in Bremen Calling
       properties:
         id:
           type: integer
+          example: 42
         name:
           type: string
           maxLength: 128
+          example: BSMD
         street:
           type: string
           maxLength: 128
+          example: Hermann-Hollerith-Str. 7
         postal code:
           type: string
           maxLength: 5
+          example: '28359'
         city:
           type: string
           maxLength: 64
+          example: Bremen
         type:
           type: integer
-          description: a logical combination (bitflag) of possible values. This cannot be encoded in a Enumeration type with discrete values in OpenAPI version < 3.1. The values are 1=
+          description: a logical combination (bitflag) of possible values. This cannot be encoded in a Enumeration type with discrete values in OpenAPI version < 3.1.
+          example: 10
         flags:
+          description: Bit-encoded flag array for internal use
           type: integer
           nullable: true
+          example: 0
         created:
           type: string
           format: date-time
-          description: Readonly field set by the database
+          description: Readonly field set by the database when participant was created
+          example: '2023-08-21T08:23:35Z'
         modified:
           type: string
           format: date-time
           nullable: true
-          description: Readonly field set by the database
+          description: Readonly field set by the database when participant was last modified
+          example: '2023-08-21T08:23:35Z'
         deleted:
+          description: marks the participant as logically deleted
           type: boolean
           default: false
+          example: false
+      example:
+        id: 42
+        name: BSMD
+        street: Hermann-Hollerith-Str. 7
+        postal code: '28359'
+        city: Bremen
+        type: 10
+        flags: 0
+        created: '2023-08-21T08:23:35Z'
+        modified: '2023-08-21T08:23:35Z'
+        deleted: false
     participant_list:
+      description: List of participants
       type: array
       items:
         $ref: '#/components/schemas/participant'
+      example:
+        - id: 42
+          name: BSMD
+          street: Hermann-Hollerith-Str. 7
+          postal code: '28359'
+          city: Bremen
+          type: 10
+          flags: 0
+          created: '2023-08-21T08:23:35Z'
+          modified: '2023-08-21T08:23:35Z'
+          deleted: false
     login_result:
       type: object
       description: result structure of a successful login attempt
       properties:
         id:
           type: integer
+          example: 42
         participant_id:
           type: integer
+          example: 5
         first_name:
           type: string
+          example: John
         last_name:
           type: string
+          example: Doe
         user_name:
           type: string
+          example: johndoe
         user_phone:
           type: string
+          example: '1234567890'
         user_email:
           type: string
+          example: no@where.com
         exp:
           type: number
           format: float
+          example: 1630000000
         token:
           type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+      example:
+        id: 42
+        participant_id: 5
+        first_name: John
+        last_name: Doe
+        user_name: johndoe
+        user_phone: '1234567890'
+        user_email: no@where.com
+        exp: 1630000000
+        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
     user_details:
       type: object
       description: fields that a user may change
       properties:
         id:
           type: integer
+          example: 42
         old_password:
           type: string
           nullable: true
           maxLength: 128
+          example: oldpassword
         new_password:
           type: string
           nullable: true
           maxLength: 128
+          example: newpassword
         first_name:
           type: string
           nullable: true
           maxLength: 45
+          example: John
         last_name:
           type: string
           nullable: true
           maxLength: 45
+          example: Doe
         user_phone:
           maxLength: 128
           type: string
           nullable: true
+          example: '1234567890'
         user_email:
           maxLength: 128
           type: string
           nullable: true
+          example: no@where.com
+      example:
+        id: 42
+        old_password: oldpassword
+        new_password: newpassword
+        first_name: John
+        last_name: Doe
+        user_phone: '1234567890'
+        user_email: no@where.com
     Id:
       type: object
       description: A unique identifier for an entity
       properties:
         id:
           type: integer
+          example: 42
+      example:
+        id: 42
     Error:
       type: object
       description: Structure returned when invalid data (bad request) is created.
       properties:
-        message:
-          description: A human readable error message
+        error_field:
+          description: Input field that caused the error or general error message
           type: string
-        errors:
-          description: A list of errors
-          type: array
-          items:
-            type: string
-        valid_data:
-          description: A dictionary of valid data
-          type: object
+          example: eta
+        error_description:
+          description: Detailed description if error_field was an input field
+          type: string
+          example: eta must be in the future
       required:
-        - message
+        - error_field
+      example:
+        error_field: eta
+        error_description: eta must be in the future
     ShipcallType:
       type: string
       enum:
@@ -966,14 +1740,18 @@ components:
         - departure
         - shifting
       x-internal: false
-      description: ''
+      description: Type of ship call
+      example: arrival
     NotificationType:
       type: string
+      description: Type of notification
       enum:
         - undefined
         - email
         - push
+      example: email
     EvaluationType:
+      description: Evaluation of the ship call
       readOnly: true
       nullable: true
       type: string
@@ -982,20 +1760,26 @@ components:
         - green
         - yellow
         - red
+      example: green
     OperationType:
       type: string
+      description: Type of operation that was performed
       enum:
         - undefined
         - insert
         - update
         - delete
+      example: insert
     ObjectType:
       type: string
+      description: Type of object that was changed
       enum:
         - times
         - shipcall
+      example: times
   securitySchemes:
     ApiKey:
+      description: API key needed to access the API
       type: apiKey
       in: header
       name: Authorization
@@ -1006,48 +1790,70 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/Id'
+          example:
+            id: 42
     '201':
       description: Created
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Id'
+          example:
+            id: 42
     '400':
       description: Bad request
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: eta
+            error_description: eta must be in the future
     '401':
       description: Not authorized
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: user_id
+            error_description: User not authorized to perform this action
     '403':
       description: Forbidden
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: user_id
+            error_description: User not authorized to perform this action
     '404':
       description: Not found
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: shipcall_id
+            error_description: Ship call not found
     '500':
       description: Unexpected error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: service
+            error_description: Internal server error
     '503':
       description: Service unavailable
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            error_field: service
+            error_description: Service is currently unavailable
 security:
   - ApiKey: []
 externalDocs: