2.x

openapi/occapi_v2.yaml

@@ -1,6 +1,6 @@
 openapi: 3.1.0
 info:
-  version: 2.0.0-dev
+  version: 2.0.0-alpha
   title: Open Course Catalogue API
   termsOfService: ''
   contact:
@@ -13,14 +13,11 @@ info:
     url: 'https://uni-foundation.eu/wp-content/uploads/2019/04/EUF-1.png'
   description:
     $ref: ./v2/info-description.md
-# externalDocs:
-#   description: Find out how to create a GitHub repo for your OpenAPI definition.
-#   url: 'https://github.com/Rebilly/generator-openapi-repo'
 tags:
-  - name: API provider
-    description: Information about the provider.
+  - name: API server
+    description: Information about the server.
   - name: Institution
-    description: Information about the Institutions covered by the provider.
+    description: Information about the Institutions covered by the server.
   - name: Organisational Unit
     description: Information about Organisational Units in an Institution.
   - name: Programme
@@ -30,41 +27,45 @@ tags:
       Information about Courses offered by an Institution.
 
       _Course_ resources include a JSON:API _meta_ object containing information
-       about the relation between each Course and all or specific Programmes.
-  # - name: Tag
+       about the relation between each Course and specific Programmes.
+  - name: Course instance
+    description: |
+      Information about instances of Courses offered by an Institution.
+
+      _Course instance_ resources are directly linked to _Course_ resources.
 servers:
   - url: '/occapi/v2'
     description: Sandbox server (example data)
 paths:
   /:
-    $ref: paths/root.yaml
+    $ref: v2/paths/root.yaml
   # Institution & Organisational Unit endpoints.
   /hei:
-    $ref: paths/hei.yaml
+    $ref: v2/paths/hei.yaml
   '/hei/{heiId}':
-    $ref: 'paths/hei@{heiId}.yaml'
+    $ref: 'v2/paths/hei@{heiId}.yaml'
   '/hei/{heiId}/ounit':
-    $ref: 'paths/ounit.yaml'
+    $ref: 'v2/paths/ounit.yaml'
   '/hei/{heiId}/ounit/{id}':
-    $ref: 'paths/ounit@{id}.yaml'
+    $ref: 'v2/paths/ounit@{id}.yaml'
   # Programme endpoints.
   '/hei/{heiId}/programme':
-    $ref: 'paths/programme.yaml'
+    $ref: 'v2/paths/programme.yaml'
   '/hei/{heiId}/ounit/{id}/programme':
-    $ref: 'paths/ounit@{id}-programme.yaml'
+    $ref: 'v2/paths/ounit@{id}-programme.yaml'
   '/hei/{heiId}/programme/{id}':
-    $ref: 'paths/programme@{id}.yaml'
+    $ref: 'v2/paths/programme@{id}.yaml'
   # Course endpoints.
   '/hei/{heiId}/course':
-    $ref: 'paths/course.yaml'
+    $ref: 'v2/paths/course.yaml'
   '/hei/{heiId}/ounit/{id}/course':
-    $ref: 'paths/ounit@{id}-course.yaml'
+    $ref: 'v2/paths/ounit@{id}-course.yaml'
   '/hei/{heiId}/programme/{id}/course':
-    $ref: 'paths/programme@{id}-course.yaml'
+    $ref: 'v2/paths/programme@{id}-course.yaml'
   '/hei/{heiId}/course/{id}':
-    $ref: 'paths/course@{id}.yaml'
-  # Exanples
-  # '/path':
-  #   $ref: 'paths/path-item.yaml'
-  # '/path/example':
-  #   $ref: 'paths/path-item-with-examples.yaml'
+    $ref: 'v2/paths/course@{id}.yaml'
+  # Course instance endpoints.
+  '/hei/{heiId}/course/{id}/instance':
+    $ref: 'v2/paths/course@{id}-instance.yaml'
+  '/hei/{heiId}/instance/{id}':
+    $ref: 'v2/paths/instance@{id}.yaml'

openapi/v2/components/README.md

@@ -0,0 +1,14 @@
+Reusable components
+===========
+
+* You can create the following folders here:
+  - `schemas` - reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject)
+  - `responses` - reusable [Response Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject)
+  - `parameters` - reusable [Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject)
+  - `examples` - reusable [Example Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#exampleObject)
+  - `headers` - reusable [Header Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#headerObject)
+  - `requestBodies` - reusable [Request Body Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject)
+  - `links` - reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject)
+  - `callbacks` - reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject)
+  - `securitySchemes` - reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject)
+* Filename of files inside the folders represent component name, e.g. `Customer.yaml`

openapi/v2/components/headers/ExpiresAfter.yaml

@@ -0,0 +1,4 @@
+description: date in UTC when token expires
+schema:
+  type: string
+  format: date-time

openapi/v2/components/responses/CourseCollection.yaml

@@ -0,0 +1,76 @@
+jsonapi:
+  version: "1.1"
+  meta:
+    links:
+      self:
+        href: "http://jsonapi.org/format/1.1/"
+data:
+  - type: course
+    id: aabbccdd-eeff-1122-3344-556677889900
+    attributes:
+      title:
+        - string: Example Course
+          lang: en
+      code: COUR01
+      ects: 7.5
+      academicTerm:
+        - '1/2'
+      description:
+        - multiline: |
+            This is the description of the Course.
+
+            This is a long text field.
+          lang: en
+      elmAssessmentType:
+        - 3484bd7e51
+        - d30284d7df
+        - 6e6cb2cc78
+      elmLearningActivityType:
+        - ff436ea7c9
+        - 3c8bd58d62
+      elmLearningOpportunityType:
+        - 05053c1cbe
+      elmModeOfLearning:
+        - e92d221e4d
+      iscedCode:
+        - '0000'
+      languageOfInstruction:
+        - en
+      learningOutcomes:
+        - multiline: |
+            These are the learning outcomes of the Course.
+
+            This is a long text field.
+          lang: en
+      localClassification:
+        - classificationSystem: 'erasmus'
+          classificationValue: '00.0'
+      restrictedToLocalStudents: false
+      restrictedToAllianceStudents: true
+      url:
+        - uri: www.domain.tld/example/course
+          lang: en
+      lastModified: 2025-09-01T12:00:00Z
+      deprecated: false
+    meta:
+      relatedProgramme:
+        - programmeId: abcdef12-3456-7890-abcd-ef1234567890
+          mandatoryCourse: true
+          year: '1/2'
+    relationships:
+      prerequisiteCourse: []
+      relatedProgramme:
+        - data:
+            type: programme
+            id: abcdef12-3456-7890-abcd-ef1234567890
+          links:
+            self:
+              href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890'
+    links:
+      self:
+        href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900'
+      instance:
+        href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900/instance'
+links:
+  self:
+    href: 'http://example.com/occapi/v2/hei/domain.tld/course'

openapi/v2/components/responses/CourseInstanceCollection.yaml

@@ -0,0 +1,25 @@
+jsonapi:
+  version: "1.1"
+  meta:
+    links:
+      self:
+        href: "http://jsonapi.org/format/1.1/"
+data:
+  - type: instance
+    id: 13579bdf-0246-8ace-1357-9bdf02468ace
+    attributes:
+      lastModified: 2025-09-01T12:00:00Z
+    relationships:
+      course:
+        data:
+          type: course
+          id: aabbccdd-eeff-1122-3344-556677889900
+        links:
+          self:
+            href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900'
+    links:
+      self:
+        href: 'http://example.com/occapi/v2/hei/domain.tld/instance/13579bdf-0246-8ace-1357-9bdf02468ace'
+links:
+  self:
+    href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900/instance'

openapi/v2/components/responses/CourseInstanceResource.yaml

@@ -0,0 +1,42 @@
+jsonapi:
+  version: "1.1"
+  meta:
+    links:
+      self:
+        href: "http://jsonapi.org/format/1.1/"
+data:
+  type: instance
+  id: 13579bdf-0246-8ace-1357-9bdf02468ace
+  attributes:
+    startDate: 2025-02-01
+    endDate: 2025-06-30
+    academicTermId: 2025/2026-2/2
+    ects: 7.5
+    elmAssessmentType:
+      - 3484bd7e51
+      - 6e6cb2cc78
+    elmLearningActivityType:
+      - ff436ea7c9
+      - 3c8bd58d62
+    elmLearningOpportunityType:
+      - 05053c1cbe
+    elmModeOfLearning:
+      - e92d221e4d
+    engagementHours: 42
+    languageOfInstruction:
+      - en
+    lastModified: 2025-09-01T12:00:00Z
+  relationships:
+    course:
+      data:
+        type: course
+        id: aabbccdd-eeff-1122-3344-556677889900
+      links:
+        self:
+          href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900'
+  links:
+    self:
+      href: 'http://example.com/occapi/v2/hei/domain.tld/instance/13579bdf-0246-8ace-1357-9bdf02468ace'
+links:
+  self:
+    href: 'http://example.com/occapi/v2/hei/domain.tld/instance/13579bdf-0246-8ace-1357-9bdf02468ace'

openapi/v2/components/responses/CourseResource.yaml

@@ -0,0 +1,112 @@
+jsonapi:
+  version: "1.1"
+  meta:
+    links:
+      self:
+        href: "http://jsonapi.org/format/1.1/"
+data:
+  type: course
+  id: aabbccdd-eeff-1122-3344-556677889900
+  attributes:
+    title:
+      - string: Example Course
+        lang: en
+    code: COUR01
+    ects: 7.5
+    academicTerm:
+      - '1/2'
+    description:
+      - multiline: |
+          This is the description of the Course.
+
+          This is a long text field.
+        lang: en
+    elmAssessmentType:
+      - 3484bd7e51
+      - d30284d7df
+      - 6e6cb2cc78
+    elmLearningActivityType:
+      - ff436ea7c9
+      - 3c8bd58d62
+    elmLearningOpportunityType:
+      - 05053c1cbe
+    elmModeOfLearning:
+      - e92d221e4d
+    iscedCode:
+      - '0000'
+    languageOfInstruction:
+      - en
+    learningOutcomes:
+      - multiline: |
+          These are the learning outcomes of the Course.
+
+          This is a long text field.
+        lang: en
+    localClassification:
+      - classificationSystem: 'erasmus'
+        classificationValue: '00.0'
+    restrictedToLocalStudents: false
+    restrictedToAllianceStudents: true
+    url:
+      - uri: www.domain.tld/example/course
+        lang: en
+    bibliography:
+      - multiline: |
+          This is the bibliography of the Course.
+
+          This is a long text field.
+        lang: en
+    courseContent:
+      - multiline: |
+          this is the content outline of the Course.
+
+          This is a long text field.
+        lang: en
+    prerequisites:
+      - multiline: |
+          These are the prerequisites of the Course.
+
+          This is a long text field.
+        lang: en
+    courseAvailability:
+      - multiline: |
+          These are other factors impacting enrollment in the Course.
+
+          This is a long text field.
+        lang: en
+    teachingMethod:
+      - multiline: |
+          This is the teaching method for the Course.
+
+          This is a long text field.
+        lang: en
+    assessmentMethod:
+      - multiline: |
+          This is the assessment method for the Course.
+
+          This is a long text field.
+        lang: en
+    lastModified: 2025-09-01T12:00:00Z
+    deprecated: false
+  meta:
+    relatedProgramme:
+      - programmeId: abcdef12-3456-7890-abcd-ef1234567890
+        mandatoryCourse: true
+        year: '1/2'
+  relationships:
+    prerequisiteCourse: []
+    relatedProgramme:
+      - data:
+          type: programme
+          id: abcdef12-3456-7890-abcd-ef1234567890
+        links:
+          self:
+            href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890'
+  links:
+    self:
+      href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900'
+    instance:
+      href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900/instance'
+links:
+  self:
+    href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900'

openapi/v2/components/responses/EndpointNotAvailable.yaml

@@ -0,0 +1,9 @@
+jsonapi:
+  version: "1.1"
+  meta:
+    links:
+      self:
+        href: "http://jsonapi.org/format/1.1/"
+errors:
+  - status: "404"
+    title: Endpoint not available.