swagger: '2.0'
info:
  version: 1.0.0
  title: 'Koulutukset, opetussuunnitelmat/Opintojaksot ja niiden toteutukset API'
  description: >
    Koulutukset, (opetussuunnitelmat, tutkinnot, curriculum) -rajapinta sisältää
    opetussuunnitelman kuvaustiedot, tiedot ajoitussuunnitelmista ja
    opintopoluista. Opintojaksot (Learning Opportunity Specification,
    courseunit) -rajapinta sisältää opintojaksojen kuvaustiedot. Opintojaksojen
    toteutukset (Learning Opportunity Instance,realization)- sisältää
    opintojaksojen toteutusten tiedot.
  contact:
    name: Pekka Järveläinen
    email: pj@csc.fi
  license:
    name: CC0
    url: 'https://creativecommons.org/licenses/by/4.0/'
consumes:
  - application/json
produces:
  - application/json
basePath: /v1
paths:
  /curriculum/:
    get:
      description: Käytettävissä olevat hakukentät
      operationId: curriculumsearch
      produces:
        - application/json
      parameters:
        - name: nameOrCodesOrStructureViews
          in: body
          description: Opetussuunnitelman nimi tai koodilista
          required: true
          schema:
            $ref: '#/definitions/nimiOrCodesOrStructureViews'
      responses:
        '200':
          description: programmes
          schema:
            $ref: '#/definitions/curriculumresponse'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
  /learningOpportunity/specification:
    get:
      description: Käytettävissä olevat hakukentät
      operationId: specificationsearch
      produces:
        - application/json
      parameters:
        - name: nameOrCode
          in: body
          description: Name of the course | List of codes for course units
          schema:
            $ref: '#/definitions/nimiOrCodes'
      responses:
        '200':
          description: LearningOpportunitySpecification
          schema:
            $ref: '#/definitions/learningOpportunitySpecification'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
  /LearningOpportunity/instance:
    get:
      description: Käytettävissä olevat hakukentät
      operationId: instanceSearch
      produces:
        - application/json
      parameters:
        - name: nameOrCodeOrDates
          in: body
          description: >-
            Toteutuksen nimi |  Lista opintojaksojen toteutuksien koodeja |
            startDate endDate
          schema:
            $ref: '#/definitions/nimiOrCodesOrDates'
      responses:
        '200':
          description: Learning Opportunity Instance
          schema:
            $ref: '#/definitions/instanceresponse'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
definitions:
  instanceresponse:
    type: object
    properties:
      LearningOpportunityInstance:
        $ref: '#/definitions/learningOpportunityInstance'
      message:
        type: string
  curriculumresponse:
    type: object
    properties:
      programmes:
        type: array
        items:
           $ref: '#/definitions/koulutus'
      message:
        type: string
  learningOpportunitySpecificationArray:
    type: array
    items:
      $ref: '#/definitions/learningOpportunitySpecification'
  learningOpportunitySpecification:
    type: object
    required:
      - id
      - description
      - title
      - specifies
    properties:
      id:
        type: string
      description:
        type: array
        items:
          type: string
        description: JSON käytäntö on kysyä kukin kieli erikseen, eli array turha, nyt rdf:langString
      title:
        type: array
        items:
          type: string
      type:
        type: string
        description: "Degree Programme, 'ProgrammeYear', Module, Course, 'CourceUnit', Class, 'Arvioinnin kohde'"
      subjectArea:
        type: string
      iscedCode:
        type: string
      url:
        type: string
      specifies:
        $ref: '#/definitions/learningOpportunityInstance'
        description: pakollinen, Samin kommentti 1
      hasPart:
        $ref: '#/definitions/learningOpportunitySpecificationArray'
      extension:
        $ref: '#/definitions/m2'
  m2:
    type: object
    required:
      - arvostelu
      - laajuus
      - suoritustavat
      - tavoitteet
      - sisältö
      - vastuuorganisaatio
      - toteutustavat
    properties:
      arvostelu:
        $ref: '#/definitions/arvostelu'
      laajuus:
        type: number
        format: float
        description: 'Opintopisteet, Amount of study credits. Oletusarvo M2.4.2'
      laajuusMin:
        type: number
        format: float
        description: 'Opintopisteet, Amount of study credits. Minimiarvo M2.4.3'
      laajuusMax:
        type: number
        format: float
        description: 'Opintopisteet, Amount of study credits. Maksimiarvo M2.4.4'
      laajuusSelite:
        type: string
        description: 'M2 1.4.5 & 2.4.5 Mittaustapa jätetty pois koska ELMO credit, jossa se on'
      suoritustavat:
        $ref: '#/definitions/suoritustavat'
      tavoitteet:
        type: string
        description: 'M2 1.13'
      sisältö:
        type: string
        description: 'M2 1.14'
      vastuuorganisaatio:
        $ref: '#/definitions/organisaatioviittaus'
      avainsanat:
        type: string
        description: 'M2 1.11'
      edellytykset:
        type: string
      lisätietoja:
        type: string
      opettajat:
         $ref: '#/definitions/henkilöviittaus'
      opetuskielet:
        type: string
        description: 'fi,sv,en... ISO 639 teachingLanguage'
      suorituskielet:
        type: string
        description: 'fi,sv,en... ISO 639' 
      oppimateriaalit:
        type: array
        items:
          $ref: '#/definitions/materiaali'
      tarjontatieto:
        type: array
        items:
          type: string
          enum:
            - JOO-opinto
            - AMK-yhteistyöopinnot
            - Vaihto-opinto
            - Avoin yliopisto
            - Avoin ammattikorkekoulu
        description: 1.1.4
      yhteistyöverkosto:
        type: array
        items:
           $ref: '#/definitions/yhteistyoverkosto'
      ryhmäkoko:
        type: number
        format: int32
        description: 2.6.4 Suurin osallistuja määrä
      toteutustavat:
        $ref: '#/definitions/toteutustavat'
      ilmoittautumisenalkuaika:
        type: string
        format: date
        description: 2.10.1
      ilmoittautumisenloppuaika:
        type: string
        format: date
        description: 2.10.2
  materiaali:
    type: object
    properties:
      merkintäjärjestelmä:
        type: string
        description: M2 taulukko 6 1.1.1
        enum:
          - ISBN
          - URI
      tunnus:
        type: string
        description: M2 taulukko 6 1.1.2
      nimike:
        type: string
        description: M2 taulukko 6 1.2
      tekijä:
        type: string
        description: M2 taulukko 6 1.3
      julkaisija:
        type: string
        description: M2 taulukko 6 1.4
      julkaisuaika:
        type: string
        description: M2 taulukko 6 1.5
      kuvaus:
        type: string
        description: M2 taulukko 6 1.6
      rooli:
        type: string
        description: M2 taulukko 6 1.7
        enum:
          - Tentittävä
          - Ennen luettava
          - Oheismateriaali
      lisätietoja:
        type: string
        description: M2 taulukko 6 1.8
    description: jos merkintäjärjestelmä ja tunnus täytetty, muut voi jättää tyhiksi
  toteutustavat:
    type: array
    items:
      $ref: '#/definitions/toteutustapa'
  toteutustapa:
    type: object
    required:
      - toteutus
    properties:
      toteutus:
        type: string
        description: M2 taulukko 5 1.1
        enum:
          - Luento-opetus
          - Pienryhmäopetus
          - Yksilöopetus
          - Ryhmätyöskentely
          - Itsenäinen työskentely
      yksikkö:
        type: string
        description: M2 taulukko 5 1.2.1
        enum:
          - Tunti
          - Prosentti
      määrä:
        type: integer
        format: int32
        description: M2 taulukko 5 1.2.2
      ajankohdatjapaikat:
        $ref: '#/definitions/ajankohdatjapaikat'
      verkkotyöskentelynosuus:
        type: number
        format: int
        description: 2.8.2 Vaatii etätyöskentelyä %
    description: 2.8 opetuksen toteutustavat
  suoritustavat:
    type: array
    items:
      $ref: '#/definitions/suoritustapa'
  suoritustapa:
    type: object
    required:
      - tapa
    properties:
      id:
        type: integer
        format: int64
        description: ei pakollinen??? Halutaanko jakaa???
      tapa:
        type: string
        description: M2 taulukko 4 1.1 lisätty Exam!
        enum:
          - Kirjallinen tentti
          - Exam-tentti
          - Suullinen tentti
          - Essee
          - Harjoitustyö
          - Tutkielma
          - Projekti
          - Työharjoittelu
          - Portfolio
          - Oppimispäiväkirja
          - Osallistuminen opetukseen
          - Seminaari
          - Näyttökoe
      arvosteluasteikko:
        $ref: '#/definitions/arvostelu'
      selite:
        type: string
        description: M2 taulukko 4 1.4
      ajankohdatjapaikat:
        $ref: '#/definitions/ajankohdatjapaikat'
  ajankohdatjapaikat:
    type: array
    items:
      $ref: '#/definitions/ajankohtajapaikka'
    description: M2 taulukot 4 ja 5 kohdat 1.3 
  ajankohtajapaikka:
    type: object
    properties:
      alkuaika:
        type: string
        format: dateTime
        description: M2 taulukko 4 1.3.1
      loppuaika:
        type: string
        format: dateTime
        description: M2 taulukko 4 1.3.2
      paikka:
        type: string
        description: M2 taulukko 4 1.3.3
      pakollisuus:
        type: boolean
        description: M2 taulukko 4 1.3.4 typpi Poikkeaa M2sta
      linkki:
        type: string
        description: URL ilmoittautumisosoiteeseen M2 taulukko 4 1.3.5
      Lisätietoja:
        type: string
        description: M2 taulukko 4 1.3.6
  arvostelu:
    type: object
    properties:
      arvosteluasteikko:
        type: object
        description:  >-
          https://confluence.csc.fi/display/VIRTA/Tietovarannon+koodistot#Tietovarannonkoodistot-Arvosana-asteikot,Vitsordsskalor
          M2 taulukko 4 1.2
          EvaluationType.Numerical or Enumerated or system or Grading table
          based on the ECTS Grading Table (EGT)
        properties:
          asteikko:
            type: string
            enum:
              - Viisiportainen
              - Hyväksytty
              - Toinen kotimainen
              - Näytetyö
              - Tutkielma
              - EGT
              - EiKäytössä
              - Muu
            description: EGT = ECTS Grading Table 
          arvosana:
            type: string
            enum:
              - HYV
              - 1
              - 2
              - 3
              - 4
              - 5
              - TT
              - HT
              - KH
              - A
              - B
              - N
              - C
              - M
              - E
              - L
              - Arvosana ei käytössä
            description: kaikki yhdistelmät eivät ole laillisia, noudatettava virta määristystä
          egt:
            type: string
            description: vain tämä saa olla vapaa merkkijono
      selite:
        type: string
        description: M2 taulukko 4 1.2.2 
  organisaatioviittaus:
    type: object
    required:
      - roolit
      - kohde
    properties:
      roolit:
        type: array
        items: 
          type: string
          description: M2 taulukko 8 1.1
          enum:               
            - Päävastuullinen
            - Opetussuunnitelmasta vastaava Järjestävä
            - Toteuttava
            - Hyväksyvä
            - Yhteistyötä koordinoiva
            - Muu
      kohde:
        $ref: '#/definitions/organisaatio'
      selite:
        type: string
        description: M2 taulukko 8 1.3
  henkilöviittaus:
    type: object
    required:
      - roolit
      - kohde
    properties:
      roolit:
        type: array
        items: 
          type: string
          enum:            
            - Opettaja
            - Vastaava opettaja
            - Tuutori
            - Opiskelija
            - Tukihenkilö
            - Yhteyshenkilö
            - Muu henkilö
          description: M2 taulukko 7 1.1
      kohde:
        $ref: '#/definitions/henkilö'
      selite:
        type: string
        description: M2 taulukko 7 1.3
  henkilö:
    type: object
    required:
      - tunniste
    properties:
          tunniste:
            type: string
            description: M2 3.1.1.1 Oid
          henkilötunnus:
            type: string
            description: M2 3.1.1.2 Ehdottomasti ei pakollinen, konsultoi juristia ennen käyttöä
          nimike:
            type: string
            description: M2 3.1.2 Pakollinen, jos ei nimeä!
          etunimi:
            type: string
            description: M2 3.1.3 Pakollinen, jos ei nimikettä!
          sukunimi:
            type: string
            description: M2 3.1.4 Pakollinen, jos ei nimikettä!
          sähköposti:
            type: string
            description: M2 3.1.5
          verkkosivu:
            type: string
            description: M2 3.1.6 URL
          puhelin:
            type: string
            description: M2 3.1.7
          organisaatio:
            $ref: '#/definitions/organisaatio'
  organisaatio:
    type: object
    required:
      - tunniste
      - organisaation nimi
    properties:
      tunniste:
        type: string
        description: Seppo kommentoi oid, M2 tilaskokeskuksen koodi???
      organisaation nimi:
        type: string
        description: M2 4.1.2
      yksikön nimi:
        type: string
        description: M2 4.1.3 "Lääketieteellinen tiedekunta"
      nimiselite:
        type: string
        description: M2 4.1.4 "Patologian laitos"
      postiosoite:
        $ref: '#/definitions/osoite'
      käyntiosoite:
        $ref: '#/definitions/osoite'
      puhelin:
        $ref: '#/definitions/puhelin'
  osoite:
    type: object
    properties:
      katu:
        type: string
        description: M2 4.1.5/6.1
      postinumero:
        type: number
        format: int32
        description: M2 4.1.5/6.2
      postitoimipaikka:
        type: string
        description: M2 4.1.5/6.3
      maa:
        type: string
        description: M2 4.1.5/6.4
  puhelin:
    type: object
    required:
      - numero
    properties:
      numero:
        type: string
        description: M2 4.1.7.1
      selite:
        type: string
        description: M2 4.1.7.2 "esim. kanslia"
  yhteistyoverkosto:
    type: object
    required:
      - tunnus
      - nimi
    properties:
      tunnus:
        type: string
        description: URI M2 1.1.5.1
      nimi:
        type: string
        description: M2 1.1.5.2
  koulutus:
    type: object
    required:
      - id
      - code
      - name
      - content
      - furtherInformation
      - tyyppi
    properties:
      id:
        type: string
      code:
        type: string
      name:
        type: string
      content:
        type: string
        description: sisältö M1 4.9
      furtherInformation:
        type: string
        description: lisätietoja 
      duration:
        type: number
        description: laajuus 4.4
      courseUnit:
        $ref: '#/definitions/learningOpportunitySpecificationArray'
      specialisationOptions:
        type: array
        items:
          type: string
        description: viittauksia koulutusolioihin=opintokokonaisuudet, opintosuunnat ym. ohjelmat
      structure:
        type: array
        items:
          type: string
        description: viittauksia koulutusolioihin=opintokokonaisuudet, opintosuunnat ym. ohjelmat
      tyyppi:
        type: string
  learningOpportunityInstance:
    type: object
    required:
      - id
      - title
      - startDate
      - dateFinished
      - languageOfInstruction
      - credit
    properties:
      id:
        type: string
      code:
        type: string
      title:
        type: string
      startDate:
        type: string
        format: date-time
      dateFinished:
        type: string
        format: date-time
      enrollmentStart:
        type: string
        format: date-time
      enrollmentEnd:
        type: string
        format: date-time
      languageOfInstruction:
        type: string
        description: teaching language, fi, sv, en ISO 639 - 2. Päällekkäin M2. 2.3.1 jätetäänkö pois??? 
      credit:
        $ref: '#/definitions/credit'
      Academic Term:
        $ref: '#/definitions/AcademicTerm'
      result:
        type: string
        description: 'Ei ole mielekäs tarjonnassa, oppijan suoritys, ei väliä kun ei pakollinen'
      engagementHours:
        type: number
        description: studentWorkload
      extension:
        $ref: '#/definitions/m2'
  credit:
    type: object
    required:
      - scheme
      - value
    properties:
      scheme:
        type: string
        description: ECTS = opintopiste
        enum:
          - ECTS
      level:
        type: string
        description: 'Huom: ei pakollinen, ulkomaalaiset ei noudata seuraavaa rajoitetta!!!'
        enum:
          - Bachelor
          - Master
          - PhD
      value:
        type: number
        format: float
  AcademicTerm:
    type: object
    required:
      - title
      - startDate
      - endDate
    properties:
      title:
        type: string
      startDate:
        type: string
        format: date
      endDate:
        type: string
        format: date
  nimi:
    type: object
    required:
      - name
    properties:
      name:
        type: string
  codes:
    type: array
    items:
      type: string
  nimiOrCodes:
    type: object
    properties:
      name:
        type: string
      codes:
        type: array
        items:
          type: string
  specialisationStructureViews:
    type: array
    items:
      type: string
  accomplishmentPlanStructureViews:
    type: array
    items:
      type: string
  nimiOrCodesOrStructureViews:
    type: object
    properties:
      name:
        type: string
      codes:
        $ref: '#/definitions/codes'
      specialisationStructureViews:
        $ref: '#/definitions/specialisationStructureViews'
      accomplishmentPlanStructureViews:
        $ref: '#/definitions/accomplishmentPlanStructureViews'
  nimiOrCodesOrDates:
    type: object
    properties:
      name:
        type: string
      codes:
        $ref: '#/definitions/codes'
      startDate:
        type: string
        format: date
      endDate:
        type: string
        format: date
  errorModel:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
