openapi: 3.0.3
info:
  title: IWG Experts API
  description: API Specification of IWG experts
  version: "1.0"
  termsOfService: https://justizonline.gv.at/jop/web/iwg/terms
  contact:
    name: Bundesministerium für Justiz
    url: https://justizonline.gv.at
    email: justizonline-iwg@brz.gv.at

servers:
  - url: https://justizonline.gv.at/jop/api/
    description: Production Server

paths:
  /v1/experts:
    get:
      tags:
        - expert-persons
      summary: List experts
      description: Get a list of experts, depending on various query and paging parameters
      operationId: listExpertsV1
      parameters:
        - name: from
          in: query
          description: Filter to include changes from date
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date
        - name: until
          in: query
          description: Filter to include changes until date
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date
        - name: type
          in: query
          description: Filter to include specific types of experts
          required: false
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/ExpertType'
        - $ref: '#/components/parameters/PageNumberParam'
        - $ref: '#/components/parameters/PageSizeParam'
      responses:
        "200":
          description: List of experts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpertPagedList'
        "404":
          description: Not found

  /v1/experts/{addressCode}:
    get:
      tags:
        - expert-persons
      summary: Get expert by addressCode
      description: Get a single Expert by its address code(Id)
      operationId: getExpertByAddressCodeV1
      parameters:
        - $ref: '#/components/parameters/ExpertAddressCodePathParam'
      responses:
        "200":
          description: Found expert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expert'
        "404":
          description: Not found
components:
  schemas:
    ExpertType:
      type: string
      enum:
        - SV
        - DO
    Person:
      required:
        - firstName
        - lastName
        - job
        - yearOfBirth
      type: object
      properties:
        firstName:
          minLength: 2
          type: string
          description: "Firstname of the expert"
          example: Max
        lastName:
          minLength: 2
          type: string
          description: "Lastname of the expert"
          example: Mustermann
        title:
          type: string
          description: "Title of the expert"
        academicTitlePreceding:
          type: string
        academicTitleAfter:
          type: string
        job:
          type: string
          maxLength: 80
          description: "Job of the expert"
        yearOfBirth:
          type: string
          minLength: 4
          maxLength: 4
          description: "Year of birth of the expert (yyyy)"
          pattern: '^\d{4}$'
    Contact:
      type: object
      required:
        - addressType
        - addressForService
      properties:
        addressType:
          type: string
          description: "Kind of address"
          enum:
            - OW
            - BT
            - SA
        addressForService:
          type: boolean
        postalCode:
          type: string
          description: "Postal code"
          example: 1030
        city:
          type: string
          description: "Name of the city"
          example: Wien
        country:
          type: string
          description: "Name of the country"
        address:
          type: string
          description: "Full address including street and house number"
        phone1:
          type: string
          description: "primary telephone number"
          maxLength: 40
        phone2:
          type: string
          description: "secondary telephone number"
          maxLength: 40
        fax:
          type: string
          description: "Fax"
          maxLength: 40
        eMail:
          type: string
          description: "E-Mail address"
          maxLength: 250
          pattern: '^(?:[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+(?:\.[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+)*)@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)$'
        additionalInfo:
          type: string
          description: "Additional information for contact"

    FieldOfWork:
      required:
        - field
        - group
      type: object
      properties:
        field:
          type: string
          description: "Subject and field of work"
        fieldNumber:
          type: string
          description: "Field number of work"
        group:
          type: string
          description: "Subject and group of work"
        onlyFor:
          type: string
          description: "Exclusive within this field of work"
        exemption:
          type: string
          description: "Exemption of the expert within this field of work"
        certification:
          $ref: '#/components/schemas/Certification'
        specialisation:
          type: string
          description: "expert specialty"
    Language:
      required:
        - language
      type: object
      properties:
        language:
          type: string
          description: "Language"
        certification:
          $ref: '#/components/schemas/Certification'
        verbalOnly:
          type: boolean
        specialisation:
          type: string
          description: "expert specialty"
        notes:
          type: string
          description: "Additional notes"
    Certification:
      type: object
      properties:
        certifiedSince:
          type: string
          format: date-time
          description: "Certified since date"
        certifiedUntil:
          type: string
          format: date-time
          description: "Certified until date"
    Subject:
      required:
        - court
      type: object
      properties:
        court:
          $ref: '#/components/schemas/Court'
        localRestrictionList:
          type: array
          description: "Local resctrictions of the expert"
          items:
            $ref: '#/components/schemas/Court'
        fieldOfWorkList:
          type: array
          description: "Subjects or fields of work with expert specialty"
          items:
            $ref: '#/components/schemas/FieldOfWork'
        languageList:
          type: array
          description: "Languages with expert specialty"
          items:
            $ref: '#/components/schemas/Language'
    Court:
      required:
        - name
        - bl
        - blName
      properties:
        code:
          type: string
        name:
          type: string
        bl:
          type: integer
          format: int32
        blName:
          type: string
    AdditionalInformation:
      properties:
        old:
          type: string
          description: 'Legacy/deprecated additional information text'
        education:
          type: string
          description: 'Education'
        career:
          type: string
          description: 'Career'
        infrastructure:
          type: string
          description: 'Available infrastructure'
        previousActivity:
          type: string
          description: 'Previous activity'
    Expert:
      required:
        - lastChange
        - addressCode
        - type
      type: object
      description: Expert object
      properties:
        lastChange:
          type: string
          description: "Date of last chance"
          format: date-time
          example: 2021-05-31
        addressCode:
          type: string
          description: "Address code of the expert"
          readOnly: true
          pattern: "W[0-9]{6}"
        homepage:
          type: string
        type:
          $ref: '#/components/schemas/ExpertType'
        status:
          type: string
          enum:
            - AVAILABLE
            - DELETED
        person:
          $ref: '#/components/schemas/Person'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
          minItems: 1
          maxItems: 2
        suspendedFrom:
          type: string
          format: date
        suspendedTo:
          type: string
          format: date
        subjectInformation:
          $ref: '#/components/schemas/Subject'
        additionalInformation:
          $ref: '#/components/schemas/AdditionalInformation'
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'

    ExpertList:
      type: array
      description: "List of experts"
      items:
        $ref: '#/components/schemas/Expert'
    ExpertPagedList:
      allOf:
        - $ref: '#/components/schemas/PagedResponse'
        - type: object
          properties:
            content:
              $ref: '#/components/schemas/ExpertList'
    Certificate:
      type: object
      properties:
        type:
          type: string
        cardNumber:
          type: string
    PagedResponse:
      type: object
      properties:
        pageable:
          $ref: '#/components/schemas/PagedResponse_pageable'
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        totalElements:
          type: integer
          format: int32
        first:
          type: boolean
    PagedResponse_pageable_sort:
      type: object
      properties:
        sorted:
          type: boolean
        unsorted:
          type: boolean
    PagedResponse_pageable:
      type: object
      properties:
        sort:
          $ref: '#/components/schemas/PagedResponse_pageable_sort'
        offset:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
  parameters:
    PageNumberParam:
      name: pageNumber
      in: query
      description: "Page number"
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        default: 1
    PageSizeParam:
      name: pageSize
      in: query
      description: "Page size"
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        default: 25
    ExpertAddressCodePathParam:
      name: addressCode
      in: path
      description: "Unique address code of an expert"
      required: true
      style: simple
      explode: false
      schema:
        type: string


  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: '....'

security:
  - api_key: [ ]