From 5f754c65527a50b7b622d2b2907b6cf68ed8bc19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Fri, 5 Sep 2025 15:51:03 +0200 Subject: [PATCH 01/23] New file tree for v2; fixes #45 Switch to IETF BCP 47 language tags --- openapi/occapi_v2.yaml | 28 ++-- openapi/v2/components/README.md | 14 ++ .../v2/components/headers/ExpiresAfter.yaml | 4 + .../responses/CourseCollection.yaml | 50 ++++++ .../components/responses/CourseResource.yaml | 86 ++++++++++ .../responses/EndpointNotAvailable.yaml | 9 + .../responses/InstitutionCollection.yaml | 24 +++ .../responses/InstitutionResource.yaml | 30 ++++ .../components/responses/OunitCollection.yaml | 25 +++ .../responses/OunitCourseCollection.yaml | 49 ++++++ .../responses/OunitProgrammeCollection.yaml | 34 ++++ .../components/responses/OunitResource.yaml | 29 ++++ openapi/v2/components/responses/Problem.yaml | 5 + .../responses/ProgrammeCollection.yaml | 34 ++++ .../responses/ProgrammeCourseCollection.yaml | 49 ++++++ .../responses/ProgrammeResource.yaml | 36 ++++ .../responses/ResourceNotFound.yaml | 9 + openapi/v2/components/responses/Root.yaml | 12 ++ .../components/schemas/CourseCollection.yaml | 27 +++ openapi/v2/components/schemas/CourseData.yaml | 99 +++++++++++ .../schemas/CourseDataExtended.yaml | 129 +++++++++++++++ openapi/v2/components/schemas/CourseMeta.yaml | 50 ++++++ .../v2/components/schemas/CourseResource.yaml | 25 +++ .../components/schemas/DescriptionLang.yaml | 4 + openapi/v2/components/schemas/Email.yaml | 4 + openapi/v2/components/schemas/Error.yaml | 32 ++++ .../schemas/HttpWithOptionalLang.yaml | 10 ++ .../schemas/InstitutionCollection.yaml | 27 +++ .../components/schemas/InstitutionData.yaml | 40 +++++ .../schemas/InstitutionResource.yaml | 66 ++++++++ openapi/v2/components/schemas/Jsonapi.yaml | 34 ++++ openapi/v2/components/schemas/Lang.yaml | 19 +++ .../components/schemas/LinksCollection.yaml | 8 + .../v2/components/schemas/LinksResource.yaml | 8 + openapi/v2/components/schemas/LinksSelf.yaml | 8 + .../MultilineStringWithOptionalLang.yaml | 9 + .../components/schemas/OunitCollection.yaml | 27 +++ openapi/v2/components/schemas/OunitData.yaml | 42 +++++ .../v2/components/schemas/OunitResource.yaml | 48 ++++++ openapi/v2/components/schemas/Problem.yaml | 39 +++++ .../schemas/ProgrammeCollection.yaml | 27 +++ .../v2/components/schemas/ProgrammeData.yaml | 76 +++++++++ .../components/schemas/ProgrammeResource.yaml | 36 ++++ openapi/v2/components/schemas/Root.yaml | 27 +++ openapi/v2/components/schemas/Schema.yaml | 154 ++++++++++++++++++ .../schemas/StringWithOptionalLang.yaml | 9 + openapi/v2/components/schemas/User.yaml | 19 +++ .../components/securitySchemes/api_key.yaml | 3 + .../securitySchemes/basic_auth.yaml | 2 + .../components/securitySchemes/main_auth.yaml | 7 + openapi/v2/paths/README.md | 105 ++++++++++++ openapi/v2/paths/course.yaml | 37 +++++ openapi/v2/paths/course@{id}.yaml | 47 ++++++ openapi/v2/paths/echo.yaml | 54 ++++++ openapi/v2/paths/hei.yaml | 35 ++++ openapi/v2/paths/hei@{heiId}.yaml | 44 +++++ openapi/v2/paths/ounit.yaml | 40 +++++ openapi/v2/paths/ounit@{id}-course.yaml | 44 +++++ openapi/v2/paths/ounit@{id}-programme.yaml | 44 +++++ openapi/v2/paths/ounit@{id}.yaml | 48 ++++++ openapi/v2/paths/path-item-with-examples.yaml | 43 +++++ openapi/v2/paths/path-item.yaml | 34 ++++ openapi/v2/paths/programme.yaml | 37 +++++ openapi/v2/paths/programme@{id}-course.yaml | 44 +++++ openapi/v2/paths/programme@{id}.yaml | 45 +++++ openapi/v2/paths/root.yaml | 29 ++++ openapi/v2/paths/users@{username}.yaml | 81 +++++++++ public/v2/openapi.yaml | 16 +- 68 files changed, 2452 insertions(+), 17 deletions(-) create mode 100644 openapi/v2/components/README.md create mode 100644 openapi/v2/components/headers/ExpiresAfter.yaml create mode 100644 openapi/v2/components/responses/CourseCollection.yaml create mode 100644 openapi/v2/components/responses/CourseResource.yaml create mode 100644 openapi/v2/components/responses/EndpointNotAvailable.yaml create mode 100644 openapi/v2/components/responses/InstitutionCollection.yaml create mode 100644 openapi/v2/components/responses/InstitutionResource.yaml create mode 100644 openapi/v2/components/responses/OunitCollection.yaml create mode 100644 openapi/v2/components/responses/OunitCourseCollection.yaml create mode 100644 openapi/v2/components/responses/OunitProgrammeCollection.yaml create mode 100644 openapi/v2/components/responses/OunitResource.yaml create mode 100644 openapi/v2/components/responses/Problem.yaml create mode 100644 openapi/v2/components/responses/ProgrammeCollection.yaml create mode 100644 openapi/v2/components/responses/ProgrammeCourseCollection.yaml create mode 100644 openapi/v2/components/responses/ProgrammeResource.yaml create mode 100644 openapi/v2/components/responses/ResourceNotFound.yaml create mode 100644 openapi/v2/components/responses/Root.yaml create mode 100644 openapi/v2/components/schemas/CourseCollection.yaml create mode 100644 openapi/v2/components/schemas/CourseData.yaml create mode 100644 openapi/v2/components/schemas/CourseDataExtended.yaml create mode 100644 openapi/v2/components/schemas/CourseMeta.yaml create mode 100644 openapi/v2/components/schemas/CourseResource.yaml create mode 100644 openapi/v2/components/schemas/DescriptionLang.yaml create mode 100644 openapi/v2/components/schemas/Email.yaml create mode 100644 openapi/v2/components/schemas/Error.yaml create mode 100644 openapi/v2/components/schemas/HttpWithOptionalLang.yaml create mode 100644 openapi/v2/components/schemas/InstitutionCollection.yaml create mode 100644 openapi/v2/components/schemas/InstitutionData.yaml create mode 100644 openapi/v2/components/schemas/InstitutionResource.yaml create mode 100644 openapi/v2/components/schemas/Jsonapi.yaml create mode 100644 openapi/v2/components/schemas/Lang.yaml create mode 100644 openapi/v2/components/schemas/LinksCollection.yaml create mode 100644 openapi/v2/components/schemas/LinksResource.yaml create mode 100644 openapi/v2/components/schemas/LinksSelf.yaml create mode 100644 openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml create mode 100644 openapi/v2/components/schemas/OunitCollection.yaml create mode 100644 openapi/v2/components/schemas/OunitData.yaml create mode 100644 openapi/v2/components/schemas/OunitResource.yaml create mode 100644 openapi/v2/components/schemas/Problem.yaml create mode 100644 openapi/v2/components/schemas/ProgrammeCollection.yaml create mode 100644 openapi/v2/components/schemas/ProgrammeData.yaml create mode 100644 openapi/v2/components/schemas/ProgrammeResource.yaml create mode 100644 openapi/v2/components/schemas/Root.yaml create mode 100644 openapi/v2/components/schemas/Schema.yaml create mode 100644 openapi/v2/components/schemas/StringWithOptionalLang.yaml create mode 100644 openapi/v2/components/schemas/User.yaml create mode 100644 openapi/v2/components/securitySchemes/api_key.yaml create mode 100644 openapi/v2/components/securitySchemes/basic_auth.yaml create mode 100644 openapi/v2/components/securitySchemes/main_auth.yaml create mode 100644 openapi/v2/paths/README.md create mode 100644 openapi/v2/paths/course.yaml create mode 100644 openapi/v2/paths/course@{id}.yaml create mode 100644 openapi/v2/paths/echo.yaml create mode 100644 openapi/v2/paths/hei.yaml create mode 100644 openapi/v2/paths/hei@{heiId}.yaml create mode 100644 openapi/v2/paths/ounit.yaml create mode 100644 openapi/v2/paths/ounit@{id}-course.yaml create mode 100644 openapi/v2/paths/ounit@{id}-programme.yaml create mode 100644 openapi/v2/paths/ounit@{id}.yaml create mode 100644 openapi/v2/paths/path-item-with-examples.yaml create mode 100644 openapi/v2/paths/path-item.yaml create mode 100644 openapi/v2/paths/programme.yaml create mode 100644 openapi/v2/paths/programme@{id}-course.yaml create mode 100644 openapi/v2/paths/programme@{id}.yaml create mode 100644 openapi/v2/paths/root.yaml create mode 100644 openapi/v2/paths/users@{username}.yaml diff --git a/openapi/occapi_v2.yaml b/openapi/occapi_v2.yaml index d134dea..bce9bf8 100644 --- a/openapi/occapi_v2.yaml +++ b/openapi/occapi_v2.yaml @@ -37,34 +37,34 @@ servers: 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' + $ref: 'v2/paths/course@{id}.yaml' # Exanples # '/path': - # $ref: 'paths/path-item.yaml' + # $ref: 'v2/paths/path-item.yaml' # '/path/example': - # $ref: 'paths/path-item-with-examples.yaml' + # $ref: 'v2/paths/path-item-with-examples.yaml' diff --git a/openapi/v2/components/README.md b/openapi/v2/components/README.md new file mode 100644 index 0000000..26eaeb5 --- /dev/null +++ b/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` diff --git a/openapi/v2/components/headers/ExpiresAfter.yaml b/openapi/v2/components/headers/ExpiresAfter.yaml new file mode 100644 index 0000000..0cbe9a5 --- /dev/null +++ b/openapi/v2/components/headers/ExpiresAfter.yaml @@ -0,0 +1,4 @@ +description: date in UTC when token expires +schema: + type: string + format: date-time diff --git a/openapi/v2/components/responses/CourseCollection.yaml b/openapi/v2/components/responses/CourseCollection.yaml new file mode 100644 index 0000000..1439341 --- /dev/null +++ b/openapi/v2/components/responses/CourseCollection.yaml @@ -0,0 +1,50 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: course + id: aabbccdd-eeff-1122-3344-556677889900 + attributes: + title: + - string: Example Course + lang: en + code: COUR01 + description: + - multiline: | + This is the description of the Course. + + This is a long text field. + lang: en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Course. + + This is a long text field. + lang: en + academicTerm: '1/2' + ects: 6 + languageOfInstruction: en + iscedCode: '0000' + subjectArea: '00.0' + otherCategorization: 'zero' + unavailableForIncomingMobility: false + url: + - uri: www.domain.tld/example/course + lang: en + meta: + global: + eqfLevel: 6 + year: '1/3' + programme: + - programmeId: abcdef12-3456-7890-abcd-ef1234567890 + mandatoryCourse: true + year: '1/2' + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course' diff --git a/openapi/v2/components/responses/CourseResource.yaml b/openapi/v2/components/responses/CourseResource.yaml new file mode 100644 index 0000000..b716106 --- /dev/null +++ b/openapi/v2/components/responses/CourseResource.yaml @@ -0,0 +1,86 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + type: course + id: aabbccdd-eeff-1122-3344-556677889900 + attributes: + title: + - string: Example Course + lang: en + code: COUR01 + description: + - multiline: | + This is the description of the Course. + + This is a long text field. + lang: en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Course. + + This is a long text field. + lang: en + academicTerm: '1/2' + ects: 6 + languageOfInstruction: en + iscedCode: '0000' + subjectArea: '00.0' + otherCategorization: 'zero' + unavailableForIncomingMobility: false + 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 + meta: + global: + eqfLevel: 6 + year: '1/3' + programme: + - programmeId: abcdef12-3456-7890-abcd-ef1234567890 + mandatoryCourse: true + year: '1/2' + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' diff --git a/openapi/v2/components/responses/EndpointNotAvailable.yaml b/openapi/v2/components/responses/EndpointNotAvailable.yaml new file mode 100644 index 0000000..21f586b --- /dev/null +++ b/openapi/v2/components/responses/EndpointNotAvailable.yaml @@ -0,0 +1,9 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +errors: + - status: "404" + title: Endpoint not available. diff --git a/openapi/v2/components/responses/InstitutionCollection.yaml b/openapi/v2/components/responses/InstitutionCollection.yaml new file mode 100644 index 0000000..a6adc50 --- /dev/null +++ b/openapi/v2/components/responses/InstitutionCollection.yaml @@ -0,0 +1,24 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: hei + id: 12345678-90ab-cdef-1234-567890abcdef + attributes: + title: + - string: Example Institution + lang: en + abbreviation: EI + heiId: domain.tld + url: + - uri: www.domain.tld + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld' +links: + self: + href: 'http://example.com/occapi/v1/hei' diff --git a/openapi/v2/components/responses/InstitutionResource.yaml b/openapi/v2/components/responses/InstitutionResource.yaml new file mode 100644 index 0000000..bf1bd09 --- /dev/null +++ b/openapi/v2/components/responses/InstitutionResource.yaml @@ -0,0 +1,30 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + type: hei + id: 12345678-90ab-cdef-1234-567890abcdef + attributes: + title: + - string: Example Institution + lang: en + abbreviation: EI + heiId: domain.tld + url: + - uri: www.domain.tld + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld' + ounit: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit' + programme: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme' + course: + href: 'http://example.com/occapi/v1/hei/domain.tld/course' diff --git a/openapi/v2/components/responses/OunitCollection.yaml b/openapi/v2/components/responses/OunitCollection.yaml new file mode 100644 index 0000000..3bb2f49 --- /dev/null +++ b/openapi/v2/components/responses/OunitCollection.yaml @@ -0,0 +1,25 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: ounit + id: 11223344-5566-7788-9900-aabbccddeeff + attributes: + title: + - string: Example Organisational Unit + lang: en + abbreviation: EOU + ounitId: 11223344-5566-7788-9900-aabbccddeeff + ounitCode: EI-EOU + url: + - uri: www.domain.tld/eou + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit' diff --git a/openapi/v2/components/responses/OunitCourseCollection.yaml b/openapi/v2/components/responses/OunitCourseCollection.yaml new file mode 100644 index 0000000..6bada9c --- /dev/null +++ b/openapi/v2/components/responses/OunitCourseCollection.yaml @@ -0,0 +1,49 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: course + id: aabbccdd-eeff-1122-3344-556677889900 + attributes: + title: + - string: Example Course + lang: en + code: COUR01 + description: + - multiline: | + This is the description of the Course. + + This is a long text field. + lang: en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Course. + + This is a long text field. + lang: en + academicTerm: '1/2' + ects: 6 + languageOfInstruction: en + iscedCode: '0000' + subjectArea: '00.0' + otherCategorization: 'zero' + url: + - uri: www.domain.tld/example/course + lang: en + meta: + global: + eqfLevel: 6 + year: '1/3' + programme: + - programmeId: abcdef12-3456-7890-abcd-ef1234567890 + mandatoryCourse: true + year: '1/2' + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' diff --git a/openapi/v2/components/responses/OunitProgrammeCollection.yaml b/openapi/v2/components/responses/OunitProgrammeCollection.yaml new file mode 100644 index 0000000..20c23b6 --- /dev/null +++ b/openapi/v2/components/responses/OunitProgrammeCollection.yaml @@ -0,0 +1,34 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: programme + id: abcdef12-3456-7890-abcd-ef1234567890 + attributes: + title: + - string: Example Programme + lang: en + code: PROG01 + description: + - multiline: | + This is the description of the Programme. + + This is a long text field. + lang: en + ects: 120 + eqfLevelProvided: 5 + iscedCode: 0000 + languageOfInstruction: en + length: 2 + url: + - uri: www.domain.tld/example/programme + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' diff --git a/openapi/v2/components/responses/OunitResource.yaml b/openapi/v2/components/responses/OunitResource.yaml new file mode 100644 index 0000000..6b5f9b4 --- /dev/null +++ b/openapi/v2/components/responses/OunitResource.yaml @@ -0,0 +1,29 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + type: ounit + id: 11223344-5566-7788-9900-aabbccddeeff + attributes: + title: + - string: Example Organisational Unit + lang: en + abbreviation: EOU + ounitId: 11223344-5566-7788-9900-aabbccddeeff + ounitCode: EI-EOU + url: + - uri: www.domain.tld/eou + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' + programme: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' + course: + href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' diff --git a/openapi/v2/components/responses/Problem.yaml b/openapi/v2/components/responses/Problem.yaml new file mode 100644 index 0000000..f66a55e --- /dev/null +++ b/openapi/v2/components/responses/Problem.yaml @@ -0,0 +1,5 @@ +description: Problem +content: + application/problem+json: + schema: + $ref: ../schemas/Problem.yaml \ No newline at end of file diff --git a/openapi/v2/components/responses/ProgrammeCollection.yaml b/openapi/v2/components/responses/ProgrammeCollection.yaml new file mode 100644 index 0000000..c954102 --- /dev/null +++ b/openapi/v2/components/responses/ProgrammeCollection.yaml @@ -0,0 +1,34 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: programme + id: abcdef12-3456-7890-abcd-ef1234567890 + attributes: + title: + - string: Example Programme + lang: en + code: PROG01 + description: + - multiline: | + This is the description of the Programme. + + This is a long text field. + lang: en + ects: 120 + eqfLevelProvided: 5 + iscedCode: 0000 + languageOfInstruction: en + length: 2 + url: + - uri: www.domain.tld/example/programme + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme' diff --git a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml new file mode 100644 index 0000000..7ff8974 --- /dev/null +++ b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml @@ -0,0 +1,49 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + - type: course + id: aabbccdd-eeff-1122-3344-556677889900 + attributes: + title: + - string: Example Course + lang: en + code: COUR01 + description: + - multiline: | + This is the description of the Course. + + This is a long text field. + lang: en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Course. + + This is a long text field. + lang: en + academicTerm: '1/2' + ects: 6 + languageOfInstruction: en + iscedCode: '0000' + subjectArea: '00.0' + otherCategorization: 'zero' + url: + - uri: www.domain.tld/example/course + lang: en + meta: + global: + eqfLevel: 6 + year: '1/3' + programme: + - programmeId: abcdef12-3456-7890-abcd-ef1234567890 + mandatoryCourse: true + year: '1/2' + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' diff --git a/openapi/v2/components/responses/ProgrammeResource.yaml b/openapi/v2/components/responses/ProgrammeResource.yaml new file mode 100644 index 0000000..195b46e --- /dev/null +++ b/openapi/v2/components/responses/ProgrammeResource.yaml @@ -0,0 +1,36 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +data: + type: programme + id: abcdef12-3456-7890-abcd-ef1234567890 + attributes: + title: + - string: Example Programme + lang: en + code: PROG01 + description: + - multiline: | + This is the description of the Programme. + + This is a long text field. + lang: en + ects: 120 + eqfLevelProvided: 5 + iscedCode: '0000' + languageOfInstruction: en + length: 2 + url: + - uri: www.domain.tld/example/programme + lang: en + links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' +links: + self: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + course: + href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' diff --git a/openapi/v2/components/responses/ResourceNotFound.yaml b/openapi/v2/components/responses/ResourceNotFound.yaml new file mode 100644 index 0000000..d8ba231 --- /dev/null +++ b/openapi/v2/components/responses/ResourceNotFound.yaml @@ -0,0 +1,9 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +errors: + - status: "404" + title: Resource not found. diff --git a/openapi/v2/components/responses/Root.yaml b/openapi/v2/components/responses/Root.yaml new file mode 100644 index 0000000..507139a --- /dev/null +++ b/openapi/v2/components/responses/Root.yaml @@ -0,0 +1,12 @@ +jsonapi: + version: "1.0" + meta: + links: + self: + href: "http://jsonapi.org/format/1.0/" +meta: {} +links: + self: + href: 'http://example.com/occapi/v1' + hei: + href: 'http://example.com/occapi/v1/hei' diff --git a/openapi/v2/components/schemas/CourseCollection.yaml b/openapi/v2/components/schemas/CourseCollection.yaml new file mode 100644 index 0000000..7950226 --- /dev/null +++ b/openapi/v2/components/schemas/CourseCollection.yaml @@ -0,0 +1,27 @@ +type: object +description: JSON:API collection of _Course_ resources. +required: + - data +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: array + description: List of _Course_ resources. + items: + type: object + required: + - type + - id + - links + - attributes + properties: + $ref: ./CourseData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml new file mode 100644 index 0000000..b23c80f --- /dev/null +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -0,0 +1,99 @@ +type: + type: string + description: JSON:API resource type. +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, + but any string that is unique within the realm of the Institution may be used. + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - title + - code + - description + - learningOutcomes + - academicTerm + - ects + - languageOfInstruction + - iscedCode + # - subjectArea + # - otherCategorization + properties: + title: + type: array + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + code: + type: string + description: Human readable code identifying the Course. + description: + type: array + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + learningOutcomes: + type: array + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + academicTerm: + type: string + description: | + Academic term in which the Course is delivered. + + e.g. `1/2` for first semester, + `2/2` for second semester, + `1/1` for the full academic year. + pattern: '[1-9]/[1-9]' + ects: + type: integer + description: Number of ECTS credits provided to the learner upon completing the Course. + languageOfInstruction: + type: string + description: | + Language code in + [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + + Optionally the country locale can be indicated in + [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + + e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + iscedCode: + type: string + description: | + [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + describing the field of education of the Course. + + This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. + subjectArea: + type: string + description: | + Erasmus subject area code describing the field of education of the Course. + otherCategorization: + type: string + description: | + Any other term used internally to describe the field of education of the Course. + unavailableForIncomingMobility: + type: boolean + description: | + Return `true` when the Course is not available for incoming exchange students to enroll. + + Unless explicitly stated, client implementations should assume this as `false`. + url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +meta: + $ref: ./CourseMeta.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml new file mode 100644 index 0000000..b709783 --- /dev/null +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -0,0 +1,129 @@ +type: + type: string + description: JSON:API resource type. +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, + but any string that is unique within the realm of the Institution may be used. + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - title + - code + - description + - learningOutcomes + - academicTerm + - ects + - languageOfInstruction + - iscedCode + # - subjectArea + # - otherCategorization + properties: + title: + type: array + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + code: + type: string + description: Human readable code identifying the Course. + description: + type: array + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + learningOutcomes: + type: array + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + academicTerm: + type: string + description: | + Academic term in which the Course is delivered. + + e.g. `1/2` for first semester, + `2/2` for second semester, + `1/1` for the full academic year. + pattern: '[1-9]/[1-9]' + ects: + type: integer + description: Number of ECTS credits provided to the learner upon completing the Course. + languageOfInstruction: + type: string + description: | + Language code in + [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + + Optionally the country locale can be indicated in + [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + + e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + iscedCode: + type: string + description: | + [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + describing the field of education of the Course. + + This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. + subjectArea: + type: string + description: | + Erasmus subject area code describing the field of education of the Course. + otherCategorization: + type: string + description: | + Any other term used internally to describe the field of education of the Course. + unavailableForIncomingMobility: + type: boolean + description: | + Return `true` when the Course is not available for incoming exchange students to enroll. + + Unless explicitly stated, client implementations should assume this as `false`. + url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml + bibliography: + type: array + description: Bibliography with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + courseContent: + type: array + description: Course content with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + prerequisites: + type: array + description: Prerequisites with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + courseAvailability: + type: array + description: Course availability with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + teachingMethod: + type: array + description: Teaching method with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + assessmentMethod: + type: array + description: Assessment method with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +meta: + $ref: ./CourseMeta.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseMeta.yaml b/openapi/v2/components/schemas/CourseMeta.yaml new file mode 100644 index 0000000..02b380c --- /dev/null +++ b/openapi/v2/components/schemas/CourseMeta.yaml @@ -0,0 +1,50 @@ +type: object +description: | + JSON:API _meta_ object containing information about the relation between + a Course and all or specific Programmes. +properties: + global: + type: object + description: Global rules that apply to all Programmes by default. + required: + - eqfLevel + - year + properties: + eqfLevel: + type: integer + minimum: 5 + maximum: 8 + description: | + [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) + of the Programmes to which the global rule applies. + year: + type: string + description: | + Year of the Programme in which the Course is delivered. + + e.g. `2/3` for the second of three years. + pattern: '[1-9]/[1-9]' + programme: + type: array + description: Rules that apply to specific Programmes. + items: + type: object + required: + - programmeId + - mandatoryCourse + - year + properties: + programmeId: + type: string + description: ID of the _Programme_ resource. + format: uuid + mandatoryCourse: + type: boolean + description: Whether the Course is mandatory within the Programme. + year: + type: string + description: | + Year of the Programme in which the Course is delivered. + + e.g. `2/3` for the second of three years. + pattern: '[1-9]/[1-9]' diff --git a/openapi/v2/components/schemas/CourseResource.yaml b/openapi/v2/components/schemas/CourseResource.yaml new file mode 100644 index 0000000..b6b09aa --- /dev/null +++ b/openapi/v2/components/schemas/CourseResource.yaml @@ -0,0 +1,25 @@ +type: object +description: JSON:API _Course_ resource. +required: + - data +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: object + description: _Course_ resource data. + required: + - type + - id + - links + - attributes + properties: + $ref: ./CourseDataExtended.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/DescriptionLang.yaml b/openapi/v2/components/schemas/DescriptionLang.yaml new file mode 100644 index 0000000..9a5a741 --- /dev/null +++ b/openapi/v2/components/schemas/DescriptionLang.yaml @@ -0,0 +1,4 @@ +type: array +description: Description with optional language code. +items: + $ref: ./MultilineLang.yaml diff --git a/openapi/v2/components/schemas/Email.yaml b/openapi/v2/components/schemas/Email.yaml new file mode 100644 index 0000000..55801ff --- /dev/null +++ b/openapi/v2/components/schemas/Email.yaml @@ -0,0 +1,4 @@ +description: User email address +type: string +format: test +example: john.smith@example.com diff --git a/openapi/v2/components/schemas/Error.yaml b/openapi/v2/components/schemas/Error.yaml new file mode 100644 index 0000000..03ff4ae --- /dev/null +++ b/openapi/v2/components/schemas/Error.yaml @@ -0,0 +1,32 @@ +type: object +description: JSON:API `errors` object. +required: + - errors +properties: + jsonapi: + $ref: ./Jsonapi.yaml + errors: + type: array + description: List of errors. + items: + type: object + description: JSON:API `error` object. + properties: + status: + type: string + description: The HTTP status code applicable to this problem. + title: + type: string + description: Human-readable summary of the problem. + source: + type: object + description: | + An object containing references to the source of the error. + properties: + pointer: + type: string + description: | + A JSON Pointer to the associated entity in the request document. + parameter: + type: string + description: Which URI query parameter caused the error. diff --git a/openapi/v2/components/schemas/HttpWithOptionalLang.yaml b/openapi/v2/components/schemas/HttpWithOptionalLang.yaml new file mode 100644 index 0000000..f0a9691 --- /dev/null +++ b/openapi/v2/components/schemas/HttpWithOptionalLang.yaml @@ -0,0 +1,10 @@ +type: object +required: + - uri +properties: + uri: + type: string + format: uri + description: Value + lang: + $ref: ./Lang.yaml diff --git a/openapi/v2/components/schemas/InstitutionCollection.yaml b/openapi/v2/components/schemas/InstitutionCollection.yaml new file mode 100644 index 0000000..277bd49 --- /dev/null +++ b/openapi/v2/components/schemas/InstitutionCollection.yaml @@ -0,0 +1,27 @@ +type: object +description: JSON:API collection of _Institution_ resources. +required: + - data +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: array + description: List of _Institution_ resources. + items: + type: object + required: + - type + - id + - links + - attributes + properties: + $ref: ./InstitutionData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml new file mode 100644 index 0000000..7d45024 --- /dev/null +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -0,0 +1,40 @@ +type: + type: string + description: JSON:API resource type. +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, + but any string that is unique within the realm of the Institution may be used. + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - title + - heiId + properties: + title: + type: array + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + abbreviation: + type: string + description: Most widely recognized abbreviation. + heiId: + type: string + description: The SCHAC code of the Institution. + format: hostname + url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/InstitutionResource.yaml b/openapi/v2/components/schemas/InstitutionResource.yaml new file mode 100644 index 0000000..aac8299 --- /dev/null +++ b/openapi/v2/components/schemas/InstitutionResource.yaml @@ -0,0 +1,66 @@ +type: object +description: JSON:API _Institution_ resource. +required: + - data + - links +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: object + description: _Institution_ resource data. + required: + - type + - id + - links + - attributes + properties: + $ref: ./InstitutionData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksResource.yaml + ounit: + type: object + description: | + Hypermedia link to the _Organisational Units_ collection associated to this resource. + + **Recommended:** separate any collections by _Organisational Unit_ in order to avoid large HTTP responses. + + The resource collection links for _Programmes_ and _Courses_ shown below can also be implemented at the _Organisational Unit_ level. + required: + - href + properties: + href: + type: string + format: uri + programme: + type: object + description: | + Hypermedia link to the _Programmes_ collection associated to this resource. + + **Recommended:** separate this collection by _Organisational Unit_ in order to avoid large HTTP responses. + + The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. + required: + - href + properties: + href: + type: string + format: uri + course: + type: object + description: | + _**Discouraged!**_ Hypermedia link to the _Courses_ collection associated to this resource. + + **Recommended:** separate this collection by _Programme_ or by _Organisational Unit_ in order to avoid large HTTP responses. + required: + - href + properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/Jsonapi.yaml b/openapi/v2/components/schemas/Jsonapi.yaml new file mode 100644 index 0000000..7747162 --- /dev/null +++ b/openapi/v2/components/schemas/Jsonapi.yaml @@ -0,0 +1,34 @@ +type: object +description: JSON:API header. +required: + - version + - meta +properties: + version: + type: string + description: JSON:API schema version. + meta: + type: object + description: JSON:API meta object. + required: + - links + properties: + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + type: object + description: Hypermedia link to the current path. + required: + - href + properties: + href: + type: string + format: uri + description: | + JSON:API version supported by the server. + + http://jsonapi.org/format/1.0/ diff --git a/openapi/v2/components/schemas/Lang.yaml b/openapi/v2/components/schemas/Lang.yaml new file mode 100644 index 0000000..51a066d --- /dev/null +++ b/openapi/v2/components/schemas/Lang.yaml @@ -0,0 +1,19 @@ +type: + - string + - null +description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) diff --git a/openapi/v2/components/schemas/LinksCollection.yaml b/openapi/v2/components/schemas/LinksCollection.yaml new file mode 100644 index 0000000..1585730 --- /dev/null +++ b/openapi/v2/components/schemas/LinksCollection.yaml @@ -0,0 +1,8 @@ +type: object +description: Hypermedia link to this resource collection. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/LinksResource.yaml b/openapi/v2/components/schemas/LinksResource.yaml new file mode 100644 index 0000000..595fba9 --- /dev/null +++ b/openapi/v2/components/schemas/LinksResource.yaml @@ -0,0 +1,8 @@ +type: object +description: Hypermedia link to the **canonical path** of this resource. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/LinksSelf.yaml b/openapi/v2/components/schemas/LinksSelf.yaml new file mode 100644 index 0000000..c05b57a --- /dev/null +++ b/openapi/v2/components/schemas/LinksSelf.yaml @@ -0,0 +1,8 @@ +type: object +description: Hypermedia link to the current path. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml b/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml new file mode 100644 index 0000000..463354c --- /dev/null +++ b/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml @@ -0,0 +1,9 @@ +type: object +required: + - multiline +properties: + multiline: + type: string + description: Value + lang: + $ref: ./Lang.yaml diff --git a/openapi/v2/components/schemas/OunitCollection.yaml b/openapi/v2/components/schemas/OunitCollection.yaml new file mode 100644 index 0000000..3ce3eba --- /dev/null +++ b/openapi/v2/components/schemas/OunitCollection.yaml @@ -0,0 +1,27 @@ +type: object +description: JSON:API collection of _Organisational Unit_ resources. +required: + - data +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: array + description: List of _Organisational Unit_ resources. + items: + type: object + required: + - type + - id + - links + - attributes + properties: + $ref: ./OunitData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml new file mode 100644 index 0000000..07a3aae --- /dev/null +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -0,0 +1,42 @@ +type: + type: string + description: JSON:API resource type. +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, + but any string that is unique within the realm of the Institution may be used. + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - title + - ounitId + properties: + title: + type: array + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + abbreviation: + type: string + description: Most widely recognized abbreviation. + ounitId: + type: string + description: Unique identifier within the Institution. Can be a UUID. + ounitCode: + type: string + description: Human readable code identifying the Organisational Unit. + url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/OunitResource.yaml b/openapi/v2/components/schemas/OunitResource.yaml new file mode 100644 index 0000000..23bb507 --- /dev/null +++ b/openapi/v2/components/schemas/OunitResource.yaml @@ -0,0 +1,48 @@ +type: object +description: JSON:API _Organisational Unit_ resource. +required: + - data + - links +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: object + description: _Organisational Unit_ resource data. + required: + - type + - id + - links + - attributes + properties: + $ref: ./OunitData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksResource.yaml + programme: + type: object + description: | + Hypermedia link to the _Programmes_ collection associated to this resource. + + The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. + required: + - href + properties: + href: + type: string + format: uri + course: + type: object + description: | + Hypermedia link to the _Courses_ collection associated to this resource. + required: + - href + properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/Problem.yaml b/openapi/v2/components/schemas/Problem.yaml new file mode 100644 index 0000000..b0d320b --- /dev/null +++ b/openapi/v2/components/schemas/Problem.yaml @@ -0,0 +1,39 @@ +type: object +additionalProperties: true +minProperties: 1 +description: >- + The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. +properties: + type: + type: string + description: >- + A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the problem type. + It should provide human-readable documentation for the problem type. + When this member is not present, its value is assumed to be "about:blank". + format: uri + title: + type: string + description: >- + A short, human-readable summary of the problem type. + It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. + status: + type: integer + description: The HTTP status code. + minimum: 400 + maximum: 599 + detail: + type: string + description: >- + A human-readable explanation specific to this + occurrence of the problem. + instance: + type: string + description: >- + A URI reference that identifies the specific + occurrence of the problem. It may or may not yield further + information if dereferenced. + +# Consumers SHOULD NOT parse the "detail" member for information; +# extensions are more suitable and less error-prone ways to obtain such +# information. +# See: https://datatracker.ietf.org/doc/html/rfc7807#section-3.2 \ No newline at end of file diff --git a/openapi/v2/components/schemas/ProgrammeCollection.yaml b/openapi/v2/components/schemas/ProgrammeCollection.yaml new file mode 100644 index 0000000..8dafb7f --- /dev/null +++ b/openapi/v2/components/schemas/ProgrammeCollection.yaml @@ -0,0 +1,27 @@ +type: object +description: JSON:API collection of _Programme_ resources. +required: + - data +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: array + description: List of _Programme_ resources. + items: + type: object + required: + - type + - id + - links + - attributes + properties: + $ref: ./ProgrammeData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml new file mode 100644 index 0000000..d64dfd1 --- /dev/null +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -0,0 +1,76 @@ +type: + type: string + description: JSON:API resource type. +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, + but any string that is unique within the realm of the Institution may be used. + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - title + - code + - description + - ects + - eqfLevelProvided + - iscedCode + - languageOfInstruction + - length + properties: + title: + type: array + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + code: + type: string + description: Human readable code identifying the Programme. + description: + type: array + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml + ects: + type: integer + description: Number of ECTS credits required to complete the Programme. + eqfLevelProvided: + type: integer + minimum: 5 + maximum: 8 + description: | + [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) + provided to the learner upon completing the Programme. + iscedCode: + type: string + description: | + [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + describing the field of education of the Programme. + languageOfInstruction: + type: string + description: | + Language code in + [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + + Optionally the country locale can be indicated in + [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + + e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + length: + type: integer + minimum: 1 + description: Length of the Programme in **years**. + url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/ProgrammeResource.yaml b/openapi/v2/components/schemas/ProgrammeResource.yaml new file mode 100644 index 0000000..a153c05 --- /dev/null +++ b/openapi/v2/components/schemas/ProgrammeResource.yaml @@ -0,0 +1,36 @@ +type: object +description: JSON:API _Programme_ resource. +required: + - data + - links +properties: + jsonapi: + $ref: ./Jsonapi.yaml + data: + type: object + description: _Programme_ resource data. + required: + - type + - id + - links + - attributes + properties: + $ref: ./ProgrammeData.yaml + links: + type: object + description: JSON:API _links_ object. + # required: + # - self + properties: + self: + $ref: ./LinksResource.yaml + course: + type: object + description: | + Hypermedia link to the _Courses_ collection associated to this resource. + required: + - href + properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/Root.yaml b/openapi/v2/components/schemas/Root.yaml new file mode 100644 index 0000000..40ddf71 --- /dev/null +++ b/openapi/v2/components/schemas/Root.yaml @@ -0,0 +1,27 @@ +type: object +description: Available endpoints and metadata. +required: + - links +properties: + jsonapi: + $ref: ./Jsonapi.yaml + meta: + type: object + description: Optional metadata. + links: + type: object + description: JSON:API _links_ object. + required: + - hei + properties: + self: + $ref: ./LinksSelf.yaml + hei: + type: object + description: Hypermedia link to the [Institution collection](#tag/Institution). + required: + - href + properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/Schema.yaml b/openapi/v2/components/schemas/Schema.yaml new file mode 100644 index 0000000..308414a --- /dev/null +++ b/openapi/v2/components/schemas/Schema.yaml @@ -0,0 +1,154 @@ +type: object +title: Scalars +properties: + stringProperty: + description: Property name's description (type is string) + type: string + examples: + - example + - sample + readOnlyStringProperty: + description: Notice this only appears in the response. + type: string + readOnly: true + examples: + - example + writeOnlyStringProperty: + description: Notice this only appears in the request. + type: string + writeOnly: true + examples: + - example + minLengthString: + description: Property name's description (type is string) + type: string + minLength: 4 + examples: + - example + maxLengthString: + description: Property name's description (type is string) + type: string + maxLength: 140 + examples: + - example + minAndMaxLengthString: + description: Property name's description (type is string) + type: string + minLength: 4 + maxLength: 140 + examples: + - example + nullableOrStringProperty: + description: Property name's description (type is string or null) + type: + - string + - null + examples: + - example + stringEnumValues: + description: Property name's description (type is string) + type: string + enum: + - sample + - example + - specimen + - case + - instance + - illustration + stringDateTime: + description: Property name's description (type is string, format is date-time) + type: string + format: date-time + stringDate: + description: Property name's description (type is string, format is date-time) + type: string + format: date + stringEmail: + description: Property name's description (type is string, format is email) + type: string + format: email + stringIpAddressV4: + description: Property name's description (type is string, format is ipv4 address) + type: string + format: ipv4 + stringIpAddressV6: + description: Property name's description (type is string, format is ipv6 address) + type: string + format: ipv6 + stringPassword: + description: Property name's description (type is string, format is password) + type: string + format: password + stringHostname: + description: Property name's description (type is string, format is hostname) + type: string + format: hostname + stringUri: + description: Property name's description (type is string, format is uri) + type: string + format: uri + stringUuid: + description: Property name's description (type is string, format is uuid) + type: string + format: uuid + numberProperty: + description: Property name's description (type is number) + type: number + example: 8 + numberFloat: + description: Property name's description (type is number, format is float) + type: number + format: float + numberDouble: + description: Property name's description (type is number, format is double) + type: number + format: double + numberGreaterThanOrEquals: + description: Property name's description (type is number) + type: number + minimum: 5 + numberGreaterThan: + description: Property name's description (type is number) + type: number + exclusiveMinimum: 5 + numberLessThan: + description: Property name's description (type is number) + type: number + exclusiveMaximum: 8 + numberLessThanOrEquals: + description: Property name's description (type is number) + type: number + maximum: 8 + numberRange: + description: Property name's description (type is number) + type: number + minimum: 5 + maximum: 8 + numberRangeExclusiveMaximum: + description: Property name's description (type is number) + type: number + minimum: 5 + exclusiveMaximum: 8 + numberRangeExclusiveMinimumAndMaximum: + description: Property name's description (type is number) + type: number + exclusiveMinimum: 5 + exclusiveMaximum: 8 + numberMultipleOf: + description: Property name's description (type is number) + type: number + multipleOf: 2 + integerType: + description: Property name's description (type is integer) + type: integer + integer32bit: + description: Property name's description (type is integer, format is int32) + type: integer + format: int32 + integer64bit: + description: Property name's description (type is integer, format is int64) + type: integer + format: int64 + booleanProperty: + description: Property name's description (type is boolean) + type: boolean diff --git a/openapi/v2/components/schemas/StringWithOptionalLang.yaml b/openapi/v2/components/schemas/StringWithOptionalLang.yaml new file mode 100644 index 0000000..1560468 --- /dev/null +++ b/openapi/v2/components/schemas/StringWithOptionalLang.yaml @@ -0,0 +1,9 @@ +type: object +required: + - string +properties: + string: + type: string + description: Value + lang: + $ref: ./Lang.yaml diff --git a/openapi/v2/components/schemas/User.yaml b/openapi/v2/components/schemas/User.yaml new file mode 100644 index 0000000..efdeb3b --- /dev/null +++ b/openapi/v2/components/schemas/User.yaml @@ -0,0 +1,19 @@ +type: object +properties: + username: + description: User supplied username + type: string + minLength: 4 + example: John78 + firstName: + description: User first name + type: string + minLength: 1 + example: John + lastName: + description: User last name + type: string + minLength: 1 + example: Smith + email: + $ref: ./Email.yaml diff --git a/openapi/v2/components/securitySchemes/api_key.yaml b/openapi/v2/components/securitySchemes/api_key.yaml new file mode 100644 index 0000000..359e56e --- /dev/null +++ b/openapi/v2/components/securitySchemes/api_key.yaml @@ -0,0 +1,3 @@ +type: apiKey +in: header +name: api_key diff --git a/openapi/v2/components/securitySchemes/basic_auth.yaml b/openapi/v2/components/securitySchemes/basic_auth.yaml new file mode 100644 index 0000000..d016600 --- /dev/null +++ b/openapi/v2/components/securitySchemes/basic_auth.yaml @@ -0,0 +1,2 @@ +type: http +scheme: basic diff --git a/openapi/v2/components/securitySchemes/main_auth.yaml b/openapi/v2/components/securitySchemes/main_auth.yaml new file mode 100644 index 0000000..a8ba56c --- /dev/null +++ b/openapi/v2/components/securitySchemes/main_auth.yaml @@ -0,0 +1,7 @@ +type: oauth2 +flows: + implicit: + authorizationUrl: 'http://example.com/api/oauth/dialog' + scopes: + 'read:users': read users info + 'write:users': modify or remove users diff --git a/openapi/v2/paths/README.md b/openapi/v2/paths/README.md new file mode 100644 index 0000000..0449659 --- /dev/null +++ b/openapi/v2/paths/README.md @@ -0,0 +1,105 @@ +Paths +===== + +Organize your path definitions within this folder. You will reference your paths from your main `openapi.yaml` entrypoint file. + +It may help you to adopt some conventions: + +* path separator token (e.g. `@`) or subfolders +* path parameter (e.g. `{example}`) +* file-per-path or file-per-operation + +There are different benefits and drawbacks to each decision. + +You can adopt any organization you wish. We have some tips for organizing paths based on common practices. + +## Each path in a separate file + +Use a predefined "path separator" and keep all of your path files in the top level of the `paths` folder. + +``` +# todo: insert tree view of paths folder +``` + +Redocly recommends using the `@` character for this case. + +In addition, Redocly recommends placing path parameters within `{}` curly braces if you adopt this style. + +#### Motivations + +* Quickly see a list of all paths. Many people think in terms of the "number" of "endpoints" (paths), and not the "number" of "operations" (paths * http methods). + +* Only the "file-per-path" option is semantically correct with the OpenAPI Specification 3.0.2. However, Redocly's openapi-cli will build valid bundles for any of the other options too. + + +#### Drawbacks + +* This may require multiple definitions per http method within a single file. +* It requires settling on a path separator (that is allowed to be used in filenames) and sticking to that convention. + +## Each operation in a separate file + +You may also place each operation in a separate file. + +In this case, if you want all paths at the top-level, you can concatenate the http method to the path name. Similar to the above option, you can + +### Files at top-level of `paths` + +You may name your files with some concatenation for the http method. For example, following a convention such as: `-.yaml`. + +#### Motivations + +* Quickly see all operations without needing to navigate subfolders. + +#### Drawbacks + +* Adopting an unusual path separator convention, instead of using subfolders. + +### Use subfolders to mirror API path structure + +Example: +``` +GET /customers + +/paths/customers/get.yaml +``` + +In this case, the path id defined within subfolders which mirror the API URL structure. + +Example with path parameter: +``` +GET /customers/{id} + +/paths/customers/{id}/get.yaml +``` + +#### Motivations + +It matches the URL structure. + +It is pretty easy to reference: + +```yaml +paths: + '/customers/{id}': + get: + $ref: ./paths/customers/{id}/get.yaml + put: + $ref: ./paths/customers/{id}/put.yaml +``` + +#### Drawbacks + +If you have a lot of nested folders, it may be confusing to reference your schemas. + +Example +``` +file: /paths/customers/{id}/timeline/{messageId}/get.yaml + +# excerpt of file + headers: + Rate-Limit-Remaining: + $ref: ../../../../../components/headers/Rate-Limit-Remaining.yaml + +``` +Notice the `../../../../../` in the ref which requires some attention to formulate correctly. While openapi-cli has a linter which suggests possible refs when there is a mistake, this is still a net drawback for APIs with deep paths. diff --git a/openapi/v2/paths/course.yaml b/openapi/v2/paths/course.yaml new file mode 100644 index 0000000..f88c605 --- /dev/null +++ b/openapi/v2/paths/course.yaml @@ -0,0 +1,37 @@ +get: + tags: + - Course + summary: GET /hei/{heiId}/course + description: | + This endpoint lists all _Courses_ offered by an _Institution_. + operationId: getCourses + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseCollection.yaml + example: + $ref: ../components/responses/CourseCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/course@{id}.yaml b/openapi/v2/paths/course@{id}.yaml new file mode 100644 index 0000000..8be1bb6 --- /dev/null +++ b/openapi/v2/paths/course@{id}.yaml @@ -0,0 +1,47 @@ +get: + tags: + - Course + summary: GET /hei/{heiId}/course/{id} + description: | + This endpoint exposes extended information about a _Course_. + + A single resource response can include more fields than would appear in a collection response. + operationId: getCourseByUuid + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + format: hostname + - name: id + in: path + description: The UUID of the _Course_ resource. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseResource.yaml + example: + $ref: ../components/responses/CourseResource.yaml + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/ResourceNotFound.yaml diff --git a/openapi/v2/paths/echo.yaml b/openapi/v2/paths/echo.yaml new file mode 100644 index 0000000..d8e9c8c --- /dev/null +++ b/openapi/v2/paths/echo.yaml @@ -0,0 +1,54 @@ +post: + tags: + - Echo + summary: Echo test + description: Receive the exact message you've sent + operationId: echo + security: + - api_key: [] + - basic_auth: [] + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user + schema: + type: integer + format: int32 + X-Expires-After: + $ref: ../components/headers/ExpiresAfter.yaml + content: + application/json: + schema: + type: string + examples: + response: + value: Hello world! + application/xml: + schema: + type: string + text/csv: + schema: + type: string + '400': + description: Unauthorized + requestBody: + content: + application/json: + schema: + type: string + example: Hello world! + application/xml: + schema: + type: string + example: Hello world! + description: Echo payload + required: true + x-codeSamples: + - lang: "C#" + source: + $ref: "../code_samples/csharp/echo/post.cs" + - lang: PHP + source: + $ref: ../code_samples/PHP/echo/post.php diff --git a/openapi/v2/paths/hei.yaml b/openapi/v2/paths/hei.yaml new file mode 100644 index 0000000..eed05dd --- /dev/null +++ b/openapi/v2/paths/hei.yaml @@ -0,0 +1,35 @@ +get: + tags: + - Institution + summary: GET /hei + description: | + This endpoint lists all _Institutions_ covered by this provider. + + In order to obtain more detailed and up to date information about an + Institution, it is **recommended** that client implementations use the + [HEI API](https://hei.api.uni-foundation.eu) service provided by the + [European University Foundation](https://uni-foundation.eu/). + operationId: getInstitutions + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/InstitutionCollection.yaml + example: + $ref: ../components/responses/InstitutionCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/hei@{heiId}.yaml b/openapi/v2/paths/hei@{heiId}.yaml new file mode 100644 index 0000000..d2cc2cb --- /dev/null +++ b/openapi/v2/paths/hei@{heiId}.yaml @@ -0,0 +1,44 @@ +get: + tags: + - Institution + summary: GET /hei/{heiId} + description: | + This endpoint exposes some basic information about an Institution covered by + the provider, which should be sufficient to satisfy basic UX/UI needs of + app developers. + + In order to obtain more detailed and up to date information about an + Institution, it is **recommended** that client implementations use the + [HEI API](https://hei.api.uni-foundation.eu) service provided by the + [European University Foundation](https://uni-foundation.eu/). + operationId: getInstitutionById + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/InstitutionResource.yaml + example: + $ref: ../components/responses/InstitutionResource.yaml + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/ResourceNotFound.yaml diff --git a/openapi/v2/paths/ounit.yaml b/openapi/v2/paths/ounit.yaml new file mode 100644 index 0000000..93d38c7 --- /dev/null +++ b/openapi/v2/paths/ounit.yaml @@ -0,0 +1,40 @@ +get: + tags: + - Organisational Unit + summary: GET /hei/{heiId}/ounit + description: | + This endpoint lists all _Organisational Units_ in an _Institution_. + + Implementation is optional but **recommended** since exposing collections by + _Organisational Unit_ can help avoid large HTTP responses. + operationId: getOunits + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/OunitCollection.yaml + example: + $ref: ../components/responses/OunitCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/ounit@{id}-course.yaml b/openapi/v2/paths/ounit@{id}-course.yaml new file mode 100644 index 0000000..79efb10 --- /dev/null +++ b/openapi/v2/paths/ounit@{id}-course.yaml @@ -0,0 +1,44 @@ +get: + tags: + - Course + summary: GET /hei/{heiId}/ounit/{id}/course + description: | + This endpoint lists all _Courses_ offered by an _Institution_ filtered by _Organisational Unit_. + operationId: getOunitCourses + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + - name: id + in: path + description: The UUID of the _Organisational Unit_ resource to filter by. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseCollection.yaml + example: + $ref: ../components/responses/OunitCourseCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/ounit@{id}-programme.yaml b/openapi/v2/paths/ounit@{id}-programme.yaml new file mode 100644 index 0000000..3df2ba0 --- /dev/null +++ b/openapi/v2/paths/ounit@{id}-programme.yaml @@ -0,0 +1,44 @@ +get: + tags: + - Programme + summary: GET /hei/{heiId}/ounit/{id}/programme + description: | + This endpoint lists all _Programmes_ offered by an _Institution_ filtered by _Organisational Unit_. + operationId: getOunitProgrammes + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + - name: id + in: path + description: The UUID of the _Organisational Unit_ resource to filter by. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/ProgrammeCollection.yaml + example: + $ref: ../components/responses/OunitProgrammeCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/ounit@{id}.yaml b/openapi/v2/paths/ounit@{id}.yaml new file mode 100644 index 0000000..18f1e1c --- /dev/null +++ b/openapi/v2/paths/ounit@{id}.yaml @@ -0,0 +1,48 @@ +get: + tags: + - Organisational Unit + summary: GET /hei/{heiId}/ounit/{id} + description: | + This endpoint exposes some basic information about an _Organisational Unit_. + + Implementation is optional but **recommended** since exposing collections by + _Organisational Unit_ can help avoid large HTTP responses. + operationId: getOunitByUuid + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + format: hostname + - name: id + in: path + description: The UUID of the _Organisational Unit_ resource. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/OunitResource.yaml + example: + $ref: ../components/responses/OunitResource.yaml + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/ResourceNotFound.yaml diff --git a/openapi/v2/paths/path-item-with-examples.yaml b/openapi/v2/paths/path-item-with-examples.yaml new file mode 100644 index 0000000..46b511f --- /dev/null +++ b/openapi/v2/paths/path-item-with-examples.yaml @@ -0,0 +1,43 @@ +post: + tags: + - Tag + summary: Operation summary with examples + description: | + Operation description **markdown**. + operationId: postPathItemWithExamples + security: + - api_key: [] + - basic_auth: [] + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/Schema.yaml + examples: + mapName: + summary: My first example + description: My first example's description. + value: + stringProperty: tada + mapNameDoesNotShowInDocsUnlessSummaryIsNotProvided: + value: + stringProperty: checkmark + description: requestBody description + required: true + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user + schema: + type: integer + format: int32 + X-Expires-After: + $ref: ../components/headers/ExpiresAfter.yaml + content: + application/json: + schema: + $ref: ../components/schemas/Schema.yaml + '400': + $ref: ../components/responses/Problem.yaml diff --git a/openapi/v2/paths/path-item.yaml b/openapi/v2/paths/path-item.yaml new file mode 100644 index 0000000..92ebaa9 --- /dev/null +++ b/openapi/v2/paths/path-item.yaml @@ -0,0 +1,34 @@ +post: + tags: + - Tag + summary: Operation summary + description: | + Operation description **Markdown**. + operationId: operationId + security: + - api_key: [] + - basic_auth: [] + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/Schema.yaml + description: requestBody description + required: true + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: Calls per hour allowed by the user. + schema: + type: integer + format: int32 + X-Expires-After: + $ref: ../components/headers/ExpiresAfter.yaml + content: + application/json: + schema: + $ref: ../components/schemas/Schema.yaml + '400': + $ref: ../components/responses/Problem.yaml diff --git a/openapi/v2/paths/programme.yaml b/openapi/v2/paths/programme.yaml new file mode 100644 index 0000000..8848c01 --- /dev/null +++ b/openapi/v2/paths/programme.yaml @@ -0,0 +1,37 @@ +get: + tags: + - Programme + summary: GET /hei/{heiId}/programme + description: | + This endpoint lists all _Programmes_ offered by an _Institution_. + operationId: getProgrammes + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/ProgrammeCollection.yaml + example: + $ref: ../components/responses/ProgrammeCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/programme@{id}-course.yaml b/openapi/v2/paths/programme@{id}-course.yaml new file mode 100644 index 0000000..d899567 --- /dev/null +++ b/openapi/v2/paths/programme@{id}-course.yaml @@ -0,0 +1,44 @@ +get: + tags: + - Course + summary: GET /hei/{heiId}/programme/{id}/course + description: | + This endpoint lists all _Courses_ offered by an _Institution_ filtered by _Programme_. + operationId: getProgrammeCourses + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + - name: id + in: path + description: The UUID of the _Programme_ resource to filter by. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseCollection.yaml + example: + $ref: ../components/responses/ProgrammeCourseCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/programme@{id}.yaml b/openapi/v2/paths/programme@{id}.yaml new file mode 100644 index 0000000..84d6c5a --- /dev/null +++ b/openapi/v2/paths/programme@{id}.yaml @@ -0,0 +1,45 @@ +get: + tags: + - Programme + summary: GET /hei/{heiId}/programme/{id} + description: | + This endpoint exposes information about a _Programme_. + operationId: getProgrammeByUuid + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + format: hostname + - name: id + in: path + description: The UUID of the _Programme_ resource. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/ProgrammeResource.yaml + example: + $ref: ../components/responses/ProgrammeResource.yaml + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/ResourceNotFound.yaml diff --git a/openapi/v2/paths/root.yaml b/openapi/v2/paths/root.yaml new file mode 100644 index 0000000..aed0cd3 --- /dev/null +++ b/openapi/v2/paths/root.yaml @@ -0,0 +1,29 @@ +get: + tags: + - API provider + summary: GET / + description: Get primary Hypermedia links and optional metadata about the provider. + operationId: getRoot + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Root.yaml + example: + $ref: ../components/responses/Root.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/users@{username}.yaml b/openapi/v2/paths/users@{username}.yaml new file mode 100644 index 0000000..5271dc4 --- /dev/null +++ b/openapi/v2/paths/users@{username}.yaml @@ -0,0 +1,81 @@ +parameters: + - name: pretty_print + in: query + description: Pretty print response + schema: + type: boolean +get: + tags: + - User + summary: Get user by user name + description: | + Some description of the operation. + You can use `Markdown` here. + operationId: getUserByName + parameters: + - name: username + in: path + description: The name that needs to be fetched + required: true + schema: + type: string + - name: with_email + in: query + description: Filter users without email + schema: + type: boolean + security: + - main_auth: + - 'read:users' + - api_key: [] + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: ../components/schemas/User.yaml + example: + username: user1 + email: user@example.com + '403': + description: Forbidden + $ref: ../components/responses/Problem.yaml + '404': + description: User not found + $ref: ../components/responses/Problem.yaml +put: + tags: + - User + summary: Updated user + description: This can only be done by the logged in user. + operationId: updateUser + parameters: + - name: username + in: path + description: The name that needs to be updated + required: true + schema: + type: string + security: + - main_auth: + - 'write:users' + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/User.yaml + application/xml: + schema: + $ref: ../components/schemas/User.yaml + description: Updated user object + required: true + responses: + '200': + description: OK + '400': + description: Invalid user supplied + $ref: ../components/responses/Problem.yaml + '404': + description: User not found + $ref: ../components/responses/Problem.yaml diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 26d1e4b..d3cb7ae 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1191,11 +1191,21 @@ components: - string - null description: | - Language code in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + IETF BCP 47 language tag. - Optionally the script can be indicated in [ISO 15924](https://en.wikipedia.org/wiki/ISO_15924#List_of_codes) format. + Language tags allow to specify languages and their variations on script, region, etc. - e.g. `el` for Greek, `el-Latn` for Greek in Latin script. + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) StringWithOptionalLang: type: object required: From 110536e6b84a8bc65dac2d8f3b2df2ba71e5e19a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Fri, 5 Sep 2025 18:18:40 +0200 Subject: [PATCH 02/23] Initial review of Programmes; covers #38 #46 #47 #53; impacts #35 #45 --- .../components/schemas/DescriptionLang.yaml | 4 - .../schemas/HttpWithOptionalLang.yaml | 2 +- openapi/v2/components/schemas/Lang.yaml | 1 + .../schemas/LinksCourseCollection.yaml | 9 + .../MultilineStringWithOptionalLang.yaml | 3 +- .../v2/components/schemas/ProgrammeData.yaml | 140 ++++++-- .../components/schemas/ProgrammeResource.yaml | 10 - .../schemas/StringWithOptionalLang.yaml | 3 +- public/v2/openapi.yaml | 309 ++++++++++++++---- 9 files changed, 376 insertions(+), 105 deletions(-) delete mode 100644 openapi/v2/components/schemas/DescriptionLang.yaml create mode 100644 openapi/v2/components/schemas/LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/DescriptionLang.yaml b/openapi/v2/components/schemas/DescriptionLang.yaml deleted file mode 100644 index 9a5a741..0000000 --- a/openapi/v2/components/schemas/DescriptionLang.yaml +++ /dev/null @@ -1,4 +0,0 @@ -type: array -description: Description with optional language code. -items: - $ref: ./MultilineLang.yaml diff --git a/openapi/v2/components/schemas/HttpWithOptionalLang.yaml b/openapi/v2/components/schemas/HttpWithOptionalLang.yaml index f0a9691..952b553 100644 --- a/openapi/v2/components/schemas/HttpWithOptionalLang.yaml +++ b/openapi/v2/components/schemas/HttpWithOptionalLang.yaml @@ -5,6 +5,6 @@ properties: uri: type: string format: uri - description: Value + description: URL lang: $ref: ./Lang.yaml diff --git a/openapi/v2/components/schemas/Lang.yaml b/openapi/v2/components/schemas/Lang.yaml index 51a066d..8e5740e 100644 --- a/openapi/v2/components/schemas/Lang.yaml +++ b/openapi/v2/components/schemas/Lang.yaml @@ -1,6 +1,7 @@ type: - string - null +minLength: 2 description: | IETF BCP 47 language tag. diff --git a/openapi/v2/components/schemas/LinksCourseCollection.yaml b/openapi/v2/components/schemas/LinksCourseCollection.yaml new file mode 100644 index 0000000..b4933b8 --- /dev/null +++ b/openapi/v2/components/schemas/LinksCourseCollection.yaml @@ -0,0 +1,9 @@ +type: object +description: | + Hypermedia link to the _Courses_ collection associated with this resource. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml b/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml index 463354c..ba5b5dc 100644 --- a/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml +++ b/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml @@ -4,6 +4,7 @@ required: properties: multiline: type: string - description: Value + minLength: 1 + description: Text value, which may contain markup. lang: $ref: ./Lang.yaml diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index d64dfd1..107bb88 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -1,71 +1,159 @@ type: type: string description: JSON:API resource type. + enum: ['programme'] id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, - but any string that is unique within the realm of the Institution may be used. - format: uuid + but any value that is unique within the realm of the Institution may be used. + # format: uuid attributes: type: object description: JSON:API _attributes_ object. required: - title - code - - description - ects - eqfLevelProvided - - iscedCode - - languageOfInstruction - - length properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: ./StringWithOptionalLang.yaml code: type: string + minLength: 1 description: Human readable code identifying the Programme. - description: - type: array - description: Description with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml ects: type: integer + minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: type: integer minimum: 5 maximum: 8 description: | - [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) - provided to the learner upon completing the Programme. + European Qualifications Framework (EQF) level provided to the learner + upon completing the Programme. + + **Usage** + + - EQF level **5** for short cycle Programmes; + - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); + - EQF level **7** for short cycle Programmes (i.e. Master's degree); + - EQF level **8** for short cycle Programmes (i.e. Doctorate). + + **References** + + [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml iscedCode: - type: string + type: array + minItems: 1 description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Programme. + ISCED-F code describing the field of education of the Programme. + + Multiple values are allowed in order to support multidisplinary + Programmes. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 languageOfInstruction: - type: string + type: array + minItems: 1 description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, + region, etc. + + **Usage** - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml length: - type: integer - minimum: 1 - description: Length of the Programme in **years**. + type: string + pattern: '^\d{1,2}\/\d$' + description: | + Length of the Programme in **number of academic terms**. + + The first numeric component matching `\d{1,2}` indicates the total + number of academic terms, while the second component matching `\d` + indicates the fraction of a full academic year corresponding to a + single academic term. + + **Usage** + + - `6/2` indicates six (6) semesters (1/2) equivalent to three full + academic years; + - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a + half academic years; + - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full + academic years; + - `3/1` indicates three (3) full years (1/1) absent a division in terms. url: type: array description: External URL with optional language code. items: $ref: ./HttpWithOptionalLang.yaml + validSince: + type: date + description: | + The first date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + validUntil: + type: date + description: | + The last date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) links: type: object description: JSON:API _links_ object. @@ -74,3 +162,5 @@ links: properties: self: $ref: ./LinksResource.yaml + course: + $ref: ./LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/ProgrammeResource.yaml b/openapi/v2/components/schemas/ProgrammeResource.yaml index a153c05..aca0622 100644 --- a/openapi/v2/components/schemas/ProgrammeResource.yaml +++ b/openapi/v2/components/schemas/ProgrammeResource.yaml @@ -24,13 +24,3 @@ properties: properties: self: $ref: ./LinksResource.yaml - course: - type: object - description: | - Hypermedia link to the _Courses_ collection associated to this resource. - required: - - href - properties: - href: - type: string - format: uri diff --git a/openapi/v2/components/schemas/StringWithOptionalLang.yaml b/openapi/v2/components/schemas/StringWithOptionalLang.yaml index 1560468..f92d8d1 100644 --- a/openapi/v2/components/schemas/StringWithOptionalLang.yaml +++ b/openapi/v2/components/schemas/StringWithOptionalLang.yaml @@ -4,6 +4,7 @@ required: properties: string: type: string - description: Value + minLength: 1 + description: Text value. lang: $ref: ./Lang.yaml diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index d3cb7ae..dad5a0f 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1190,6 +1190,7 @@ components: type: - string - null + minLength: 2 description: | IETF BCP 47 language tag. @@ -1213,7 +1214,8 @@ components: properties: string: type: string - description: Value + minLength: 1 + description: Text value. lang: $ref: '#/components/schemas/Lang' HttpWithOptionalLang: @@ -1224,7 +1226,7 @@ components: uri: type: string format: uri - description: Value + description: URL lang: $ref: '#/components/schemas/Lang' LinksResource: @@ -1572,9 +1574,20 @@ components: properties: multiline: type: string - description: Value + minLength: 1 + description: Text value, which may contain markup. lang: $ref: '#/components/schemas/Lang' + LinksCourseCollection: + type: object + description: | + Hypermedia link to the _Courses_ collection associated with this resource. + required: + - href + properties: + href: + type: string + format: uri ProgrammeCollection: type: object description: JSON:API collection of _Programme_ resources. @@ -1597,70 +1610,158 @@ components: type: type: string description: JSON:API resource type. + enum: + - programme id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. - format: uuid + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. required: - title - code - - description - ects - eqfLevelProvided - - iscedCode - - languageOfInstruction - - length properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' code: type: string + minLength: 1 description: Human readable code identifying the Programme. - description: - type: array - description: Description with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' ects: type: integer + minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: type: integer minimum: 5 maximum: 8 description: | - [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) - provided to the learner upon completing the Programme. + European Qualifications Framework (EQF) level provided to the learner + upon completing the Programme. + + **Usage** + + - EQF level **5** for short cycle Programmes; + - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); + - EQF level **7** for short cycle Programmes (i.e. Master's degree); + - EQF level **8** for short cycle Programmes (i.e. Doctorate). + + **References** + + [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' + description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' iscedCode: - type: string + type: array + minItems: 1 description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Programme. + ISCED-F code describing the field of education of the Programme. + + Multiple values are allowed in order to support multidisplinary + Programmes. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 languageOfInstruction: - type: string + type: array + minItems: 1 description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + IETF BCP 47 language tag. - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + Language tags allow to specify languages and their variations on script, + region, etc. - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: - type: integer - minimum: 1 - description: Length of the Programme in **years**. + type: string + pattern: ^\d{1,2}\/\d$ + description: | + Length of the Programme in **number of academic terms**. + + The first numeric component matching `\d{1,2}` indicates the total + number of academic terms, while the second component matching `\d` + indicates the fraction of a full academic year corresponding to a + single academic term. + + **Usage** + + - `6/2` indicates six (6) semesters (1/2) equivalent to three full + academic years; + - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a + half academic years; + - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full + academic years; + - `3/1` indicates three (3) full years (1/1) absent a division in terms. url: type: array description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + validSince: + type: date + description: | + The first date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + validUntil: + type: date + description: | + The last date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) links: type: object description: JSON:API _links_ object. @@ -1669,6 +1770,8 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. @@ -1696,70 +1799,158 @@ components: type: type: string description: JSON:API resource type. + enum: + - programme id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. - format: uuid + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. required: - title - code - - description - ects - eqfLevelProvided - - iscedCode - - languageOfInstruction - - length properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' code: type: string + minLength: 1 description: Human readable code identifying the Programme. - description: - type: array - description: Description with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' ects: type: integer + minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: type: integer minimum: 5 maximum: 8 description: | - [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) - provided to the learner upon completing the Programme. + European Qualifications Framework (EQF) level provided to the learner + upon completing the Programme. + + **Usage** + + - EQF level **5** for short cycle Programmes; + - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); + - EQF level **7** for short cycle Programmes (i.e. Master's degree); + - EQF level **8** for short cycle Programmes (i.e. Doctorate). + + **References** + + [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' + description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' iscedCode: - type: string + type: array + minItems: 1 description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Programme. + ISCED-F code describing the field of education of the Programme. + + Multiple values are allowed in order to support multidisplinary + Programmes. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 languageOfInstruction: - type: string + type: array + minItems: 1 description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + IETF BCP 47 language tag. - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + Language tags allow to specify languages and their variations on script, + region, etc. - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: - type: integer - minimum: 1 - description: Length of the Programme in **years**. + type: string + pattern: ^\d{1,2}\/\d$ + description: | + Length of the Programme in **number of academic terms**. + + The first numeric component matching `\d{1,2}` indicates the total + number of academic terms, while the second component matching `\d` + indicates the fraction of a full academic year corresponding to a + single academic term. + + **Usage** + + - `6/2` indicates six (6) semesters (1/2) equivalent to three full + academic years; + - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a + half academic years; + - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full + academic years; + - `3/1` indicates three (3) full years (1/1) absent a division in terms. url: type: array description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + validSince: + type: date + description: | + The first date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + validUntil: + type: date + description: | + The last date in which the Programme was offered. + + **Usage** + + Dates must be formatted as _YYYY-MM-DD_. + + **References** + + [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) links: type: object description: JSON:API _links_ object. @@ -1768,22 +1959,14 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. properties: self: $ref: '#/components/schemas/LinksResource' - course: - type: object - description: | - Hypermedia link to the _Courses_ collection associated to this resource. - required: - - href - properties: - href: - type: string - format: uri CourseMeta: type: object description: | From ec12f067190e5baabd07bd7b38612fa42bc11db6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Fri, 5 Sep 2025 21:07:45 +0200 Subject: [PATCH 03/23] Adds ELM vocabularies to Programme per #48 --- .../v2/components/schemas/ProgrammeData.yaml | 77 ++++++++++++ public/v2/openapi.yaml | 116 ++++++++++++++++++ 2 files changed, 193 insertions(+) diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index 107bb88..5a01d42 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -59,6 +59,83 @@ attributes: description: Description with optional language code. items: $ref: ./MultilineStringWithOptionalLang.yaml + elmLearningOpportunityType: + type: array + description: | + **Learning opportunity type** as defined in the European Learning Model + (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Programmes. + + **Usage** + + - `79343569f3` represents _Educational programme_ + - `0f7dac46ca` represents _Programme module_ + - `74a4a268e8` represents _Short learning programme_ + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) + items: + type: string + enum: [ + '79343569f3', + '0f7dac46ca', + '74a4a268e8' + ] + elmLearningScheduleType: + type: array + description: | + **Learning schedule type** as defined in the European Learning Model + (ELM). + + **Usage** + + - `72a0ab92fa` represents _Full time_ + - `f230bae523` represents _Part time intensive_ + - `67395e6b5a` represents _Part time light_ + + **References** + + [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) + items: + type: string + enum: [ + '72a0ab92fa', + 'f230bae523', + '67395e6b5a' + ] + elmModeOfLearning: + type: array + description: | + **Mode of learning and assessment** as defined in the European Learning + Model (ELM). + + **Usage** + + - `e92d221e4d` represents _Blended_ + - `c_3a90b26d` represents _Hybrid_ + - `920fbb3cbe` represents _Online_ + - `9191af2ed9` represents _Presential_ + - `7813801c77` represents _Project based_ + - `ed4c557045` represents _Research-Lab based_ + - `729f3bed4b` represents _Workbased_ + + **References** + + [Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2) + items: + type: string + enum: [ + 'e92d221e4d', + 'c_3a90b26d', + '920fbb3cbe', + '9191af2ed9', + '7813801c77', + 'ed4c557045', + '729f3bed4b' + ] iscedCode: type: array minItems: 1 diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index dad5a0f..0806b02 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1667,6 +1667,64 @@ components: description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' + elmLearningOpportunityType: + type: array + description: | + **Learning opportunity type** as defined in the European Learning Model + (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Programmes. + + **Usage** + + - `79343569f3` represents _Educational programme_ + - `0f7dac46ca` represents _Programme module_ + - `74a4a268e8` represents _Short learning programme_ + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) + items: + type: string + enum: + - 79343569f3 + - 0f7dac46ca + - 74a4a268e8 + elmLearningScheduleType: + type: array + description: | + **Learning schedule type** as defined in the European Learning Model + (ELM). + + **Usage** + + - `72a0ab92fa` represents _Full time_ + - `f230bae523` represents _Part time intensive_ + - `67395e6b5a` represents _Part time light_ + + **References** + + [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) + items: + type: string + enum: + - 72a0ab92fa + - f230bae523 + - 67395e6b5a + elmModeOfLearning: + type: array + description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" + items: + type: string + enum: + - e92d221e4d + - c_3a90b26d + - 920fbb3cbe + - 9191af2ed9 + - 7813801c77 + - ed4c557045 + - 729f3bed4b iscedCode: type: array minItems: 1 @@ -1856,6 +1914,64 @@ components: description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' + elmLearningOpportunityType: + type: array + description: | + **Learning opportunity type** as defined in the European Learning Model + (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Programmes. + + **Usage** + + - `79343569f3` represents _Educational programme_ + - `0f7dac46ca` represents _Programme module_ + - `74a4a268e8` represents _Short learning programme_ + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) + items: + type: string + enum: + - 79343569f3 + - 0f7dac46ca + - 74a4a268e8 + elmLearningScheduleType: + type: array + description: | + **Learning schedule type** as defined in the European Learning Model + (ELM). + + **Usage** + + - `72a0ab92fa` represents _Full time_ + - `f230bae523` represents _Part time intensive_ + - `67395e6b5a` represents _Part time light_ + + **References** + + [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) + items: + type: string + enum: + - 72a0ab92fa + - f230bae523 + - 67395e6b5a + elmModeOfLearning: + type: array + description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" + items: + type: string + enum: + - e92d221e4d + - c_3a90b26d + - 920fbb3cbe + - 9191af2ed9 + - 7813801c77 + - ed4c557045 + - 729f3bed4b iscedCode: type: array minItems: 1 From cf7b93cff0fe83f96bf6e56f3f70e896259b7e3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Sat, 6 Sep 2025 01:05:55 +0200 Subject: [PATCH 04/23] Initial review of Courses; covers #26 #49 #50 #51 --- openapi/v2/components/schemas/CourseData.yaml | 79 +--- .../schemas/CourseDataExtended.yaml | 104 +---- .../schemas/CourseDataExtendedProperties.yaml | 123 ++++++ .../schemas/CourseDataProperties.yaml | 87 ++++ .../components/schemas/ElmAssessmentType.yaml | 50 +++ .../schemas/ElmLearningActivityType.yaml | 38 ++ .../ElmLearningOpportunityTypeCourse.yaml | 37 ++ .../ElmModeOfLearningAndAssessment.yaml | 29 ++ .../schemas/LanguageOfInstruction.yaml | 22 + .../schemas/LocalClassification.yaml | 21 + public/v2/openapi.yaml | 389 +++++++++++++----- 11 files changed, 707 insertions(+), 272 deletions(-) create mode 100644 openapi/v2/components/schemas/CourseDataExtendedProperties.yaml create mode 100644 openapi/v2/components/schemas/CourseDataProperties.yaml create mode 100644 openapi/v2/components/schemas/ElmAssessmentType.yaml create mode 100644 openapi/v2/components/schemas/ElmLearningActivityType.yaml create mode 100644 openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml create mode 100644 openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml create mode 100644 openapi/v2/components/schemas/LanguageOfInstruction.yaml create mode 100644 openapi/v2/components/schemas/LocalClassification.yaml diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index b23c80f..fccc96b 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -1,92 +1,21 @@ type: type: string description: JSON:API resource type. + enum: ['course'] id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, - but any string that is unique within the realm of the Institution may be used. - format: uuid + but any value that is unique within the realm of the Institution may be used. + # format: uuid attributes: type: object description: JSON:API _attributes_ object. required: - title - code - - description - - learningOutcomes - - academicTerm - ects - - languageOfInstruction - - iscedCode - # - subjectArea - # - otherCategorization properties: - title: - type: array - description: Title with optional language code. - items: - $ref: ./StringWithOptionalLang.yaml - code: - type: string - description: Human readable code identifying the Course. - description: - type: array - description: Description with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - learningOutcomes: - type: array - description: Learning outcomes with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - academicTerm: - type: string - description: | - Academic term in which the Course is delivered. - - e.g. `1/2` for first semester, - `2/2` for second semester, - `1/1` for the full academic year. - pattern: '[1-9]/[1-9]' - ects: - type: integer - description: Number of ECTS credits provided to the learner upon completing the Course. - languageOfInstruction: - type: string - description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. - - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. - iscedCode: - type: string - description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Course. - - This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. - subjectArea: - type: string - description: | - Erasmus subject area code describing the field of education of the Course. - otherCategorization: - type: string - description: | - Any other term used internally to describe the field of education of the Course. - unavailableForIncomingMobility: - type: boolean - description: | - Return `true` when the Course is not available for incoming exchange students to enroll. - - Unless explicitly stated, client implementations should assume this as `false`. - url: - type: array - description: External URL with optional language code. - items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./CourseDataProperties.yaml meta: $ref: ./CourseMeta.yaml links: diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index b709783..99c8072 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -12,111 +12,9 @@ attributes: required: - title - code - - description - - learningOutcomes - - academicTerm - ects - - languageOfInstruction - - iscedCode - # - subjectArea - # - otherCategorization properties: - title: - type: array - description: Title with optional language code. - items: - $ref: ./StringWithOptionalLang.yaml - code: - type: string - description: Human readable code identifying the Course. - description: - type: array - description: Description with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - learningOutcomes: - type: array - description: Learning outcomes with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - academicTerm: - type: string - description: | - Academic term in which the Course is delivered. - - e.g. `1/2` for first semester, - `2/2` for second semester, - `1/1` for the full academic year. - pattern: '[1-9]/[1-9]' - ects: - type: integer - description: Number of ECTS credits provided to the learner upon completing the Course. - languageOfInstruction: - type: string - description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. - - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. - iscedCode: - type: string - description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Course. - - This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. - subjectArea: - type: string - description: | - Erasmus subject area code describing the field of education of the Course. - otherCategorization: - type: string - description: | - Any other term used internally to describe the field of education of the Course. - unavailableForIncomingMobility: - type: boolean - description: | - Return `true` when the Course is not available for incoming exchange students to enroll. - - Unless explicitly stated, client implementations should assume this as `false`. - url: - type: array - description: External URL with optional language code. - items: - $ref: ./HttpWithOptionalLang.yaml - bibliography: - type: array - description: Bibliography with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - courseContent: - type: array - description: Course content with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - prerequisites: - type: array - description: Prerequisites with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - courseAvailability: - type: array - description: Course availability with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - teachingMethod: - type: array - description: Teaching method with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - assessmentMethod: - type: array - description: Assessment method with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./CourseDataExtendedProperties.yaml meta: $ref: ./CourseMeta.yaml links: diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml new file mode 100644 index 0000000..8009c7b --- /dev/null +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -0,0 +1,123 @@ +title: + type: array + minItems: 1 + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml +code: + type: string + minItems: 1 + description: Human readable code identifying the Course. +ects: + type: integer + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the + Course. +academicTerm: + type: array + description: | + Academic term in which the Course is delivered. + + Multiple values are allowed in order to support Courses delivered in + in more than one academic term throughout an academic year. + + **Usage** + + - `1/2` indicates first (1) semester (1/2); + - `2/3` indicates second (2) trimester (1/3); + - `1/1` indicates full academic year. + items: + type: string + pattern: '^[1-9]\/[1/9]$' +description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +elmAssessmentType: + $ref: ./ElmAssessmentType.yaml +elmLearningActivityType: + $ref: ./ElmLearningActivityType.yaml +elmLearningOpportunityType: + $ref: ./ElmLearningOpportunityTypeCourse.yaml +elmModeOfLearning: + $ref: ./ElmModeOfLearningAndAssessment.yaml +iscedCode: + type: array + description: | + ISCED-F code describing the field of education of the Course. + + Multiple values are allowed in order to support multidisplinary + Courses. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 +languageOfInstruction: + $ref: ./LanguageOfInstruction.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +localClassification: + $ref: ./LocalClassification.yaml +restrictedToLocalStudents: + type: boolean + description: | + Return `true` when enrollment in the Course is restricted to students + enrolled at this Institution. +restrictedToAllianceStudents: + type: boolean + description: | + Return `true` when enrollment in the Course is restricted to students + enrolled at a partner Institution in the same University Alliance. +url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +bibliography: + type: array + description: Bibliography with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +courseContent: + type: array + description: Course content with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +prerequisites: + type: array + description: Prerequisites with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +courseAvailability: + type: array + description: Course availability with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +teachingMethod: + type: array + description: | + Teaching method with optional language code. + + **Note:** It is preferable to use `elmLearningActivityType` instead. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +assessmentMethod: + type: array + description: | + Assessment method with optional language code. + + **Note:** It is preferable to use `elmAssessmentType` instead. + items: + $ref: ./MultilineStringWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml new file mode 100644 index 0000000..35be374 --- /dev/null +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -0,0 +1,87 @@ +title: + type: array + minItems: 1 + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml +code: + type: string + minItems: 1 + description: Human readable code identifying the Course. +ects: + type: integer + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the + Course. +academicTerm: + type: array + description: | + Academic term in which the Course is delivered. + + Multiple values are allowed in order to support Courses delivered in + in more than one academic term throughout an academic year. + + **Usage** + + - `1/2` indicates first (1) semester (1/2); + - `2/3` indicates second (2) trimester (1/3); + - `1/1` indicates full academic year. + items: + type: string + pattern: '^[1-9]\/[1/9]$' +description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +elmAssessmentType: + $ref: ./ElmAssessmentType.yaml +elmLearningActivityType: + $ref: ./ElmLearningActivityType.yaml +elmLearningOpportunityType: + $ref: ./ElmLearningOpportunityTypeCourse.yaml +elmModeOfLearning: + $ref: ./ElmModeOfLearningAndAssessment.yaml +iscedCode: + type: array + description: | + ISCED-F code describing the field of education of the Course. + + Multiple values are allowed in order to support multidisplinary + Courses. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 +languageOfInstruction: + $ref: ./LanguageOfInstruction.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +localClassification: + $ref: ./LocalClassification.yaml +restrictedToLocalStudents: + type: boolean + description: | + Return `true` when enrollment in the Course is restricted to students + enrolled at this Institution. +restrictedToAllianceStudents: + type: boolean + description: | + Return `true` when enrollment in the Course is restricted to students + enrolled at a partner Institution in the same University Alliance. +url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/ElmAssessmentType.yaml b/openapi/v2/components/schemas/ElmAssessmentType.yaml new file mode 100644 index 0000000..b35ae7f --- /dev/null +++ b/openapi/v2/components/schemas/ElmAssessmentType.yaml @@ -0,0 +1,50 @@ +type: array +description: | + **Assessment type** as defined in the European Learning Model (ELM). + + **Usage** + + - `de4d165a6c` represents _artefact assessment_; + - `3484bd7e51` represents _continuous evaluation_; + - `56539a6507` represents _group performance_; + - `c_4f874951` represents _Guided self-assessment_; + - `7331eb4762` represents _level of attendance_; + - `2939dae15f` represents _marked assignment_; + - `d30284d7df` represents _oral examination_; + - `19a2e5e671` represents _peer assessment_; + - `812e3b0ae1` represents _peer review_; + - `812e3b0ae1` represents _peer review_; + - `4f03b91c0e` represents _portfolio_; + - `6a4db9f11d` represents _practical assessment_; + - `c_04b30a72` represents _Presentation_; + - `c4256a2726` represents _problem based learning_; + - `795dac4096` represents _project work_; + - `b1b68f6735` represents _quiz_; + - `c_2b3bd410` represents _Self-assessment_; + - `6e6cb2cc78` represents _written examination_. + + **References** + + [Assessment type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/assessment/25831c2) +items: + type: string + enum: [ + 'de4d165a6c', + '3484bd7e51', + '56539a6507', + 'c_4f874951', + '7331eb4762', + '2939dae15f', + 'd30284d7df', + '19a2e5e671', + '812e3b0ae1', + '812e3b0ae1', + '4f03b91c0e', + '6a4db9f11d', + 'c_04b30a72', + 'c4256a2726', + '795dac4096', + 'b1b68f6735', + 'c_2b3bd410', + '6e6cb2cc78' + ] diff --git a/openapi/v2/components/schemas/ElmLearningActivityType.yaml b/openapi/v2/components/schemas/ElmLearningActivityType.yaml new file mode 100644 index 0000000..ec0b191 --- /dev/null +++ b/openapi/v2/components/schemas/ElmLearningActivityType.yaml @@ -0,0 +1,38 @@ +type: array +description: | + **Learning activity type** as defined in the European Learning Model (ELM). + + **Usage** + + - `d46a826a39` represents _apprenticeship_; + - `ff436ea7c9` represents _classroom coursework_; + - `bf2e3a7bae` represents _e-learning coursework_; + - `fd33e234ae` represents _educational programme_; + - `bf5588ff84` represents _internship_; + - `4357e0e681` represents _job experience_; + - `3c8bd58d62` represents _lab / simulation / practice coursework_; + - `c_5665a0ad` represents _mentoring and monitoring activity_; + - `a7e556215a` represents _research_; + - `b660f5dcea` represents _self-motivated study_; + - `59eaf34fab` represents _volunteering_; + - `efff75e10a` represents _workshop, seminar or conference_. + + **References** + + [Learning activity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-activity/25831c2) +items: + type: string + enum: [ + d46a826a39, + ff436ea7c9, + bf2e3a7bae, + fd33e234ae, + bf5588ff84, + 4357e0e681, + 3c8bd58d62, + c_5665a0ad, + a7e556215a, + b660f5dcea, + 59eaf34fab, + efff75e10a + ] diff --git a/openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml b/openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml new file mode 100644 index 0000000..eb0be3b --- /dev/null +++ b/openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml @@ -0,0 +1,37 @@ +type: array +description: | + **Learning opportunity type** as defined in the European Learning Model (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Courses. + + **Usage** + + - `63f9f6180c` represents _Apprenticeship_; + - `c_170b037d` represents _Challenge_; + - `7e1ac538db` represents _Class_; + - `05053c1cbe` represents _Course_; + - `77b99de990` represents _Internship_; + - `17744a2647` represents _MOOC_; + - `11252a5207` represents _Mentoring_; + - `8b965da2d4` represents _Service learning_; + - `65a4cf5de2` represents _Study visit_; + - `b2434ca358` represents _Thesis_. + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) +items: + type: string + enum: [ + '63f9f6180c', + 'c_170b037d', + '7e1ac538db', + '05053c1cbe', + '77b99de990', + '17744a2647', + '11252a5207', + '8b965da2d4', + '65a4cf5de2', + 'b2434ca358' + ] diff --git a/openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml b/openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml new file mode 100644 index 0000000..fc541ce --- /dev/null +++ b/openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml @@ -0,0 +1,29 @@ +type: array +description: | + **Mode of learning and assessment** as defined in the European Learning + Model (ELM). + + **Usage** + + - `e92d221e4d` represents _Blended_ + - `c_3a90b26d` represents _Hybrid_ + - `920fbb3cbe` represents _Online_ + - `9191af2ed9` represents _Presential_ + - `7813801c77` represents _Project based_ + - `ed4c557045` represents _Research-Lab based_ + - `729f3bed4b` represents _Workbased_ + + **References** + + [Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2) +items: + type: string + enum: [ + 'e92d221e4d', + 'c_3a90b26d', + '920fbb3cbe', + '9191af2ed9', + '7813801c77', + 'ed4c557045', + '729f3bed4b' + ] diff --git a/openapi/v2/components/schemas/LanguageOfInstruction.yaml b/openapi/v2/components/schemas/LanguageOfInstruction.yaml new file mode 100644 index 0000000..e4fe08f --- /dev/null +++ b/openapi/v2/components/schemas/LanguageOfInstruction.yaml @@ -0,0 +1,22 @@ +type: array +minItems: 1 +description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, + region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) +items: + type: string + minLength: 2 diff --git a/openapi/v2/components/schemas/LocalClassification.yaml b/openapi/v2/components/schemas/LocalClassification.yaml new file mode 100644 index 0000000..70dbd6b --- /dev/null +++ b/openapi/v2/components/schemas/LocalClassification.yaml @@ -0,0 +1,21 @@ +type: array +description: | + Indicates a local (national or other) classification system for fields + of study, followed by the applicable value (or code) in that system. + + Multiple values are allowed in order to support multidisplinary + Courses. +items: + type: object + required: + - classificationSystem + - classificationValue + properties: + classificationSystem: + type: string + description: 'Classification system' + minLength: 1 + classificationValue: + type: string + description: 'Classification value' + minLength: 1 diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 0806b02..1f57635 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2083,6 +2083,168 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + ElmAssessmentType: + type: array + description: | + **Assessment type** as defined in the European Learning Model (ELM). + + **Usage** + + - `de4d165a6c` represents _artefact assessment_; + - `3484bd7e51` represents _continuous evaluation_; + - `56539a6507` represents _group performance_; + - `c_4f874951` represents _Guided self-assessment_; + - `7331eb4762` represents _level of attendance_; + - `2939dae15f` represents _marked assignment_; + - `d30284d7df` represents _oral examination_; + - `19a2e5e671` represents _peer assessment_; + - `812e3b0ae1` represents _peer review_; + - `812e3b0ae1` represents _peer review_; + - `4f03b91c0e` represents _portfolio_; + - `6a4db9f11d` represents _practical assessment_; + - `c_04b30a72` represents _Presentation_; + - `c4256a2726` represents _problem based learning_; + - `795dac4096` represents _project work_; + - `b1b68f6735` represents _quiz_; + - `c_2b3bd410` represents _Self-assessment_; + - `6e6cb2cc78` represents _written examination_. + + **References** + + [Assessment type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/assessment/25831c2) + items: + type: string + enum: + - de4d165a6c + - 3484bd7e51 + - 56539a6507 + - c_4f874951 + - 7331eb4762 + - 2939dae15f + - d30284d7df + - 19a2e5e671 + - 812e3b0ae1 + - 812e3b0ae1 + - 4f03b91c0e + - 6a4db9f11d + - c_04b30a72 + - c4256a2726 + - 795dac4096 + - b1b68f6735 + - c_2b3bd410 + - 6e6cb2cc78 + ElmLearningActivityType: + type: array + description: | + **Learning activity type** as defined in the European Learning Model (ELM). + + **Usage** + + - `d46a826a39` represents _apprenticeship_; + - `ff436ea7c9` represents _classroom coursework_; + - `bf2e3a7bae` represents _e-learning coursework_; + - `fd33e234ae` represents _educational programme_; + - `bf5588ff84` represents _internship_; + - `4357e0e681` represents _job experience_; + - `3c8bd58d62` represents _lab / simulation / practice coursework_; + - `c_5665a0ad` represents _mentoring and monitoring activity_; + - `a7e556215a` represents _research_; + - `b660f5dcea` represents _self-motivated study_; + - `59eaf34fab` represents _volunteering_; + - `efff75e10a` represents _workshop, seminar or conference_. + + **References** + + [Learning activity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-activity/25831c2) + items: + type: string + enum: + - d46a826a39 + - ff436ea7c9 + - bf2e3a7bae + - fd33e234ae + - bf5588ff84 + - 4357e0e681 + - 3c8bd58d62 + - c_5665a0ad + - a7e556215a + - b660f5dcea + - 59eaf34fab + - efff75e10a + ElmLearningOpportunityTypeCourse: + type: array + description: "**Learning opportunity type** as defined in the European Learning Model (ELM).\n\n_Note_: limited to the items in the controlled vocabulary that may apply\n to Courses.\n\n**Usage**\n\n- `63f9f6180c` represents\t_Apprenticeship_;\n- `c_170b037d` represents\t_Challenge_;\n- `7e1ac538db` represents\t_Class_;\n- `05053c1cbe` represents\t_Course_;\n- `77b99de990` represents\t_Internship_;\n- `17744a2647` represents\t_MOOC_;\n- `11252a5207` represents\t_Mentoring_;\n- `8b965da2d4` represents\t_Service learning_;\n- `65a4cf5de2` represents\t_Study visit_;\n- `b2434ca358` represents\t_Thesis_.\n\n**References**\n\n[Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2)\n" + items: + type: string + enum: + - 63f9f6180c + - c_170b037d + - 7e1ac538db + - 05053c1cbe + - 77b99de990 + - 17744a2647 + - 11252a5207 + - 8b965da2d4 + - 65a4cf5de2 + - b2434ca358 + ElmModeOfLearningAndAssessment: + type: array + description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" + items: + type: string + enum: + - e92d221e4d + - c_3a90b26d + - 920fbb3cbe + - 9191af2ed9 + - 7813801c77 + - ed4c557045 + - 729f3bed4b + LanguageOfInstruction: + type: array + minItems: 1 + description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, + region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 + LocalClassification: + type: array + description: | + Indicates a local (national or other) classification system for fields + of study, followed by the applicable value (or code) in that system. + + Multiple values are allowed in order to support multidisplinary + Courses. + items: + type: object + required: + - classificationSystem + - classificationValue + properties: + classificationSystem: + type: string + description: Classification system + minLength: 1 + classificationValue: + type: string + description: Classification value + minLength: 1 CourseMeta: type: object description: | @@ -2156,84 +2318,101 @@ components: type: type: string description: JSON:API resource type. + enum: + - course id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. - format: uuid + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. required: - title - code - - description - - learningOutcomes - - academicTerm - ects - - languageOfInstruction - - iscedCode properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' code: type: string + minItems: 1 description: Human readable code identifying the Course. + ects: + type: integer + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the + Course. + academicTerm: + type: array + description: | + Academic term in which the Course is delivered. + + Multiple values are allowed in order to support Courses delivered in + in more than one academic term throughout an academic year. + + **Usage** + + - `1/2` indicates first (1) semester (1/2); + - `2/3` indicates second (2) trimester (1/3); + - `1/1` indicates full academic year. + items: + type: string + pattern: ^[1-9]\/[1/9]$ description: type: array + minItems: 1 description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' - learningOutcomes: + elmAssessmentType: + $ref: '#/components/schemas/ElmAssessmentType' + elmLearningActivityType: + $ref: '#/components/schemas/ElmLearningActivityType' + elmLearningOpportunityType: + $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' + elmModeOfLearning: + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + iscedCode: type: array - description: Learning outcomes with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - academicTerm: - type: string - description: | - Academic term in which the Course is delivered. - - e.g. `1/2` for first semester, - `2/2` for second semester, - `1/1` for the full academic year. - pattern: '[1-9]/[1-9]' - ects: - type: integer - description: Number of ECTS credits provided to the learner upon completing the Course. - languageOfInstruction: - type: string description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. + ISCED-F code describing the field of education of the Course. - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + Multiple values are allowed in order to support multidisplinary + Courses. - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. - iscedCode: - type: string - description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Course. + **References** - This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. - subjectArea: - type: string - description: | - Erasmus subject area code describing the field of education of the Course. - otherCategorization: - type: string + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + localClassification: + $ref: '#/components/schemas/LocalClassification' + restrictedToLocalStudents: + type: boolean description: | - Any other term used internally to describe the field of education of the Course. - unavailableForIncomingMobility: + Return `true` when enrollment in the Course is restricted to students + enrolled at this Institution. + restrictedToAllianceStudents: type: boolean description: | - Return `true` when the Course is not available for incoming exchange students to enroll. - - Unless explicitly stated, client implementations should assume this as `false`. + Return `true` when enrollment in the Course is restricted to students + enrolled at a partner Institution in the same University Alliance. url: type: array description: External URL with optional language code. @@ -2285,74 +2464,90 @@ components: required: - title - code - - description - - learningOutcomes - - academicTerm - ects - - languageOfInstruction - - iscedCode properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' code: type: string + minItems: 1 description: Human readable code identifying the Course. + ects: + type: integer + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the + Course. + academicTerm: + type: array + description: | + Academic term in which the Course is delivered. + + Multiple values are allowed in order to support Courses delivered in + in more than one academic term throughout an academic year. + + **Usage** + + - `1/2` indicates first (1) semester (1/2); + - `2/3` indicates second (2) trimester (1/3); + - `1/1` indicates full academic year. + items: + type: string + pattern: ^[1-9]\/[1/9]$ description: type: array + minItems: 1 description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' - learningOutcomes: + elmAssessmentType: + $ref: '#/components/schemas/ElmAssessmentType' + elmLearningActivityType: + $ref: '#/components/schemas/ElmLearningActivityType' + elmLearningOpportunityType: + $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' + elmModeOfLearning: + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + iscedCode: type: array - description: Learning outcomes with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - academicTerm: - type: string description: | - Academic term in which the Course is delivered. + ISCED-F code describing the field of education of the Course. - e.g. `1/2` for first semester, - `2/2` for second semester, - `1/1` for the full academic year. - pattern: '[1-9]/[1-9]' - ects: - type: integer - description: Number of ECTS credits provided to the learner upon completing the Course. - languageOfInstruction: - type: string - description: | - Language code in - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - - Optionally the country locale can be indicated in - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. + Multiple values are allowed in order to support multidisplinary + Courses. - e.g. `pt` for Portuguese, `pt-PT` for European Portuguese. - iscedCode: - type: string - description: | - [ISCED-F code](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - describing the field of education of the Course. + **References** - This may be left empty **if** a value for `subjectArea` or `otherCategorization` is provided. - subjectArea: - type: string - description: | - Erasmus subject area code describing the field of education of the Course. - otherCategorization: - type: string + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + localClassification: + $ref: '#/components/schemas/LocalClassification' + restrictedToLocalStudents: + type: boolean description: | - Any other term used internally to describe the field of education of the Course. - unavailableForIncomingMobility: + Return `true` when enrollment in the Course is restricted to students + enrolled at this Institution. + restrictedToAllianceStudents: type: boolean description: | - Return `true` when the Course is not available for incoming exchange students to enroll. - - Unless explicitly stated, client implementations should assume this as `false`. + Return `true` when enrollment in the Course is restricted to students + enrolled at a partner Institution in the same University Alliance. url: type: array description: External URL with optional language code. @@ -2380,12 +2575,18 @@ components: $ref: '#/components/schemas/MultilineStringWithOptionalLang' teachingMethod: type: array - description: Teaching method with optional language code. + description: | + Teaching method with optional language code. + + **Note:** It is preferable to use `elmLearningActivityType` instead. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' assessmentMethod: type: array - description: Assessment method with optional language code. + description: | + Assessment method with optional language code. + + **Note:** It is preferable to use `elmAssessmentType` instead. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' meta: From b1344766962929d9a23e55eb3cbd53673a9d7399 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Sat, 6 Sep 2025 01:29:03 +0200 Subject: [PATCH 05/23] Refactoring for readability and reusability --- .../ElmLearningOpportunityTypeProgramme.yaml | 23 + .../schemas/ElmLearningScheduleType.yaml | 20 + .../components/schemas/EqfLevelProvided.yaml | 17 + .../v2/components/schemas/ProgrammeData.yaml | 216 +-------- .../schemas/ProgrammeDataProperties.yaml | 75 +++ .../components/schemas/ProgrammeLength.yaml | 19 + public/v2/openapi.yaml | 439 ++++++------------ 7 files changed, 294 insertions(+), 515 deletions(-) create mode 100644 openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml create mode 100644 openapi/v2/components/schemas/ElmLearningScheduleType.yaml create mode 100644 openapi/v2/components/schemas/EqfLevelProvided.yaml create mode 100644 openapi/v2/components/schemas/ProgrammeDataProperties.yaml create mode 100644 openapi/v2/components/schemas/ProgrammeLength.yaml diff --git a/openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml b/openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml new file mode 100644 index 0000000..ff0f5f4 --- /dev/null +++ b/openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml @@ -0,0 +1,23 @@ +type: array +description: | + **Learning opportunity type** as defined in the European Learning Model (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Programmes. + + **Usage** + + - `79343569f3` represents _Educational programme_ + - `0f7dac46ca` represents _Programme module_ + - `74a4a268e8` represents _Short learning programme_ + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) +items: + type: string + enum: [ + '79343569f3', + '0f7dac46ca', + '74a4a268e8' + ] diff --git a/openapi/v2/components/schemas/ElmLearningScheduleType.yaml b/openapi/v2/components/schemas/ElmLearningScheduleType.yaml new file mode 100644 index 0000000..bd336eb --- /dev/null +++ b/openapi/v2/components/schemas/ElmLearningScheduleType.yaml @@ -0,0 +1,20 @@ +type: array +description: | + **Learning schedule type** as defined in the European Learning Model (ELM). + + **Usage** + + - `72a0ab92fa` represents _Full time_ + - `f230bae523` represents _Part time intensive_ + - `67395e6b5a` represents _Part time light_ + + **References** + + [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) +items: + type: string + enum: [ + '72a0ab92fa', + 'f230bae523', + '67395e6b5a' + ] diff --git a/openapi/v2/components/schemas/EqfLevelProvided.yaml b/openapi/v2/components/schemas/EqfLevelProvided.yaml new file mode 100644 index 0000000..a01a497 --- /dev/null +++ b/openapi/v2/components/schemas/EqfLevelProvided.yaml @@ -0,0 +1,17 @@ +type: integer +minimum: 5 +maximum: 8 +description: | + European Qualifications Framework (EQF) level provided to the learner + upon completing the Programme. + + **Usage** + + - EQF level **5** for short cycle Programmes; + - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); + - EQF level **7** for short cycle Programmes (i.e. Master's degree); + - EQF level **8** for short cycle Programmes (i.e. Doctorate). + + **References** + + [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index 5a01d42..3b9ac2e 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -16,221 +16,7 @@ attributes: - ects - eqfLevelProvided properties: - title: - type: array - minItems: 1 - description: Title with optional language code. - items: - $ref: ./StringWithOptionalLang.yaml - code: - type: string - minLength: 1 - description: Human readable code identifying the Programme. - ects: - type: integer - minimum: 0 - description: Number of ECTS credits required to complete the Programme. - eqfLevelProvided: - type: integer - minimum: 5 - maximum: 8 - description: | - European Qualifications Framework (EQF) level provided to the learner - upon completing the Programme. - - **Usage** - - - EQF level **5** for short cycle Programmes; - - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); - - EQF level **7** for short cycle Programmes (i.e. Master's degree); - - EQF level **8** for short cycle Programmes (i.e. Doctorate). - - **References** - - [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) - abbreviation: - type: array - description: Abbbreviation with optional language code. - items: - $ref: ./StringWithOptionalLang.yaml - description: - type: array - minItems: 1 - description: Description with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - elmLearningOpportunityType: - type: array - description: | - **Learning opportunity type** as defined in the European Learning Model - (ELM). - - _Note_: limited to the items in the controlled vocabulary that may apply - to Programmes. - - **Usage** - - - `79343569f3` represents _Educational programme_ - - `0f7dac46ca` represents _Programme module_ - - `74a4a268e8` represents _Short learning programme_ - - **References** - - [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) - items: - type: string - enum: [ - '79343569f3', - '0f7dac46ca', - '74a4a268e8' - ] - elmLearningScheduleType: - type: array - description: | - **Learning schedule type** as defined in the European Learning Model - (ELM). - - **Usage** - - - `72a0ab92fa` represents _Full time_ - - `f230bae523` represents _Part time intensive_ - - `67395e6b5a` represents _Part time light_ - - **References** - - [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) - items: - type: string - enum: [ - '72a0ab92fa', - 'f230bae523', - '67395e6b5a' - ] - elmModeOfLearning: - type: array - description: | - **Mode of learning and assessment** as defined in the European Learning - Model (ELM). - - **Usage** - - - `e92d221e4d` represents _Blended_ - - `c_3a90b26d` represents _Hybrid_ - - `920fbb3cbe` represents _Online_ - - `9191af2ed9` represents _Presential_ - - `7813801c77` represents _Project based_ - - `ed4c557045` represents _Research-Lab based_ - - `729f3bed4b` represents _Workbased_ - - **References** - - [Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2) - items: - type: string - enum: [ - 'e92d221e4d', - 'c_3a90b26d', - '920fbb3cbe', - '9191af2ed9', - '7813801c77', - 'ed4c557045', - '729f3bed4b' - ] - iscedCode: - type: array - minItems: 1 - description: | - ISCED-F code describing the field of education of the Programme. - - Multiple values are allowed in order to support multidisplinary - Programmes. - - **References** - - [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - (PDF) - items: - type: string - minLength: 2 - maxLength: 4 - languageOfInstruction: - type: array - minItems: 1 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, - region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - items: - type: string - minLength: 2 - learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: ./MultilineStringWithOptionalLang.yaml - length: - type: string - pattern: '^\d{1,2}\/\d$' - description: | - Length of the Programme in **number of academic terms**. - - The first numeric component matching `\d{1,2}` indicates the total - number of academic terms, while the second component matching `\d` - indicates the fraction of a full academic year corresponding to a - single academic term. - - **Usage** - - - `6/2` indicates six (6) semesters (1/2) equivalent to three full - academic years; - - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a - half academic years; - - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full - academic years; - - `3/1` indicates three (3) full years (1/1) absent a division in terms. - url: - type: array - description: External URL with optional language code. - items: - $ref: ./HttpWithOptionalLang.yaml - validSince: - type: date - description: | - The first date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - validUntil: - type: date - description: | - The last date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + $ref: ./ProgrammeDataProperties.yaml links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml new file mode 100644 index 0000000..f0fc230 --- /dev/null +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -0,0 +1,75 @@ +title: + type: array + minItems: 1 + description: Title with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml +code: + type: string + minLength: 1 + description: Human readable code identifying the Programme. +ects: + type: integer + minimum: 0 + description: Number of ECTS credits required to complete the Programme. +eqfLevelProvided: + $ref: ./EqfLevelProvided.yaml +abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml +description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +elmLearningOpportunityType: + $ref: ./ElmLearningOpportunityTypeProgramme.yaml +elmLearningScheduleType: + $ref: ./ElmLearningScheduleType.yaml +elmModeOfLearning: + $ref: ./ElmModeOfLearningAndAssessment.yaml +iscedCode: + type: array + minItems: 1 + description: | + ISCED-F code describing the field of education of the Programme. + + Multiple values are allowed in order to support multidisplinary + Programmes. + + **References** + + [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) + (PDF) + items: + type: string + minLength: 2 + maxLength: 4 +languageOfInstruction: + $ref: ./LanguageOfInstruction.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./MultilineStringWithOptionalLang.yaml +length: + $ref: ./ProgrammeLength.yaml +url: + type: array + description: External URL with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml +validSince: + type: date + description: | + The first date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +validUntil: + type: date + description: | + The last date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/ProgrammeLength.yaml b/openapi/v2/components/schemas/ProgrammeLength.yaml new file mode 100644 index 0000000..096a9b4 --- /dev/null +++ b/openapi/v2/components/schemas/ProgrammeLength.yaml @@ -0,0 +1,19 @@ +type: string +pattern: '^\d{1,2}\/\d$' +description: | + Length of the Programme in **number of academic terms**. + + The first numeric component matching `\d{1,2}` indicates the total + number of academic terms, while the second component matching `\d` + indicates the fraction of a full academic year corresponding to a + single academic term. + + **Usage** + + - `6/2` indicates six (6) semesters (1/2) equivalent to three full + academic years; + - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a + half academic years; + - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full + academic years; + - `3/1` indicates three (3) full years (1/1) absent a division in terms. diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 1f57635..2a81cee 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1567,6 +1567,24 @@ components: href: type: string format: uri + EqfLevelProvided: + type: integer + minimum: 5 + maximum: 8 + description: | + European Qualifications Framework (EQF) level provided to the learner + upon completing the Programme. + + **Usage** + + - EQF level **5** for short cycle Programmes; + - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); + - EQF level **7** for short cycle Programmes (i.e. Master's degree); + - EQF level **8** for short cycle Programmes (i.e. Doctorate). + + **References** + + [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) MultilineStringWithOptionalLang: type: object required: @@ -1578,6 +1596,105 @@ components: description: Text value, which may contain markup. lang: $ref: '#/components/schemas/Lang' + ElmLearningOpportunityTypeProgramme: + type: array + description: | + **Learning opportunity type** as defined in the European Learning Model (ELM). + + _Note_: limited to the items in the controlled vocabulary that may apply + to Programmes. + + **Usage** + + - `79343569f3` represents _Educational programme_ + - `0f7dac46ca` represents _Programme module_ + - `74a4a268e8` represents _Short learning programme_ + + **References** + + [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) + items: + type: string + enum: + - 79343569f3 + - 0f7dac46ca + - 74a4a268e8 + ElmLearningScheduleType: + type: array + description: | + **Learning schedule type** as defined in the European Learning Model (ELM). + + **Usage** + + - `72a0ab92fa` represents _Full time_ + - `f230bae523` represents _Part time intensive_ + - `67395e6b5a` represents _Part time light_ + + **References** + + [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) + items: + type: string + enum: + - 72a0ab92fa + - f230bae523 + - 67395e6b5a + ElmModeOfLearningAndAssessment: + type: array + description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" + items: + type: string + enum: + - e92d221e4d + - c_3a90b26d + - 920fbb3cbe + - 9191af2ed9 + - 7813801c77 + - ed4c557045 + - 729f3bed4b + LanguageOfInstruction: + type: array + minItems: 1 + description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, + region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 + ProgrammeLength: + type: string + pattern: ^\d{1,2}\/\d$ + description: | + Length of the Programme in **number of academic terms**. + + The first numeric component matching `\d{1,2}` indicates the total + number of academic terms, while the second component matching `\d` + indicates the fraction of a full academic year corresponding to a + single academic term. + + **Usage** + + - `6/2` indicates six (6) semesters (1/2) equivalent to three full + academic years; + - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a + half academic years; + - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full + academic years; + - `3/1` indicates three (3) full years (1/1) absent a division in terms. LinksCourseCollection: type: object description: | @@ -1639,23 +1756,7 @@ components: minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: - type: integer - minimum: 5 - maximum: 8 - description: | - European Qualifications Framework (EQF) level provided to the learner - upon completing the Programme. - - **Usage** - - - EQF level **5** for short cycle Programmes; - - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); - - EQF level **7** for short cycle Programmes (i.e. Master's degree); - - EQF level **8** for short cycle Programmes (i.e. Doctorate). - - **References** - - [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + $ref: '#/components/schemas/EqfLevelProvided' abbreviation: type: array description: Abbbreviation with optional language code. @@ -1668,63 +1769,11 @@ components: items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' elmLearningOpportunityType: - type: array - description: | - **Learning opportunity type** as defined in the European Learning Model - (ELM). - - _Note_: limited to the items in the controlled vocabulary that may apply - to Programmes. - - **Usage** - - - `79343569f3` represents _Educational programme_ - - `0f7dac46ca` represents _Programme module_ - - `74a4a268e8` represents _Short learning programme_ - - **References** - - [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) - items: - type: string - enum: - - 79343569f3 - - 0f7dac46ca - - 74a4a268e8 + $ref: '#/components/schemas/ElmLearningOpportunityTypeProgramme' elmLearningScheduleType: - type: array - description: | - **Learning schedule type** as defined in the European Learning Model - (ELM). - - **Usage** - - - `72a0ab92fa` represents _Full time_ - - `f230bae523` represents _Part time intensive_ - - `67395e6b5a` represents _Part time light_ - - **References** - - [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) - items: - type: string - enum: - - 72a0ab92fa - - f230bae523 - - 67395e6b5a + $ref: '#/components/schemas/ElmLearningScheduleType' elmModeOfLearning: - type: array - description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" - items: - type: string - enum: - - e92d221e4d - - c_3a90b26d - - 920fbb3cbe - - 9191af2ed9 - - 7813801c77 - - ed4c557045 - - 729f3bed4b + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' iscedCode: type: array minItems: 1 @@ -1737,34 +1786,13 @@ components: **References** [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - (PDF) + (PDF) items: type: string minLength: 2 maxLength: 4 languageOfInstruction: - type: array - minItems: 1 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, - region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - items: - type: string - minLength: 2 + $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -1772,25 +1800,7 @@ components: items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: - type: string - pattern: ^\d{1,2}\/\d$ - description: | - Length of the Programme in **number of academic terms**. - - The first numeric component matching `\d{1,2}` indicates the total - number of academic terms, while the second component matching `\d` - indicates the fraction of a full academic year corresponding to a - single academic term. - - **Usage** - - - `6/2` indicates six (6) semesters (1/2) equivalent to three full - academic years; - - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a - half academic years; - - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full - academic years; - - `3/1` indicates three (3) full years (1/1) absent a division in terms. + $ref: '#/components/schemas/ProgrammeLength' url: type: array description: External URL with optional language code. @@ -1799,27 +1809,13 @@ components: validSince: type: date description: | - The first date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + The first date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: type: date description: | - The last date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + The last date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1886,23 +1882,7 @@ components: minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: - type: integer - minimum: 5 - maximum: 8 - description: | - European Qualifications Framework (EQF) level provided to the learner - upon completing the Programme. - - **Usage** - - - EQF level **5** for short cycle Programmes; - - EQF level **6** for first cycle Programmes (i.e. Bachelor's degree); - - EQF level **7** for short cycle Programmes (i.e. Master's degree); - - EQF level **8** for short cycle Programmes (i.e. Doctorate). - - **References** - - [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + $ref: '#/components/schemas/EqfLevelProvided' abbreviation: type: array description: Abbbreviation with optional language code. @@ -1915,63 +1895,11 @@ components: items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' elmLearningOpportunityType: - type: array - description: | - **Learning opportunity type** as defined in the European Learning Model - (ELM). - - _Note_: limited to the items in the controlled vocabulary that may apply - to Programmes. - - **Usage** - - - `79343569f3` represents _Educational programme_ - - `0f7dac46ca` represents _Programme module_ - - `74a4a268e8` represents _Short learning programme_ - - **References** - - [Learning opportunity type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-opportunity/25831c2) - items: - type: string - enum: - - 79343569f3 - - 0f7dac46ca - - 74a4a268e8 + $ref: '#/components/schemas/ElmLearningOpportunityTypeProgramme' elmLearningScheduleType: - type: array - description: | - **Learning schedule type** as defined in the European Learning Model - (ELM). - - **Usage** - - - `72a0ab92fa` represents _Full time_ - - `f230bae523` represents _Part time intensive_ - - `67395e6b5a` represents _Part time light_ - - **References** - - [Learning schedule type - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-schedule/25831c2) - items: - type: string - enum: - - 72a0ab92fa - - f230bae523 - - 67395e6b5a + $ref: '#/components/schemas/ElmLearningScheduleType' elmModeOfLearning: - type: array - description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" - items: - type: string - enum: - - e92d221e4d - - c_3a90b26d - - 920fbb3cbe - - 9191af2ed9 - - 7813801c77 - - ed4c557045 - - 729f3bed4b + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' iscedCode: type: array minItems: 1 @@ -1984,34 +1912,13 @@ components: **References** [Fields of education and training 2013](http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-fields-of-education-and-training-2013-detailed-field-descriptions-2015-en.pdf) - (PDF) + (PDF) items: type: string minLength: 2 maxLength: 4 languageOfInstruction: - type: array - minItems: 1 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, - region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - items: - type: string - minLength: 2 + $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -2019,25 +1926,7 @@ components: items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: - type: string - pattern: ^\d{1,2}\/\d$ - description: | - Length of the Programme in **number of academic terms**. - - The first numeric component matching `\d{1,2}` indicates the total - number of academic terms, while the second component matching `\d` - indicates the fraction of a full academic year corresponding to a - single academic term. - - **Usage** - - - `6/2` indicates six (6) semesters (1/2) equivalent to three full - academic years; - - `7/2` indicates seven (7) semesters (1/2) equivalent to three and a - half academic years; - - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full - academic years; - - `3/1` indicates three (3) full years (1/1) absent a division in terms. + $ref: '#/components/schemas/ProgrammeLength' url: type: array description: External URL with optional language code. @@ -2046,27 +1935,13 @@ components: validSince: type: date description: | - The first date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + The first date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: type: date description: | - The last date in which the Programme was offered. - - **Usage** - - Dates must be formatted as _YYYY-MM-DD_. - - **References** - - [Internet Date/Time Format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + The last date in which the Programme was offered, formatted as + [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2187,42 +2062,6 @@ components: - 8b965da2d4 - 65a4cf5de2 - b2434ca358 - ElmModeOfLearningAndAssessment: - type: array - description: "**Mode of learning and assessment** as defined in the European Learning\n Model (ELM).\n\n**Usage**\n\n- `e92d221e4d` represents\t_Blended_\n- `c_3a90b26d` represents\t_Hybrid_\n- `920fbb3cbe` represents\t_Online_\n- `9191af2ed9` represents\t_Presential_\n- `7813801c77` represents\t_Project based_\n- `ed4c557045` represents\t_Research-Lab based_\n- `729f3bed4b` represents\t_Workbased_\n\n**References**\n\n[Mode of learning and assessment - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/learning-assessment/25831c2)\n" - items: - type: string - enum: - - e92d221e4d - - c_3a90b26d - - 920fbb3cbe - - 9191af2ed9 - - 7813801c77 - - ed4c557045 - - 729f3bed4b - LanguageOfInstruction: - type: array - minItems: 1 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, - region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - items: - type: string - minLength: 2 LocalClassification: type: array description: | From 22bb46292bb659f0a49b5b81f185ae473cdc7128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Mon, 8 Sep 2025 09:50:10 +0200 Subject: [PATCH 06/23] Introduces lastModified field in all resource types --- openapi/v2/components/schemas/CourseData.yaml | 1 + .../schemas/CourseDataExtended.yaml | 1 + .../schemas/CourseDataExtendedProperties.yaml | 9 ++- .../schemas/CourseDataProperties.yaml | 9 ++- .../components/schemas/InstitutionData.yaml | 7 ++ openapi/v2/components/schemas/OunitData.yaml | 7 ++ .../v2/components/schemas/ProgrammeData.yaml | 1 + .../schemas/ProgrammeDataProperties.yaml | 12 ++- public/v2/openapi.yaml | 74 +++++++++++++++++-- 9 files changed, 107 insertions(+), 14 deletions(-) diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index fccc96b..aa7e86d 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -14,6 +14,7 @@ attributes: - title - code - ects + - lastModified properties: $ref: ./CourseDataProperties.yaml meta: diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index 99c8072..5bb28ca 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -13,6 +13,7 @@ attributes: - title - code - ects + - lastModified properties: $ref: ./CourseDataExtendedProperties.yaml meta: diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index 8009c7b..41a5083 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -12,8 +12,7 @@ ects: type: integer minimum: 0 description: | - Number of ECTS credits awarded to the learner upon completing the - Course. + Number of ECTS credits awarded to the learner upon completing the Course. academicTerm: type: array description: | @@ -121,3 +120,9 @@ assessmentMethod: **Note:** It is preferable to use `elmAssessmentType` instead. items: $ref: ./MultilineStringWithOptionalLang.yaml +lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 35be374..9fc3ca7 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -12,8 +12,7 @@ ects: type: integer minimum: 0 description: | - Number of ECTS credits awarded to the learner upon completing the - Course. + Number of ECTS credits awarded to the learner upon completing the Course. academicTerm: type: array description: | @@ -85,3 +84,9 @@ url: description: External URL with optional language code. items: $ref: ./HttpWithOptionalLang.yaml +lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index 7d45024..05bd364 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -12,6 +12,7 @@ attributes: required: - title - heiId + - lastModified properties: title: type: array @@ -30,6 +31,12 @@ attributes: description: External URL with optional language code. items: $ref: ./HttpWithOptionalLang.yaml + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 07a3aae..2bdf3a3 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -12,6 +12,7 @@ attributes: required: - title - ounitId + - lastModified properties: title: type: array @@ -32,6 +33,12 @@ attributes: description: External URL with optional language code. items: $ref: ./HttpWithOptionalLang.yaml + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index 3b9ac2e..aae299f 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -15,6 +15,7 @@ attributes: - code - ects - eqfLevelProvided + - lastModified properties: $ref: ./ProgrammeDataProperties.yaml links: diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index f0fc230..5ed2e99 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -64,12 +64,20 @@ url: items: $ref: ./HttpWithOptionalLang.yaml validSince: - type: date + type: string + format: date description: | The first date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: - type: date + type: string + format: date description: | The last date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 2a81cee..aeffa57 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1279,6 +1279,7 @@ components: required: - title - heiId + - lastModified properties: title: type: array @@ -1297,6 +1298,12 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1342,6 +1349,7 @@ components: required: - title - heiId + - lastModified properties: title: type: array @@ -1360,6 +1368,12 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1446,6 +1460,7 @@ components: required: - title - ounitId + - lastModified properties: title: type: array @@ -1466,6 +1481,12 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1511,6 +1532,7 @@ components: required: - title - ounitId + - lastModified properties: title: type: array @@ -1531,6 +1553,12 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1740,6 +1768,7 @@ components: - code - ects - eqfLevelProvided + - lastModified properties: title: type: array @@ -1807,15 +1836,23 @@ components: items: $ref: '#/components/schemas/HttpWithOptionalLang' validSince: - type: date + type: string + format: date description: | The first date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: - type: date + type: string + format: date description: | The last date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1866,6 +1903,7 @@ components: - code - ects - eqfLevelProvided + - lastModified properties: title: type: array @@ -1933,15 +1971,23 @@ components: items: $ref: '#/components/schemas/HttpWithOptionalLang' validSince: - type: date + type: string + format: date description: | The first date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: - type: date + type: string + format: date description: | The last date in which the Programme was offered, formatted as [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2169,6 +2215,7 @@ components: - title - code - ects + - lastModified properties: title: type: array @@ -2184,8 +2231,7 @@ components: type: integer minimum: 0 description: | - Number of ECTS credits awarded to the learner upon completing the - Course. + Number of ECTS credits awarded to the learner upon completing the Course. academicTerm: type: array description: | @@ -2257,6 +2303,12 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' links: @@ -2304,6 +2356,7 @@ components: - title - code - ects + - lastModified properties: title: type: array @@ -2319,8 +2372,7 @@ components: type: integer minimum: 0 description: | - Number of ECTS credits awarded to the learner upon completing the - Course. + Number of ECTS credits awarded to the learner upon completing the Course. academicTerm: type: array description: | @@ -2428,6 +2480,12 @@ components: **Note:** It is preferable to use `elmAssessmentType` instead. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Timestamp of the latest change to this resource, formatted as + [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' links: From 23aa2252f12d0df8f1dc24db143b1a950cbb4bc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Mon, 8 Sep 2025 10:32:03 +0200 Subject: [PATCH 07/23] Simplifies Course meta: no global rule, clearer field name, improved doc --- openapi/v2/components/schemas/CourseMeta.yaml | 36 +++++++------------ public/v2/openapi.yaml | 34 ++++++------------ 2 files changed, 22 insertions(+), 48 deletions(-) diff --git a/openapi/v2/components/schemas/CourseMeta.yaml b/openapi/v2/components/schemas/CourseMeta.yaml index 02b380c..2cd0e27 100644 --- a/openapi/v2/components/schemas/CourseMeta.yaml +++ b/openapi/v2/components/schemas/CourseMeta.yaml @@ -3,27 +3,6 @@ description: | JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - global: - type: object - description: Global rules that apply to all Programmes by default. - required: - - eqfLevel - - year - properties: - eqfLevel: - type: integer - minimum: 5 - maximum: 8 - description: | - [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) - of the Programmes to which the global rule applies. - year: - type: string - description: | - Year of the Programme in which the Course is delivered. - - e.g. `2/3` for the second of three years. - pattern: '[1-9]/[1-9]' programme: type: array description: Rules that apply to specific Programmes. @@ -37,7 +16,7 @@ properties: programmeId: type: string description: ID of the _Programme_ resource. - format: uuid + # format: uuid mandatoryCourse: type: boolean description: Whether the Course is mandatory within the Programme. @@ -46,5 +25,14 @@ properties: description: | Year of the Programme in which the Course is delivered. - e.g. `2/3` for the second of three years. - pattern: '[1-9]/[1-9]' + **Usage** + + - `2/3` means the Course is delivered in the second (2) of the three + (3) years of the Programme duration; + - `0/3` means the Course may be completed _at any point_ during the + three (3) years of the Programme duration; + - `4/4` may also refer to the fourth (4) year in a Programme with a + length of three and a half years (3.5) which must be rounded up in + the current context. + + pattern: '\d\/[1-9]' diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index aeffa57..810e04c 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2136,27 +2136,6 @@ components: JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - global: - type: object - description: Global rules that apply to all Programmes by default. - required: - - eqfLevel - - year - properties: - eqfLevel: - type: integer - minimum: 5 - maximum: 8 - description: | - [EQF Level](https://europa.eu/europass/en/description-eight-eqf-levels) - of the Programmes to which the global rule applies. - year: - type: string - description: | - Year of the Programme in which the Course is delivered. - - e.g. `2/3` for the second of three years. - pattern: '[1-9]/[1-9]' programme: type: array description: Rules that apply to specific Programmes. @@ -2170,7 +2149,6 @@ components: programmeId: type: string description: ID of the _Programme_ resource. - format: uuid mandatoryCourse: type: boolean description: Whether the Course is mandatory within the Programme. @@ -2179,8 +2157,16 @@ components: description: | Year of the Programme in which the Course is delivered. - e.g. `2/3` for the second of three years. - pattern: '[1-9]/[1-9]' + **Usage** + + - `2/3` means the Course is delivered in the second (2) of the three + (3) years of the Programme duration; + - `0/3` means the Course may be completed _at any point_ during the + three (3) years of the Programme duration; + - `4/4` may also refer to the fourth (4) year in a Programme with a + length of three and a half years (3.5) which must be rounded up in + the current context. + pattern: \d\/[1-9] CourseCollection: type: object description: JSON:API collection of _Course_ resources. From 727ac03ce7d2141ea843948868e6a4502f073d44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Mon, 8 Sep 2025 10:43:51 +0200 Subject: [PATCH 08/23] Tweaks to heiId, abbreviations in HEIs and OUnits --- openapi/v2/components/schemas/CourseMeta.yaml | 4 +- .../components/schemas/InstitutionData.yaml | 13 +++--- openapi/v2/components/schemas/OunitData.yaml | 9 ++-- public/v2/openapi.yaml | 42 ++++++++++++------- 4 files changed, 42 insertions(+), 26 deletions(-) diff --git a/openapi/v2/components/schemas/CourseMeta.yaml b/openapi/v2/components/schemas/CourseMeta.yaml index 2cd0e27..e37dfc1 100644 --- a/openapi/v2/components/schemas/CourseMeta.yaml +++ b/openapi/v2/components/schemas/CourseMeta.yaml @@ -3,9 +3,9 @@ description: | JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - programme: + relatedProgrammes: type: array - description: Rules that apply to specific Programmes. + description: Describes the inclusion of a Course in specific Programmes. items: type: object required: diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index 05bd364..01fd6d3 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -3,8 +3,7 @@ type: description: JSON:API resource type. id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, - but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; **must match** `heiId`. format: uuid attributes: type: object @@ -16,16 +15,20 @@ attributes: properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: ./StringWithOptionalLang.yaml - abbreviation: - type: string - description: Most widely recognized abbreviation. heiId: type: string description: The SCHAC code of the Institution. format: hostname + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language + code. + items: + $ref: ./StringWithOptionalLang.yaml url: type: array description: External URL with optional language code. diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 2bdf3a3..c811537 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -19,12 +19,15 @@ attributes: description: Title with optional language code. items: $ref: ./StringWithOptionalLang.yaml - abbreviation: - type: string - description: Most widely recognized abbreviation. ounitId: type: string description: Unique identifier within the Institution. Can be a UUID. + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language + code. + items: + $ref: ./StringWithOptionalLang.yaml ounitCode: type: string description: Human readable code identifying the Organisational Unit. diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 810e04c..689b825 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1271,7 +1271,7 @@ components: description: JSON:API resource type. id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; **must match** `heiId`. format: uuid attributes: type: object @@ -1283,16 +1283,19 @@ components: properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' - abbreviation: - type: string - description: Most widely recognized abbreviation. heiId: type: string description: The SCHAC code of the Institution. format: hostname + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' url: type: array description: External URL with optional language code. @@ -1341,7 +1344,7 @@ components: description: JSON:API resource type. id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; **must match** `heiId`. format: uuid attributes: type: object @@ -1353,16 +1356,19 @@ components: properties: title: type: array + minItems: 1 description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' - abbreviation: - type: string - description: Most widely recognized abbreviation. heiId: type: string description: The SCHAC code of the Institution. format: hostname + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' url: type: array description: External URL with optional language code. @@ -1467,12 +1473,14 @@ components: description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' - abbreviation: - type: string - description: Most widely recognized abbreviation. ounitId: type: string description: Unique identifier within the Institution. Can be a UUID. + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' ounitCode: type: string description: Human readable code identifying the Organisational Unit. @@ -1539,12 +1547,14 @@ components: description: Title with optional language code. items: $ref: '#/components/schemas/StringWithOptionalLang' - abbreviation: - type: string - description: Most widely recognized abbreviation. ounitId: type: string description: Unique identifier within the Institution. Can be a UUID. + abbreviation: + type: array + description: Most widely recognized abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' ounitCode: type: string description: Human readable code identifying the Organisational Unit. @@ -2136,9 +2146,9 @@ components: JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - programme: + relatedProgrammes: type: array - description: Rules that apply to specific Programmes. + description: Describes the inclusion of a Course in specific Programmes. items: type: object required: From 66dff4defd873cc90b0ee8e99b400afe501b12cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Mon, 8 Sep 2025 15:40:29 +0200 Subject: [PATCH 09/23] Sorts out Links objects as per #35; other minor fixes --- openapi/occapi_v2.yaml | 11 +- .../responses/CourseCollection.yaml | 4 +- .../components/responses/CourseResource.yaml | 4 +- .../responses/EndpointNotAvailable.yaml | 4 +- .../responses/InstitutionCollection.yaml | 4 +- .../responses/InstitutionResource.yaml | 4 +- .../components/responses/OunitCollection.yaml | 4 +- .../responses/OunitCourseCollection.yaml | 4 +- .../responses/OunitProgrammeCollection.yaml | 4 +- .../components/responses/OunitResource.yaml | 4 +- .../responses/ProgrammeCollection.yaml | 4 +- .../responses/ProgrammeCourseCollection.yaml | 4 +- .../responses/ProgrammeResource.yaml | 4 +- .../responses/ResourceNotFound.yaml | 4 +- openapi/v2/components/responses/Root.yaml | 4 +- .../components/schemas/CourseCollection.yaml | 4 +- .../schemas/CourseDataExtendedProperties.yaml | 2 +- .../schemas/CourseDataProperties.yaml | 2 +- .../v2/components/schemas/CourseResource.yaml | 4 +- .../schemas/InstitutionCollection.yaml | 4 +- .../components/schemas/InstitutionData.yaml | 9 +- .../schemas/InstitutionResource.yaml | 45 +- openapi/v2/components/schemas/Jsonapi.yaml | 2 +- .../schemas/LinksCourseCollection.yaml | 2 +- .../schemas/LinksInstitutionCollection.yaml | 9 + .../schemas/LinksOunitCollection.yaml | 10 + .../schemas/LinksProgrammeCollection.yaml | 9 + .../components/schemas/OunitCollection.yaml | 4 +- openapi/v2/components/schemas/OunitData.yaml | 7 +- .../v2/components/schemas/OunitResource.yaml | 27 +- .../schemas/ProgrammeCollection.yaml | 2 - .../schemas/ProgrammeDataProperties.yaml | 2 +- .../components/schemas/ProgrammeResource.yaml | 5 +- openapi/v2/components/schemas/Root.yaml | 15 +- openapi/v2/components/schemas/ServerData.yaml | 45 ++ openapi/v2/paths/hei.yaml | 2 +- openapi/v2/paths/hei@{heiId}.yaml | 2 +- openapi/v2/paths/root.yaml | 4 +- public/v2/openapi.yaml | 420 ++++++++++-------- 39 files changed, 363 insertions(+), 341 deletions(-) create mode 100644 openapi/v2/components/schemas/LinksInstitutionCollection.yaml create mode 100644 openapi/v2/components/schemas/LinksOunitCollection.yaml create mode 100644 openapi/v2/components/schemas/LinksProgrammeCollection.yaml create mode 100644 openapi/v2/components/schemas/ServerData.yaml diff --git a/openapi/occapi_v2.yaml b/openapi/occapi_v2.yaml index bce9bf8..65a4e18 100644 --- a/openapi/occapi_v2.yaml +++ b/openapi/occapi_v2.yaml @@ -17,10 +17,10 @@ info: # 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 @@ -63,8 +63,3 @@ paths: $ref: 'v2/paths/programme@{id}-course.yaml' '/hei/{heiId}/course/{id}': $ref: 'v2/paths/course@{id}.yaml' - # Exanples - # '/path': - # $ref: 'v2/paths/path-item.yaml' - # '/path/example': - # $ref: 'v2/paths/path-item-with-examples.yaml' diff --git a/openapi/v2/components/responses/CourseCollection.yaml b/openapi/v2/components/responses/CourseCollection.yaml index 1439341..2032e9a 100644 --- a/openapi/v2/components/responses/CourseCollection.yaml +++ b/openapi/v2/components/responses/CourseCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 diff --git a/openapi/v2/components/responses/CourseResource.yaml b/openapi/v2/components/responses/CourseResource.yaml index b716106..90a50a2 100644 --- a/openapi/v2/components/responses/CourseResource.yaml +++ b/openapi/v2/components/responses/CourseResource.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: type: course id: aabbccdd-eeff-1122-3344-556677889900 diff --git a/openapi/v2/components/responses/EndpointNotAvailable.yaml b/openapi/v2/components/responses/EndpointNotAvailable.yaml index 21f586b..d37cdb4 100644 --- a/openapi/v2/components/responses/EndpointNotAvailable.yaml +++ b/openapi/v2/components/responses/EndpointNotAvailable.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" errors: - status: "404" title: Endpoint not available. diff --git a/openapi/v2/components/responses/InstitutionCollection.yaml b/openapi/v2/components/responses/InstitutionCollection.yaml index a6adc50..7d62411 100644 --- a/openapi/v2/components/responses/InstitutionCollection.yaml +++ b/openapi/v2/components/responses/InstitutionCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: hei id: 12345678-90ab-cdef-1234-567890abcdef diff --git a/openapi/v2/components/responses/InstitutionResource.yaml b/openapi/v2/components/responses/InstitutionResource.yaml index bf1bd09..7f7cebe 100644 --- a/openapi/v2/components/responses/InstitutionResource.yaml +++ b/openapi/v2/components/responses/InstitutionResource.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: type: hei id: 12345678-90ab-cdef-1234-567890abcdef diff --git a/openapi/v2/components/responses/OunitCollection.yaml b/openapi/v2/components/responses/OunitCollection.yaml index 3bb2f49..da027f9 100644 --- a/openapi/v2/components/responses/OunitCollection.yaml +++ b/openapi/v2/components/responses/OunitCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: ounit id: 11223344-5566-7788-9900-aabbccddeeff diff --git a/openapi/v2/components/responses/OunitCourseCollection.yaml b/openapi/v2/components/responses/OunitCourseCollection.yaml index 6bada9c..7ce4ef3 100644 --- a/openapi/v2/components/responses/OunitCourseCollection.yaml +++ b/openapi/v2/components/responses/OunitCourseCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 diff --git a/openapi/v2/components/responses/OunitProgrammeCollection.yaml b/openapi/v2/components/responses/OunitProgrammeCollection.yaml index 20c23b6..c3126bd 100644 --- a/openapi/v2/components/responses/OunitProgrammeCollection.yaml +++ b/openapi/v2/components/responses/OunitProgrammeCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: programme id: abcdef12-3456-7890-abcd-ef1234567890 diff --git a/openapi/v2/components/responses/OunitResource.yaml b/openapi/v2/components/responses/OunitResource.yaml index 6b5f9b4..e012ede 100644 --- a/openapi/v2/components/responses/OunitResource.yaml +++ b/openapi/v2/components/responses/OunitResource.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: type: ounit id: 11223344-5566-7788-9900-aabbccddeeff diff --git a/openapi/v2/components/responses/ProgrammeCollection.yaml b/openapi/v2/components/responses/ProgrammeCollection.yaml index c954102..1ace5ac 100644 --- a/openapi/v2/components/responses/ProgrammeCollection.yaml +++ b/openapi/v2/components/responses/ProgrammeCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: programme id: abcdef12-3456-7890-abcd-ef1234567890 diff --git a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml index 7ff8974..08e570d 100644 --- a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml +++ b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 diff --git a/openapi/v2/components/responses/ProgrammeResource.yaml b/openapi/v2/components/responses/ProgrammeResource.yaml index 195b46e..86da34d 100644 --- a/openapi/v2/components/responses/ProgrammeResource.yaml +++ b/openapi/v2/components/responses/ProgrammeResource.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" data: type: programme id: abcdef12-3456-7890-abcd-ef1234567890 diff --git a/openapi/v2/components/responses/ResourceNotFound.yaml b/openapi/v2/components/responses/ResourceNotFound.yaml index d8ba231..017fb38 100644 --- a/openapi/v2/components/responses/ResourceNotFound.yaml +++ b/openapi/v2/components/responses/ResourceNotFound.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" errors: - status: "404" title: Resource not found. diff --git a/openapi/v2/components/responses/Root.yaml b/openapi/v2/components/responses/Root.yaml index 507139a..85acfe6 100644 --- a/openapi/v2/components/responses/Root.yaml +++ b/openapi/v2/components/responses/Root.yaml @@ -1,9 +1,9 @@ jsonapi: - version: "1.0" + version: "1.1" meta: links: self: - href: "http://jsonapi.org/format/1.0/" + href: "http://jsonapi.org/format/1.1/" meta: {} links: self: diff --git a/openapi/v2/components/schemas/CourseCollection.yaml b/openapi/v2/components/schemas/CourseCollection.yaml index 7950226..6a6b4e0 100644 --- a/openapi/v2/components/schemas/CourseCollection.yaml +++ b/openapi/v2/components/schemas/CourseCollection.yaml @@ -13,15 +13,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./CourseData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index 41a5083..c2d5621 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -124,5 +124,5 @@ lastModified: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 9fc3ca7..8b578b2 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -88,5 +88,5 @@ lastModified: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/CourseResource.yaml b/openapi/v2/components/schemas/CourseResource.yaml index b6b09aa..3de37fc 100644 --- a/openapi/v2/components/schemas/CourseResource.yaml +++ b/openapi/v2/components/schemas/CourseResource.yaml @@ -11,15 +11,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./CourseDataExtended.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/InstitutionCollection.yaml b/openapi/v2/components/schemas/InstitutionCollection.yaml index 277bd49..46d78b1 100644 --- a/openapi/v2/components/schemas/InstitutionCollection.yaml +++ b/openapi/v2/components/schemas/InstitutionCollection.yaml @@ -13,15 +13,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./InstitutionData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index 01fd6d3..c285a61 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -1,6 +1,7 @@ type: type: string description: JSON:API resource type. + enum: ['hei'] id: type: string description: JSON:API resource ID; **must match** `heiId`. @@ -38,7 +39,7 @@ attributes: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -48,3 +49,9 @@ links: properties: self: $ref: ./LinksResource.yaml + ounit: + $ref: ./LinksOunitCollection.yaml + programme: + $ref: ./LinksProgrammeCollection.yaml + course: + $ref: ./LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/InstitutionResource.yaml b/openapi/v2/components/schemas/InstitutionResource.yaml index aac8299..fbc6b8b 100644 --- a/openapi/v2/components/schemas/InstitutionResource.yaml +++ b/openapi/v2/components/schemas/InstitutionResource.yaml @@ -2,7 +2,6 @@ type: object description: JSON:API _Institution_ resource. required: - data - - links properties: jsonapi: $ref: ./Jsonapi.yaml @@ -12,55 +11,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./InstitutionData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksResource.yaml - ounit: - type: object - description: | - Hypermedia link to the _Organisational Units_ collection associated to this resource. - - **Recommended:** separate any collections by _Organisational Unit_ in order to avoid large HTTP responses. - - The resource collection links for _Programmes_ and _Courses_ shown below can also be implemented at the _Organisational Unit_ level. - required: - - href - properties: - href: - type: string - format: uri - programme: - type: object - description: | - Hypermedia link to the _Programmes_ collection associated to this resource. - - **Recommended:** separate this collection by _Organisational Unit_ in order to avoid large HTTP responses. - - The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. - required: - - href - properties: - href: - type: string - format: uri - course: - type: object - description: | - _**Discouraged!**_ Hypermedia link to the _Courses_ collection associated to this resource. - - **Recommended:** separate this collection by _Programme_ or by _Organisational Unit_ in order to avoid large HTTP responses. - required: - - href - properties: - href: - type: string - format: uri diff --git a/openapi/v2/components/schemas/Jsonapi.yaml b/openapi/v2/components/schemas/Jsonapi.yaml index 7747162..b7e36b9 100644 --- a/openapi/v2/components/schemas/Jsonapi.yaml +++ b/openapi/v2/components/schemas/Jsonapi.yaml @@ -31,4 +31,4 @@ properties: description: | JSON:API version supported by the server. - http://jsonapi.org/format/1.0/ + http://jsonapi.org/format/1.1/ diff --git a/openapi/v2/components/schemas/LinksCourseCollection.yaml b/openapi/v2/components/schemas/LinksCourseCollection.yaml index b4933b8..d0f89b4 100644 --- a/openapi/v2/components/schemas/LinksCourseCollection.yaml +++ b/openapi/v2/components/schemas/LinksCourseCollection.yaml @@ -1,6 +1,6 @@ type: object description: | - Hypermedia link to the _Courses_ collection associated with this resource. + Hypermedia link to the _Course_ collection associated with this resource. required: - href properties: diff --git a/openapi/v2/components/schemas/LinksInstitutionCollection.yaml b/openapi/v2/components/schemas/LinksInstitutionCollection.yaml new file mode 100644 index 0000000..b76405f --- /dev/null +++ b/openapi/v2/components/schemas/LinksInstitutionCollection.yaml @@ -0,0 +1,9 @@ +type: object +description: | + Hypermedia link to the _Institution_ collection covered with this server. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/LinksOunitCollection.yaml b/openapi/v2/components/schemas/LinksOunitCollection.yaml new file mode 100644 index 0000000..37a9bbf --- /dev/null +++ b/openapi/v2/components/schemas/LinksOunitCollection.yaml @@ -0,0 +1,10 @@ +type: object +description: | + Hypermedia link to the _Organizational Unit_ collection associated with this + resource. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/LinksProgrammeCollection.yaml b/openapi/v2/components/schemas/LinksProgrammeCollection.yaml new file mode 100644 index 0000000..9f87846 --- /dev/null +++ b/openapi/v2/components/schemas/LinksProgrammeCollection.yaml @@ -0,0 +1,9 @@ +type: object +description: | + Hypermedia link to the _Programme_ collection associated with this resource. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/components/schemas/OunitCollection.yaml b/openapi/v2/components/schemas/OunitCollection.yaml index 3ce3eba..2713039 100644 --- a/openapi/v2/components/schemas/OunitCollection.yaml +++ b/openapi/v2/components/schemas/OunitCollection.yaml @@ -13,15 +13,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./OunitData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index c811537..2779ffc 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -1,6 +1,7 @@ type: type: string description: JSON:API resource type. + enum: ['ounit'] id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, @@ -40,7 +41,7 @@ attributes: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -50,3 +51,7 @@ links: properties: self: $ref: ./LinksResource.yaml + programme: + $ref: ./LinksProgrammeCollection.yaml + course: + $ref: ./LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/OunitResource.yaml b/openapi/v2/components/schemas/OunitResource.yaml index 23bb507..145e693 100644 --- a/openapi/v2/components/schemas/OunitResource.yaml +++ b/openapi/v2/components/schemas/OunitResource.yaml @@ -2,7 +2,6 @@ type: object description: JSON:API _Organisational Unit_ resource. required: - data - - links properties: jsonapi: $ref: ./Jsonapi.yaml @@ -12,37 +11,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./OunitData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksResource.yaml - programme: - type: object - description: | - Hypermedia link to the _Programmes_ collection associated to this resource. - - The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. - required: - - href - properties: - href: - type: string - format: uri - course: - type: object - description: | - Hypermedia link to the _Courses_ collection associated to this resource. - required: - - href - properties: - href: - type: string - format: uri diff --git a/openapi/v2/components/schemas/ProgrammeCollection.yaml b/openapi/v2/components/schemas/ProgrammeCollection.yaml index 8dafb7f..9839fc3 100644 --- a/openapi/v2/components/schemas/ProgrammeCollection.yaml +++ b/openapi/v2/components/schemas/ProgrammeCollection.yaml @@ -20,8 +20,6 @@ properties: links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksCollection.yaml diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index 5ed2e99..0a1ef44 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -79,5 +79,5 @@ lastModified: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/ProgrammeResource.yaml b/openapi/v2/components/schemas/ProgrammeResource.yaml index aca0622..fda27a6 100644 --- a/openapi/v2/components/schemas/ProgrammeResource.yaml +++ b/openapi/v2/components/schemas/ProgrammeResource.yaml @@ -2,7 +2,6 @@ type: object description: JSON:API _Programme_ resource. required: - data - - links properties: jsonapi: $ref: ./Jsonapi.yaml @@ -12,15 +11,13 @@ properties: required: - type - id - - links - attributes + - links properties: $ref: ./ProgrammeData.yaml links: type: object description: JSON:API _links_ object. - # required: - # - self properties: self: $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/Root.yaml b/openapi/v2/components/schemas/Root.yaml index 40ddf71..73386c0 100644 --- a/openapi/v2/components/schemas/Root.yaml +++ b/openapi/v2/components/schemas/Root.yaml @@ -1,27 +1,18 @@ type: object description: Available endpoints and metadata. required: - - links + - data properties: jsonapi: $ref: ./Jsonapi.yaml + data: + $ref: ./ServerData.yaml meta: type: object description: Optional metadata. links: type: object description: JSON:API _links_ object. - required: - - hei properties: self: $ref: ./LinksSelf.yaml - hei: - type: object - description: Hypermedia link to the [Institution collection](#tag/Institution). - required: - - href - properties: - href: - type: string - format: uri diff --git a/openapi/v2/components/schemas/ServerData.yaml b/openapi/v2/components/schemas/ServerData.yaml new file mode 100644 index 0000000..2e01949 --- /dev/null +++ b/openapi/v2/components/schemas/ServerData.yaml @@ -0,0 +1,45 @@ +type: object +description: Information about the API server. +required: + - type + - id + - attributes + - links +properties: + type: + type: string + description: JSON:API resource type. + enum: ['server'] + id: + type: string + description: UUID v4 + format: uuid + attributes: + type: object + description: JSON:API _attributes_ object. + required: + - serverName + properties: + serverName: + type: array + minItems: 1 + description: Server name with optional language code. + items: + $ref: ./StringWithOptionalLang.yaml + termsOfService: + type: array + minItems: 1 + description: URL for Terms of service with optional language code. + items: + $ref: ./HttpWithOptionalLang.yaml + links: + type: object + description: JSON:API _links_ object. + required: + - self + - hei + properties: + self: + $ref: ./LinksResource.yaml + hei: + $ref: ./LinksInstitutionCollection.yaml diff --git a/openapi/v2/paths/hei.yaml b/openapi/v2/paths/hei.yaml index eed05dd..d799db1 100644 --- a/openapi/v2/paths/hei.yaml +++ b/openapi/v2/paths/hei.yaml @@ -3,7 +3,7 @@ get: - Institution summary: GET /hei description: | - This endpoint lists all _Institutions_ covered by this provider. + This endpoint lists all _Institutions_ covered by this server. In order to obtain more detailed and up to date information about an Institution, it is **recommended** that client implementations use the diff --git a/openapi/v2/paths/hei@{heiId}.yaml b/openapi/v2/paths/hei@{heiId}.yaml index d2cc2cb..97dff35 100644 --- a/openapi/v2/paths/hei@{heiId}.yaml +++ b/openapi/v2/paths/hei@{heiId}.yaml @@ -4,7 +4,7 @@ get: summary: GET /hei/{heiId} description: | This endpoint exposes some basic information about an Institution covered by - the provider, which should be sufficient to satisfy basic UX/UI needs of + the server, which should be sufficient to satisfy basic UX/UI needs of app developers. In order to obtain more detailed and up to date information about an diff --git a/openapi/v2/paths/root.yaml b/openapi/v2/paths/root.yaml index aed0cd3..a8507cf 100644 --- a/openapi/v2/paths/root.yaml +++ b/openapi/v2/paths/root.yaml @@ -1,8 +1,8 @@ get: tags: - - API provider + - API server summary: GET / - description: Get primary Hypermedia links and optional metadata about the provider. + description: Get server information and primary Hypermedia links. operationId: getRoot responses: '200': diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 689b825..2070453 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -16,10 +16,10 @@ servers: - url: /occapi/v2 description: Sandbox server (example data) 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 @@ -34,9 +34,9 @@ paths: /: get: tags: - - API provider + - API server summary: GET / - description: Get primary Hypermedia links and optional metadata about the provider. + description: Get server information and primary Hypermedia links. operationId: getRoot responses: '200': @@ -53,11 +53,11 @@ paths: $ref: '#/components/schemas/Root' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ meta: {} links: self: @@ -72,11 +72,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -86,7 +86,7 @@ paths: - Institution summary: GET /hei description: | - This endpoint lists all _Institutions_ covered by this provider. + This endpoint lists all _Institutions_ covered by this server. In order to obtain more detailed and up to date information about an Institution, it is **recommended** that client implementations use the @@ -108,11 +108,11 @@ paths: $ref: '#/components/schemas/InstitutionCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: hei id: 12345678-90ab-cdef-1234-567890abcdef @@ -139,11 +139,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -154,7 +154,7 @@ paths: summary: GET /hei/{heiId} description: | This endpoint exposes some basic information about an Institution covered by - the provider, which should be sufficient to satisfy basic UX/UI needs of + the server, which should be sufficient to satisfy basic UX/UI needs of app developers. In order to obtain more detailed and up to date information about an @@ -184,11 +184,11 @@ paths: $ref: '#/components/schemas/InstitutionResource' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: type: hei id: 12345678-90ab-cdef-1234-567890abcdef @@ -221,11 +221,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Resource not found. @@ -262,11 +262,11 @@ paths: $ref: '#/components/schemas/OunitCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: ounit id: 11223344-5566-7788-9900-aabbccddeeff @@ -294,11 +294,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -343,11 +343,11 @@ paths: $ref: '#/components/schemas/OunitResource' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: type: ounit id: 11223344-5566-7788-9900-aabbccddeeff @@ -379,11 +379,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Resource not found. @@ -417,11 +417,11 @@ paths: $ref: '#/components/schemas/ProgrammeCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: programme id: abcdef12-3456-7890-abcd-ef1234567890 @@ -458,11 +458,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -503,11 +503,11 @@ paths: $ref: '#/components/schemas/ProgrammeCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: programme id: abcdef12-3456-7890-abcd-ef1234567890 @@ -544,11 +544,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -590,11 +590,11 @@ paths: $ref: '#/components/schemas/ProgrammeResource' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: type: programme id: abcdef12-3456-7890-abcd-ef1234567890 @@ -633,11 +633,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Resource not found. @@ -671,11 +671,11 @@ paths: $ref: '#/components/schemas/CourseCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 @@ -728,11 +728,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -773,11 +773,11 @@ paths: $ref: '#/components/schemas/CourseCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 @@ -829,11 +829,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -874,11 +874,11 @@ paths: $ref: '#/components/schemas/CourseCollection' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: - type: course id: aabbccdd-eeff-1122-3344-556677889900 @@ -930,11 +930,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Endpoint not available. @@ -978,11 +978,11 @@ paths: $ref: '#/components/schemas/CourseResource' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ data: type: course id: aabbccdd-eeff-1122-3344-556677889900 @@ -1071,11 +1071,11 @@ paths: $ref: '#/components/schemas/Error' example: jsonapi: - version: '1.0' + version: '1.1' meta: links: self: - href: http://jsonapi.org/format/1.0/ + href: http://jsonapi.org/format/1.1/ errors: - status: '404' title: Resource not found. @@ -1115,7 +1115,116 @@ components: description: | JSON:API version supported by the server. - http://jsonapi.org/format/1.0/ + http://jsonapi.org/format/1.1/ + Lang: + type: + - string + - null + minLength: 2 + description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + StringWithOptionalLang: + type: object + required: + - string + properties: + string: + type: string + minLength: 1 + description: Text value. + lang: + $ref: '#/components/schemas/Lang' + HttpWithOptionalLang: + type: object + required: + - uri + properties: + uri: + type: string + format: uri + description: URL + lang: + $ref: '#/components/schemas/Lang' + LinksResource: + type: object + description: Hypermedia link to the **canonical path** of this resource. + required: + - href + properties: + href: + type: string + format: uri + LinksInstitutionCollection: + type: object + description: | + Hypermedia link to the _Institution_ collection covered with this server. + required: + - href + properties: + href: + type: string + format: uri + ServerData: + type: object + description: Information about the API server. + required: + - type + - id + - attributes + - links + properties: + type: + type: string + description: JSON:API resource type. + enum: + - server + id: + type: string + description: UUID v4 + format: uuid + attributes: + type: object + description: JSON:API _attributes_ object. + required: + - serverName + properties: + serverName: + type: array + minItems: 1 + description: Server name with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' + termsOfService: + type: array + minItems: 1 + description: URL for Terms of service with optional language code. + items: + $ref: '#/components/schemas/HttpWithOptionalLang' + links: + type: object + description: JSON:API _links_ object. + required: + - self + - hei + properties: + self: + $ref: '#/components/schemas/LinksResource' + hei: + $ref: '#/components/schemas/LinksInstitutionCollection' LinksSelf: type: object description: Hypermedia link to the current path. @@ -1129,30 +1238,21 @@ components: type: object description: Available endpoints and metadata. required: - - links + - data properties: jsonapi: $ref: '#/components/schemas/Jsonapi' + data: + $ref: '#/components/schemas/ServerData' meta: type: object description: Optional metadata. links: type: object description: JSON:API _links_ object. - required: - - hei properties: self: $ref: '#/components/schemas/LinksSelf' - hei: - type: object - description: Hypermedia link to the [Institution collection](#tag/Institution). - required: - - href - properties: - href: - type: string - format: uri Error: type: object description: JSON:API `errors` object. @@ -1186,52 +1286,31 @@ components: parameter: type: string description: Which URI query parameter caused the error. - Lang: - type: - - string - - null - minLength: 2 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - StringWithOptionalLang: + LinksOunitCollection: type: object + description: | + Hypermedia link to the _Organizational Unit_ collection associated with this + resource. required: - - string + - href properties: - string: + href: type: string - minLength: 1 - description: Text value. - lang: - $ref: '#/components/schemas/Lang' - HttpWithOptionalLang: + format: uri + LinksProgrammeCollection: type: object + description: | + Hypermedia link to the _Programme_ collection associated with this resource. required: - - uri + - href properties: - uri: + href: type: string format: uri - description: URL - lang: - $ref: '#/components/schemas/Lang' - LinksResource: + LinksCourseCollection: type: object - description: Hypermedia link to the **canonical path** of this resource. + description: | + Hypermedia link to the _Course_ collection associated with this resource. required: - href properties: @@ -1263,12 +1342,14 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string description: JSON:API resource type. + enum: + - hei id: type: string description: JSON:API resource ID; **must match** `heiId`. @@ -1305,7 +1386,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -1315,6 +1396,12 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + ounit: + $ref: '#/components/schemas/LinksOunitCollection' + programme: + $ref: '#/components/schemas/LinksProgrammeCollection' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. @@ -1326,7 +1413,6 @@ components: description: JSON:API _Institution_ resource. required: - data - - links properties: jsonapi: $ref: '#/components/schemas/Jsonapi' @@ -1336,12 +1422,14 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string description: JSON:API resource type. + enum: + - hei id: type: string description: JSON:API resource ID; **must match** `heiId`. @@ -1378,7 +1466,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -1388,52 +1476,18 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + ounit: + $ref: '#/components/schemas/LinksOunitCollection' + programme: + $ref: '#/components/schemas/LinksProgrammeCollection' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. properties: self: $ref: '#/components/schemas/LinksResource' - ounit: - type: object - description: | - Hypermedia link to the _Organisational Units_ collection associated to this resource. - - **Recommended:** separate any collections by _Organisational Unit_ in order to avoid large HTTP responses. - - The resource collection links for _Programmes_ and _Courses_ shown below can also be implemented at the _Organisational Unit_ level. - required: - - href - properties: - href: - type: string - format: uri - programme: - type: object - description: | - Hypermedia link to the _Programmes_ collection associated to this resource. - - **Recommended:** separate this collection by _Organisational Unit_ in order to avoid large HTTP responses. - - The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. - required: - - href - properties: - href: - type: string - format: uri - course: - type: object - description: | - _**Discouraged!**_ Hypermedia link to the _Courses_ collection associated to this resource. - - **Recommended:** separate this collection by _Programme_ or by _Organisational Unit_ in order to avoid large HTTP responses. - required: - - href - properties: - href: - type: string - format: uri OunitCollection: type: object description: JSON:API collection of _Organisational Unit_ resources. @@ -1450,12 +1504,14 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string description: JSON:API resource type. + enum: + - ounit id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. @@ -1493,7 +1549,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -1503,6 +1559,10 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + programme: + $ref: '#/components/schemas/LinksProgrammeCollection' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. @@ -1514,7 +1574,6 @@ components: description: JSON:API _Organisational Unit_ resource. required: - data - - links properties: jsonapi: $ref: '#/components/schemas/Jsonapi' @@ -1524,12 +1583,14 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string description: JSON:API resource type. + enum: + - ounit id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. @@ -1567,7 +1628,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -1577,34 +1638,16 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + programme: + $ref: '#/components/schemas/LinksProgrammeCollection' + course: + $ref: '#/components/schemas/LinksCourseCollection' links: type: object description: JSON:API _links_ object. properties: self: $ref: '#/components/schemas/LinksResource' - programme: - type: object - description: | - Hypermedia link to the _Programmes_ collection associated to this resource. - - The resource collection link for _Courses_ shown below can also be implemented at the _Programme_ level. - required: - - href - properties: - href: - type: string - format: uri - course: - type: object - description: | - Hypermedia link to the _Courses_ collection associated to this resource. - required: - - href - properties: - href: - type: string - format: uri EqfLevelProvided: type: integer minimum: 5 @@ -1733,16 +1776,6 @@ components: - `9/3` indicates nine (9) trimesters (1/3) equivalent to three full academic years; - `3/1` indicates three (3) full years (1/1) absent a division in terms. - LinksCourseCollection: - type: object - description: | - Hypermedia link to the _Courses_ collection associated with this resource. - required: - - href - properties: - href: - type: string - format: uri ProgrammeCollection: type: object description: JSON:API collection of _Programme_ resources. @@ -1861,7 +1894,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -1884,7 +1917,6 @@ components: description: JSON:API _Programme_ resource. required: - data - - links properties: jsonapi: $ref: '#/components/schemas/Jsonapi' @@ -1894,8 +1926,8 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string @@ -1996,7 +2028,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object @@ -2193,8 +2225,8 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string @@ -2303,7 +2335,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' @@ -2335,8 +2367,8 @@ components: required: - type - id - - links - attributes + - links properties: type: type: string @@ -2480,7 +2512,7 @@ components: type: string format: date-time description: | - Timestamp of the latest change to this resource, formatted as + Time of latest change to this resource, formatted as [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' From d82ed9292f6073f19719af4f1859a74371fcf762 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 11:53:25 +0200 Subject: [PATCH 10/23] Prerequisite Course relationship --- openapi/v2/components/schemas/CourseData.yaml | 6 +- .../schemas/CourseDataExtended.yaml | 7 ++- .../schemas/CourseRelationships.yaml | 43 ++++++++++++++ openapi/v2/components/schemas/OunitData.yaml | 5 +- .../v2/components/schemas/ProgrammeData.yaml | 4 +- public/v2/openapi.yaml | 59 +++++++++++++++++-- 6 files changed, 110 insertions(+), 14 deletions(-) create mode 100644 openapi/v2/components/schemas/CourseRelationships.yaml diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index aa7e86d..4832027 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -4,8 +4,8 @@ type: enum: ['course'] id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, - but any value that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value + that is unique within the Institution may be used. # format: uuid attributes: type: object @@ -19,6 +19,8 @@ attributes: $ref: ./CourseDataProperties.yaml meta: $ref: ./CourseMeta.yaml +relationships: + $ref: ./CourseRelationships.yaml links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index 5bb28ca..b651f85 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -3,8 +3,9 @@ type: description: JSON:API resource type. id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, - but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value + that is unique within the Institution may be used. + # format: uuid format: uuid attributes: type: object @@ -18,6 +19,8 @@ attributes: $ref: ./CourseDataExtendedProperties.yaml meta: $ref: ./CourseMeta.yaml +relationships: + $ref: ./CourseRelationships.yaml links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/CourseRelationships.yaml b/openapi/v2/components/schemas/CourseRelationships.yaml new file mode 100644 index 0000000..8cc8f48 --- /dev/null +++ b/openapi/v2/components/schemas/CourseRelationships.yaml @@ -0,0 +1,43 @@ +type: object +description: | + JSON:API _relationships_ object. +properties: + prerequisiteCourse: + type: array + description: | + List of other Courses that **must** be completed before enrollment in the + present Course is allowed. + + If the prerequisites for the present Course cannot be matched to concrete + Courses, use the `prerequisites` data attribute for a more detailed + description. + items: + type: object + required: + - data + - links + properties: + data: + type: object + description: Related _Course_ data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: ['course'] + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but + any value that is unique within the Institution may be used. + # format: uuid + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 2779ffc..2d711d9 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -4,8 +4,9 @@ type: enum: ['ounit'] id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, - but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value + that is unique within the Institution may be used. + # format: uuid format: uuid attributes: type: object diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index aae299f..cf64110 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -4,8 +4,8 @@ type: enum: ['programme'] id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, - but any value that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value + that is unique within the Institution may be used. # format: uuid attributes: type: object diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 2070453..8dd0a76 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1514,7 +1514,7 @@ components: - ounit id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. format: uuid attributes: type: object @@ -1593,7 +1593,7 @@ components: - ounit id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. format: uuid attributes: type: object @@ -1802,7 +1802,7 @@ components: - programme id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. @@ -1936,7 +1936,7 @@ components: - programme id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. @@ -2209,6 +2209,49 @@ components: length of three and a half years (3.5) which must be rounded up in the current context. pattern: \d\/[1-9] + CourseRelationships: + type: object + description: | + JSON:API _relationships_ object. + properties: + prerequisiteCourse: + type: array + description: | + List of other Courses that **must** be completed before enrollment in the + present Course is allowed. + + If the prerequisites for the present Course cannot be matched to concrete + Courses, use the `prerequisites` data attribute for a more detailed + description. + items: + type: object + required: + - data + - links + properties: + data: + type: object + description: Related _Course_ data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: + - course + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: '#/components/schemas/LinksResource' CourseCollection: type: object description: JSON:API collection of _Course_ resources. @@ -2235,7 +2278,7 @@ components: - course id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. attributes: type: object description: JSON:API _attributes_ object. @@ -2339,6 +2382,8 @@ components: [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' + relationships: + $ref: '#/components/schemas/CourseRelationships' links: type: object description: JSON:API _links_ object. @@ -2375,7 +2420,7 @@ components: description: JSON:API resource type. id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any string that is unique within the realm of the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. format: uuid attributes: type: object @@ -2516,6 +2561,8 @@ components: [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). meta: $ref: '#/components/schemas/CourseMeta' + relationships: + $ref: '#/components/schemas/CourseRelationships' links: type: object description: JSON:API _links_ object. From 0a87e2f01724f459636d77bce6b783d16b11f1dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 12:39:35 +0200 Subject: [PATCH 11/23] Includes related programmes in the relationships --- openapi/v2/components/schemas/CourseMeta.yaml | 7 ++- .../schemas/CourseRelationships.yaml | 48 ++++++++++++++--- public/v2/openapi.yaml | 53 ++++++++++++++++--- 3 files changed, 92 insertions(+), 16 deletions(-) diff --git a/openapi/v2/components/schemas/CourseMeta.yaml b/openapi/v2/components/schemas/CourseMeta.yaml index e37dfc1..09ff39b 100644 --- a/openapi/v2/components/schemas/CourseMeta.yaml +++ b/openapi/v2/components/schemas/CourseMeta.yaml @@ -3,9 +3,12 @@ description: | JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - relatedProgrammes: + relatedProgramme: type: array - description: Describes the inclusion of a Course in specific Programmes. + description: Describes the inclusion of a Course in a specific Programme. + + Any Programme indicated here **must** also be indicated in the + `relationships` object. items: type: object required: diff --git a/openapi/v2/components/schemas/CourseRelationships.yaml b/openapi/v2/components/schemas/CourseRelationships.yaml index 8cc8f48..38f124a 100644 --- a/openapi/v2/components/schemas/CourseRelationships.yaml +++ b/openapi/v2/components/schemas/CourseRelationships.yaml @@ -5,12 +5,12 @@ properties: prerequisiteCourse: type: array description: | - List of other Courses that **must** be completed before enrollment in the - present Course is allowed. + Another Course that **must** be completed before enrollment in the present + Course is allowed. - If the prerequisites for the present Course cannot be matched to concrete - Courses, use the `prerequisites` data attribute for a more detailed - description. + If the prerequisites for the present Course cannot be matched to a single + Course (or multiple Courses), use the `prerequisites` data attribute for + a more detailed description. items: type: object required: @@ -19,7 +19,7 @@ properties: properties: data: type: object - description: Related _Course_ data. + description: Prerequisite Course data. required: - type - id @@ -41,3 +41,39 @@ properties: properties: self: $ref: ./LinksResource.yaml + relatedProgramme: + type: array + description: | + Any Programme which includes the present Course in its curricular plan. + + This **must** match all related Programmes indicated in the `meta` object. + items: + type: object + required: + - data + - links + properties: + data: + type: object + description: Related Programme data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: ['programme'] + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but + any value that is unique within the Institution may be used. + # format: uuid + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./LinksResource.yaml diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 8dd0a76..d2b218a 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2178,9 +2178,11 @@ components: JSON:API _meta_ object containing information about the relation between a Course and all or specific Programmes. properties: - relatedProgrammes: + relatedProgramme: type: array - description: Describes the inclusion of a Course in specific Programmes. + description: |- + Describes the inclusion of a Course in a specific Programme. + Any Programme indicated here **must** also be indicated in the `relationships` object. items: type: object required: @@ -2217,12 +2219,12 @@ components: prerequisiteCourse: type: array description: | - List of other Courses that **must** be completed before enrollment in the - present Course is allowed. + Another Course that **must** be completed before enrollment in the present + Course is allowed. - If the prerequisites for the present Course cannot be matched to concrete - Courses, use the `prerequisites` data attribute for a more detailed - description. + If the prerequisites for the present Course cannot be matched to a single + Course (or multiple Courses), use the `prerequisites` data attribute for + a more detailed description. items: type: object required: @@ -2231,7 +2233,7 @@ components: properties: data: type: object - description: Related _Course_ data. + description: Prerequisite Course data. required: - type - id @@ -2252,6 +2254,41 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + relatedProgramme: + type: array + description: | + Any Programme which includes the present Course in its curricular plan. + + This **must** match all related Programmes indicated in the `meta` object. + items: + type: object + required: + - data + - links + properties: + data: + type: object + description: Related Programme data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: + - programme + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: '#/components/schemas/LinksResource' CourseCollection: type: object description: JSON:API collection of _Course_ resources. From 96a69a58967ed42d43a7e49b6564b644a3f5901b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 12:55:02 +0200 Subject: [PATCH 12/23] Adds deprecated flag to Courses as per #36 --- .../schemas/CourseDataExtendedProperties.yaml | 17 +++++++++++++- .../schemas/CourseDataProperties.yaml | 5 ++++- public/v2/openapi.yaml | 22 +++++++++++++++++-- 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index c2d5621..59e91fe 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -125,4 +125,19 @@ lastModified: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +deprecated: + type: boolean + description: | + Return `true` if a Course will no longer be delivered, or there is no + expectation that it will be delivered in the foreseeable future. + + **Deprecate, do not delete!** + + Institutions **must** keep a permanent record of all Courses ever delivered + so that they may be dereferenced from _Course instances_. + + Servers **must** omit deprecated Courses from Course collections (unless + `deprecated` is used as a filter). + + Servers **must** provide deprecated Course data via its **canonical path**. diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 8b578b2..1559498 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -89,4 +89,7 @@ lastModified: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +deprecated: + type: boolean + description: | diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index d2b218a..a84d170 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2416,7 +2416,10 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + deprecated: + type: boolean + description: '' meta: $ref: '#/components/schemas/CourseMeta' relationships: @@ -2595,7 +2598,22 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + deprecated: + type: boolean + description: | + Return `true` if a Course will no longer be delivered, or there is no + expectation that it will be delivered in the foreseeable future. + + **Deprecate, do not delete!** + + Institutions **must** keep a permanent record of all Courses ever delivered + so that they may be dereferenced from _Course instances_. + + Servers **must** omit deprecated Courses from Course collections (unless + `deprecated` is used as a filter). + + Servers **must** provide deprecated Course data via its **canonical path**. meta: $ref: '#/components/schemas/CourseMeta' relationships: From 3cbac1d0cfca7585d9cad54570a3a3989f13a2eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 13:56:57 +0200 Subject: [PATCH 13/23] Missing description for deprecated field --- .../components/schemas/CourseDataProperties.yaml | 12 ++++++++++++ public/v2/openapi.yaml | 14 +++++++++++++- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 1559498..0f544e5 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -93,3 +93,15 @@ lastModified: deprecated: type: boolean description: | + Return `true` if a Course will no longer be delivered, or there is no + expectation that it will be delivered in the foreseeable future. + + **Deprecate, do not delete!** + + Institutions **must** keep a permanent record of all Courses ever delivered + so that they may be dereferenced from _Course instances_. + + Servers **must** omit deprecated Courses from Course collections (unless + `deprecated` is used as a filter). + + Servers **must** provide deprecated Course data via its **canonical path**. diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index a84d170..21a64af 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2419,7 +2419,19 @@ components: [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). deprecated: type: boolean - description: '' + description: | + Return `true` if a Course will no longer be delivered, or there is no + expectation that it will be delivered in the foreseeable future. + + **Deprecate, do not delete!** + + Institutions **must** keep a permanent record of all Courses ever delivered + so that they may be dereferenced from _Course instances_. + + Servers **must** omit deprecated Courses from Course collections (unless + `deprecated` is used as a filter). + + Servers **must** provide deprecated Course data via its **canonical path**. meta: $ref: '#/components/schemas/CourseMeta' relationships: From a9a2b71897cf6af942ea4144cca30484a7804caf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 14:14:19 +0200 Subject: [PATCH 14/23] Groups fields and links schemas in subdirs --- .../components/schemas/CourseCollection.yaml | 4 +-- openapi/v2/components/schemas/CourseData.yaml | 2 +- .../schemas/CourseDataExtended.yaml | 2 +- .../schemas/CourseDataExtendedProperties.yaml | 32 +++++++++---------- .../schemas/CourseDataProperties.yaml | 20 ++++++------ .../schemas/CourseRelationships.yaml | 4 +-- .../v2/components/schemas/CourseResource.yaml | 4 +-- openapi/v2/components/schemas/Email.yaml | 4 --- openapi/v2/components/schemas/Error.yaml | 2 +- .../schemas/InstitutionCollection.yaml | 4 +-- .../components/schemas/InstitutionData.yaml | 14 ++++---- .../schemas/InstitutionResource.yaml | 4 +-- .../components/schemas/OunitCollection.yaml | 4 +-- openapi/v2/components/schemas/OunitData.yaml | 12 +++---- .../v2/components/schemas/OunitResource.yaml | 4 +-- .../schemas/ProgrammeCollection.yaml | 4 +-- .../v2/components/schemas/ProgrammeData.yaml | 4 +-- .../schemas/ProgrammeDataProperties.yaml | 22 ++++++------- .../components/schemas/ProgrammeResource.yaml | 4 +-- openapi/v2/components/schemas/Root.yaml | 4 +-- openapi/v2/components/schemas/ServerData.yaml | 8 ++--- openapi/v2/components/schemas/User.yaml | 19 ----------- .../{ => fields}/ElmAssessmentType.yaml | 0 .../{ => fields}/ElmLearningActivityType.yaml | 0 .../ElmLearningOpportunityTypeCourse.yaml | 0 .../ElmLearningOpportunityTypeProgramme.yaml | 0 .../{ => fields}/ElmLearningScheduleType.yaml | 0 .../ElmModeOfLearningAndAssessment.yaml | 0 .../{ => fields}/EqfLevelProvided.yaml | 0 .../{ => fields}/HttpWithOptionalLang.yaml | 0 .../components/schemas/{ => fields}/Lang.yaml | 0 .../{ => fields}/LanguageOfInstruction.yaml | 0 .../{ => fields}/LocalClassification.yaml | 0 .../MultilineStringWithOptionalLang.yaml | 0 .../schemas/{ => fields}/ProgrammeLength.yaml | 0 .../{ => fields}/StringWithOptionalLang.yaml | 0 .../schemas/{ => links}/Jsonapi.yaml | 0 .../schemas/{ => links}/LinksCollection.yaml | 0 .../{ => links}/LinksCourseCollection.yaml | 0 .../LinksInstitutionCollection.yaml | 0 .../{ => links}/LinksOunitCollection.yaml | 0 .../{ => links}/LinksProgrammeCollection.yaml | 0 .../schemas/{ => links}/LinksResource.yaml | 0 .../schemas/{ => links}/LinksSelf.yaml | 0 44 files changed, 79 insertions(+), 102 deletions(-) delete mode 100644 openapi/v2/components/schemas/Email.yaml delete mode 100644 openapi/v2/components/schemas/User.yaml rename openapi/v2/components/schemas/{ => fields}/ElmAssessmentType.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ElmLearningActivityType.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ElmLearningOpportunityTypeCourse.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ElmLearningOpportunityTypeProgramme.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ElmLearningScheduleType.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ElmModeOfLearningAndAssessment.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/EqfLevelProvided.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/HttpWithOptionalLang.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/Lang.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/LanguageOfInstruction.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/LocalClassification.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/MultilineStringWithOptionalLang.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/ProgrammeLength.yaml (100%) rename openapi/v2/components/schemas/{ => fields}/StringWithOptionalLang.yaml (100%) rename openapi/v2/components/schemas/{ => links}/Jsonapi.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksCollection.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksCourseCollection.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksInstitutionCollection.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksOunitCollection.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksProgrammeCollection.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksResource.yaml (100%) rename openapi/v2/components/schemas/{ => links}/LinksSelf.yaml (100%) diff --git a/openapi/v2/components/schemas/CourseCollection.yaml b/openapi/v2/components/schemas/CourseCollection.yaml index 6a6b4e0..e755aa9 100644 --- a/openapi/v2/components/schemas/CourseCollection.yaml +++ b/openapi/v2/components/schemas/CourseCollection.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: array description: List of _Course_ resources. @@ -22,4 +22,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksCollection.yaml + $ref: ./links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index 4832027..82349e2 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -28,4 +28,4 @@ links: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index b651f85..5b70047 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -28,4 +28,4 @@ links: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index 59e91fe..a305d95 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -3,7 +3,7 @@ title: minItems: 1 description: Title with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml code: type: string minItems: 1 @@ -34,15 +34,15 @@ description: minItems: 1 description: Description with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml elmAssessmentType: - $ref: ./ElmAssessmentType.yaml + $ref: ./fields/ElmAssessmentType.yaml elmLearningActivityType: - $ref: ./ElmLearningActivityType.yaml + $ref: ./fields/ElmLearningActivityType.yaml elmLearningOpportunityType: - $ref: ./ElmLearningOpportunityTypeCourse.yaml + $ref: ./fields/ElmLearningOpportunityTypeCourse.yaml elmModeOfLearning: - $ref: ./ElmModeOfLearningAndAssessment.yaml + $ref: ./fields/ElmModeOfLearningAndAssessment.yaml iscedCode: type: array description: | @@ -60,15 +60,15 @@ iscedCode: minLength: 2 maxLength: 4 languageOfInstruction: - $ref: ./LanguageOfInstruction.yaml + $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 description: Learning outcomes with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml localClassification: - $ref: ./LocalClassification.yaml + $ref: ./fields/LocalClassification.yaml restrictedToLocalStudents: type: boolean description: | @@ -83,27 +83,27 @@ url: type: array description: External URL with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml bibliography: type: array description: Bibliography with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml courseContent: type: array description: Course content with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml prerequisites: type: array description: Prerequisites with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml courseAvailability: type: array description: Course availability with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml teachingMethod: type: array description: | @@ -111,7 +111,7 @@ teachingMethod: **Note:** It is preferable to use `elmLearningActivityType` instead. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml assessmentMethod: type: array description: | @@ -119,7 +119,7 @@ assessmentMethod: **Note:** It is preferable to use `elmAssessmentType` instead. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml lastModified: type: string format: date-time diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 0f544e5..db4eb8b 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -3,7 +3,7 @@ title: minItems: 1 description: Title with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml code: type: string minItems: 1 @@ -34,15 +34,15 @@ description: minItems: 1 description: Description with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml elmAssessmentType: - $ref: ./ElmAssessmentType.yaml + $ref: ./fields/ElmAssessmentType.yaml elmLearningActivityType: - $ref: ./ElmLearningActivityType.yaml + $ref: ./fields/ElmLearningActivityType.yaml elmLearningOpportunityType: - $ref: ./ElmLearningOpportunityTypeCourse.yaml + $ref: ./fields/ElmLearningOpportunityTypeCourse.yaml elmModeOfLearning: - $ref: ./ElmModeOfLearningAndAssessment.yaml + $ref: ./fields/ElmModeOfLearningAndAssessment.yaml iscedCode: type: array description: | @@ -60,15 +60,15 @@ iscedCode: minLength: 2 maxLength: 4 languageOfInstruction: - $ref: ./LanguageOfInstruction.yaml + $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 description: Learning outcomes with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml localClassification: - $ref: ./LocalClassification.yaml + $ref: ./fields/LocalClassification.yaml restrictedToLocalStudents: type: boolean description: | @@ -83,7 +83,7 @@ url: type: array description: External URL with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml lastModified: type: string format: date-time diff --git a/openapi/v2/components/schemas/CourseRelationships.yaml b/openapi/v2/components/schemas/CourseRelationships.yaml index 38f124a..1520717 100644 --- a/openapi/v2/components/schemas/CourseRelationships.yaml +++ b/openapi/v2/components/schemas/CourseRelationships.yaml @@ -40,7 +40,7 @@ properties: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml relatedProgramme: type: array description: | @@ -76,4 +76,4 @@ properties: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseResource.yaml b/openapi/v2/components/schemas/CourseResource.yaml index 3de37fc..e325e26 100644 --- a/openapi/v2/components/schemas/CourseResource.yaml +++ b/openapi/v2/components/schemas/CourseResource.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: object description: _Course_ resource data. @@ -20,4 +20,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/Email.yaml b/openapi/v2/components/schemas/Email.yaml deleted file mode 100644 index 55801ff..0000000 --- a/openapi/v2/components/schemas/Email.yaml +++ /dev/null @@ -1,4 +0,0 @@ -description: User email address -type: string -format: test -example: john.smith@example.com diff --git a/openapi/v2/components/schemas/Error.yaml b/openapi/v2/components/schemas/Error.yaml index 03ff4ae..abfa446 100644 --- a/openapi/v2/components/schemas/Error.yaml +++ b/openapi/v2/components/schemas/Error.yaml @@ -4,7 +4,7 @@ required: - errors properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml errors: type: array description: List of errors. diff --git a/openapi/v2/components/schemas/InstitutionCollection.yaml b/openapi/v2/components/schemas/InstitutionCollection.yaml index 46d78b1..2deee94 100644 --- a/openapi/v2/components/schemas/InstitutionCollection.yaml +++ b/openapi/v2/components/schemas/InstitutionCollection.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: array description: List of _Institution_ resources. @@ -22,4 +22,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksCollection.yaml + $ref: ./links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index c285a61..b4174b5 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -19,7 +19,7 @@ attributes: minItems: 1 description: Title with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml heiId: type: string description: The SCHAC code of the Institution. @@ -29,12 +29,12 @@ attributes: description: Most widely recognized abbbreviation with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml url: type: array description: External URL with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml lastModified: type: string format: date-time @@ -48,10 +48,10 @@ links: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml ounit: - $ref: ./LinksOunitCollection.yaml + $ref: ./links/LinksOunitCollection.yaml programme: - $ref: ./LinksProgrammeCollection.yaml + $ref: ./links/LinksProgrammeCollection.yaml course: - $ref: ./LinksCourseCollection.yaml + $ref: ./links/LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/InstitutionResource.yaml b/openapi/v2/components/schemas/InstitutionResource.yaml index fbc6b8b..46d1453 100644 --- a/openapi/v2/components/schemas/InstitutionResource.yaml +++ b/openapi/v2/components/schemas/InstitutionResource.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: object description: _Institution_ resource data. @@ -20,4 +20,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/OunitCollection.yaml b/openapi/v2/components/schemas/OunitCollection.yaml index 2713039..85bb8c6 100644 --- a/openapi/v2/components/schemas/OunitCollection.yaml +++ b/openapi/v2/components/schemas/OunitCollection.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: array description: List of _Organisational Unit_ resources. @@ -22,4 +22,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksCollection.yaml + $ref: ./links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 2d711d9..962dd89 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -20,7 +20,7 @@ attributes: type: array description: Title with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml ounitId: type: string description: Unique identifier within the Institution. Can be a UUID. @@ -29,7 +29,7 @@ attributes: description: Most widely recognized abbbreviation with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml ounitCode: type: string description: Human readable code identifying the Organisational Unit. @@ -37,7 +37,7 @@ attributes: type: array description: External URL with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml lastModified: type: string format: date-time @@ -51,8 +51,8 @@ links: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml programme: - $ref: ./LinksProgrammeCollection.yaml + $ref: ./links/LinksProgrammeCollection.yaml course: - $ref: ./LinksCourseCollection.yaml + $ref: ./links/LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/OunitResource.yaml b/openapi/v2/components/schemas/OunitResource.yaml index 145e693..f13d0bd 100644 --- a/openapi/v2/components/schemas/OunitResource.yaml +++ b/openapi/v2/components/schemas/OunitResource.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: object description: _Organisational Unit_ resource data. @@ -20,4 +20,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/ProgrammeCollection.yaml b/openapi/v2/components/schemas/ProgrammeCollection.yaml index 9839fc3..46a82ac 100644 --- a/openapi/v2/components/schemas/ProgrammeCollection.yaml +++ b/openapi/v2/components/schemas/ProgrammeCollection.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: array description: List of _Programme_ resources. @@ -22,4 +22,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksCollection.yaml + $ref: ./links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index cf64110..8b64142 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -25,6 +25,6 @@ links: - self properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml course: - $ref: ./LinksCourseCollection.yaml + $ref: ./links/LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index 0a1ef44..dad89b8 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -3,7 +3,7 @@ title: minItems: 1 description: Title with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml code: type: string minLength: 1 @@ -13,24 +13,24 @@ ects: minimum: 0 description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: - $ref: ./EqfLevelProvided.yaml + $ref: ./fields/EqfLevelProvided.yaml abbreviation: type: array description: Abbbreviation with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml description: type: array minItems: 1 description: Description with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml elmLearningOpportunityType: - $ref: ./ElmLearningOpportunityTypeProgramme.yaml + $ref: ./fields/ElmLearningOpportunityTypeProgramme.yaml elmLearningScheduleType: - $ref: ./ElmLearningScheduleType.yaml + $ref: ./fields/ElmLearningScheduleType.yaml elmModeOfLearning: - $ref: ./ElmModeOfLearningAndAssessment.yaml + $ref: ./fields/ElmModeOfLearningAndAssessment.yaml iscedCode: type: array minItems: 1 @@ -49,20 +49,20 @@ iscedCode: minLength: 2 maxLength: 4 languageOfInstruction: - $ref: ./LanguageOfInstruction.yaml + $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 description: Learning outcomes with optional language code. items: - $ref: ./MultilineStringWithOptionalLang.yaml + $ref: ./fields/MultilineStringWithOptionalLang.yaml length: - $ref: ./ProgrammeLength.yaml + $ref: ./fields/ProgrammeLength.yaml url: type: array description: External URL with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml validSince: type: string format: date diff --git a/openapi/v2/components/schemas/ProgrammeResource.yaml b/openapi/v2/components/schemas/ProgrammeResource.yaml index fda27a6..252ca6a 100644 --- a/openapi/v2/components/schemas/ProgrammeResource.yaml +++ b/openapi/v2/components/schemas/ProgrammeResource.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: type: object description: _Programme_ resource data. @@ -20,4 +20,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/Root.yaml b/openapi/v2/components/schemas/Root.yaml index 73386c0..c86e073 100644 --- a/openapi/v2/components/schemas/Root.yaml +++ b/openapi/v2/components/schemas/Root.yaml @@ -4,7 +4,7 @@ required: - data properties: jsonapi: - $ref: ./Jsonapi.yaml + $ref: ./links/Jsonapi.yaml data: $ref: ./ServerData.yaml meta: @@ -15,4 +15,4 @@ properties: description: JSON:API _links_ object. properties: self: - $ref: ./LinksSelf.yaml + $ref: ./links/LinksSelf.yaml diff --git a/openapi/v2/components/schemas/ServerData.yaml b/openapi/v2/components/schemas/ServerData.yaml index 2e01949..89170a5 100644 --- a/openapi/v2/components/schemas/ServerData.yaml +++ b/openapi/v2/components/schemas/ServerData.yaml @@ -25,13 +25,13 @@ properties: minItems: 1 description: Server name with optional language code. items: - $ref: ./StringWithOptionalLang.yaml + $ref: ./fields/StringWithOptionalLang.yaml termsOfService: type: array minItems: 1 description: URL for Terms of service with optional language code. items: - $ref: ./HttpWithOptionalLang.yaml + $ref: ./fields/HttpWithOptionalLang.yaml links: type: object description: JSON:API _links_ object. @@ -40,6 +40,6 @@ properties: - hei properties: self: - $ref: ./LinksResource.yaml + $ref: ./links/LinksResource.yaml hei: - $ref: ./LinksInstitutionCollection.yaml + $ref: ./links/LinksInstitutionCollection.yaml diff --git a/openapi/v2/components/schemas/User.yaml b/openapi/v2/components/schemas/User.yaml deleted file mode 100644 index efdeb3b..0000000 --- a/openapi/v2/components/schemas/User.yaml +++ /dev/null @@ -1,19 +0,0 @@ -type: object -properties: - username: - description: User supplied username - type: string - minLength: 4 - example: John78 - firstName: - description: User first name - type: string - minLength: 1 - example: John - lastName: - description: User last name - type: string - minLength: 1 - example: Smith - email: - $ref: ./Email.yaml diff --git a/openapi/v2/components/schemas/ElmAssessmentType.yaml b/openapi/v2/components/schemas/fields/ElmAssessmentType.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmAssessmentType.yaml rename to openapi/v2/components/schemas/fields/ElmAssessmentType.yaml diff --git a/openapi/v2/components/schemas/ElmLearningActivityType.yaml b/openapi/v2/components/schemas/fields/ElmLearningActivityType.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmLearningActivityType.yaml rename to openapi/v2/components/schemas/fields/ElmLearningActivityType.yaml diff --git a/openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml b/openapi/v2/components/schemas/fields/ElmLearningOpportunityTypeCourse.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmLearningOpportunityTypeCourse.yaml rename to openapi/v2/components/schemas/fields/ElmLearningOpportunityTypeCourse.yaml diff --git a/openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml b/openapi/v2/components/schemas/fields/ElmLearningOpportunityTypeProgramme.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmLearningOpportunityTypeProgramme.yaml rename to openapi/v2/components/schemas/fields/ElmLearningOpportunityTypeProgramme.yaml diff --git a/openapi/v2/components/schemas/ElmLearningScheduleType.yaml b/openapi/v2/components/schemas/fields/ElmLearningScheduleType.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmLearningScheduleType.yaml rename to openapi/v2/components/schemas/fields/ElmLearningScheduleType.yaml diff --git a/openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml b/openapi/v2/components/schemas/fields/ElmModeOfLearningAndAssessment.yaml similarity index 100% rename from openapi/v2/components/schemas/ElmModeOfLearningAndAssessment.yaml rename to openapi/v2/components/schemas/fields/ElmModeOfLearningAndAssessment.yaml diff --git a/openapi/v2/components/schemas/EqfLevelProvided.yaml b/openapi/v2/components/schemas/fields/EqfLevelProvided.yaml similarity index 100% rename from openapi/v2/components/schemas/EqfLevelProvided.yaml rename to openapi/v2/components/schemas/fields/EqfLevelProvided.yaml diff --git a/openapi/v2/components/schemas/HttpWithOptionalLang.yaml b/openapi/v2/components/schemas/fields/HttpWithOptionalLang.yaml similarity index 100% rename from openapi/v2/components/schemas/HttpWithOptionalLang.yaml rename to openapi/v2/components/schemas/fields/HttpWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/Lang.yaml b/openapi/v2/components/schemas/fields/Lang.yaml similarity index 100% rename from openapi/v2/components/schemas/Lang.yaml rename to openapi/v2/components/schemas/fields/Lang.yaml diff --git a/openapi/v2/components/schemas/LanguageOfInstruction.yaml b/openapi/v2/components/schemas/fields/LanguageOfInstruction.yaml similarity index 100% rename from openapi/v2/components/schemas/LanguageOfInstruction.yaml rename to openapi/v2/components/schemas/fields/LanguageOfInstruction.yaml diff --git a/openapi/v2/components/schemas/LocalClassification.yaml b/openapi/v2/components/schemas/fields/LocalClassification.yaml similarity index 100% rename from openapi/v2/components/schemas/LocalClassification.yaml rename to openapi/v2/components/schemas/fields/LocalClassification.yaml diff --git a/openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml b/openapi/v2/components/schemas/fields/MultilineStringWithOptionalLang.yaml similarity index 100% rename from openapi/v2/components/schemas/MultilineStringWithOptionalLang.yaml rename to openapi/v2/components/schemas/fields/MultilineStringWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/ProgrammeLength.yaml b/openapi/v2/components/schemas/fields/ProgrammeLength.yaml similarity index 100% rename from openapi/v2/components/schemas/ProgrammeLength.yaml rename to openapi/v2/components/schemas/fields/ProgrammeLength.yaml diff --git a/openapi/v2/components/schemas/StringWithOptionalLang.yaml b/openapi/v2/components/schemas/fields/StringWithOptionalLang.yaml similarity index 100% rename from openapi/v2/components/schemas/StringWithOptionalLang.yaml rename to openapi/v2/components/schemas/fields/StringWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/Jsonapi.yaml b/openapi/v2/components/schemas/links/Jsonapi.yaml similarity index 100% rename from openapi/v2/components/schemas/Jsonapi.yaml rename to openapi/v2/components/schemas/links/Jsonapi.yaml diff --git a/openapi/v2/components/schemas/LinksCollection.yaml b/openapi/v2/components/schemas/links/LinksCollection.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksCollection.yaml rename to openapi/v2/components/schemas/links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/LinksCourseCollection.yaml b/openapi/v2/components/schemas/links/LinksCourseCollection.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksCourseCollection.yaml rename to openapi/v2/components/schemas/links/LinksCourseCollection.yaml diff --git a/openapi/v2/components/schemas/LinksInstitutionCollection.yaml b/openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksInstitutionCollection.yaml rename to openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml diff --git a/openapi/v2/components/schemas/LinksOunitCollection.yaml b/openapi/v2/components/schemas/links/LinksOunitCollection.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksOunitCollection.yaml rename to openapi/v2/components/schemas/links/LinksOunitCollection.yaml diff --git a/openapi/v2/components/schemas/LinksProgrammeCollection.yaml b/openapi/v2/components/schemas/links/LinksProgrammeCollection.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksProgrammeCollection.yaml rename to openapi/v2/components/schemas/links/LinksProgrammeCollection.yaml diff --git a/openapi/v2/components/schemas/LinksResource.yaml b/openapi/v2/components/schemas/links/LinksResource.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksResource.yaml rename to openapi/v2/components/schemas/links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/LinksSelf.yaml b/openapi/v2/components/schemas/links/LinksSelf.yaml similarity index 100% rename from openapi/v2/components/schemas/LinksSelf.yaml rename to openapi/v2/components/schemas/links/LinksSelf.yaml From bd4b32bfed74db544f39828f10b335ee59f347d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 16:59:58 +0200 Subject: [PATCH 15/23] Fixes a typo --- openapi/v2/components/schemas/InstitutionData.yaml | 2 +- openapi/v2/components/schemas/OunitData.yaml | 2 +- openapi/v2/components/schemas/ProgrammeDataProperties.yaml | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index b4174b5..1d033c5 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -40,7 +40,7 @@ attributes: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 962dd89..2c32988 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -43,7 +43,7 @@ attributes: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index dad89b8..792adeb 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -68,16 +68,16 @@ validSince: format: date description: | The first date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: type: string format: date description: | The last date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). lastModified: type: string format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). From 52d150b7800db1aa6fe1da09f65c81b7bc6e7371 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 17:00:27 +0200 Subject: [PATCH 16/23] Rebuilds examples according to the current schema --- .../responses/CourseCollection.yaml | 50 ++- .../components/responses/CourseResource.yaml | 50 ++- .../responses/InstitutionCollection.yaml | 16 +- .../responses/InstitutionResource.yaml | 22 +- .../components/responses/OunitCollection.yaml | 11 +- .../responses/OunitCourseCollection.yaml | 49 ++- .../responses/OunitProgrammeCollection.yaml | 35 +- .../components/responses/OunitResource.yaml | 15 +- .../responses/ProgrammeCollection.yaml | 35 +- .../responses/ProgrammeCourseCollection.yaml | 49 ++- .../responses/ProgrammeResource.yaml | 37 +- openapi/v2/components/responses/Root.yaml | 19 +- public/v2/openapi.yaml | 408 +++++++++++++----- 13 files changed, 586 insertions(+), 210 deletions(-) diff --git a/openapi/v2/components/responses/CourseCollection.yaml b/openapi/v2/components/responses/CourseCollection.yaml index 2032e9a..62770d2 100644 --- a/openapi/v2/components/responses/CourseCollection.yaml +++ b/openapi/v2/components/responses/CourseCollection.yaml @@ -12,39 +12,63 @@ data: - 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 - academicTerm: '1/2' - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: 'zero' - unavailableForIncomingMobility: false + 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: - global: - eqfLevel: 6 - year: '1/3' - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' + href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/course' + href: 'http://example.com/occapi/v2/hei/domain.tld/course' diff --git a/openapi/v2/components/responses/CourseResource.yaml b/openapi/v2/components/responses/CourseResource.yaml index 90a50a2..fd05f9b 100644 --- a/openapi/v2/components/responses/CourseResource.yaml +++ b/openapi/v2/components/responses/CourseResource.yaml @@ -12,25 +12,41 @@ data: - 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 - academicTerm: '1/2' - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: 'zero' - unavailableForIncomingMobility: false + localClassification: + - classificationSystem: 'erasmus' + classificationValue: '00.0' + restrictedToLocalStudents: false + restrictedToAllianceStudents: true url: - uri: www.domain.tld/example/course lang: en @@ -70,17 +86,25 @@ data: This is a long text field. lang: en + lastModified: 2025-09-01T12:00:00Z + deprecated: false meta: - global: - eqfLevel: 6 - year: '1/3' - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' + href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' + href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' diff --git a/openapi/v2/components/responses/InstitutionCollection.yaml b/openapi/v2/components/responses/InstitutionCollection.yaml index 7d62411..20b721f 100644 --- a/openapi/v2/components/responses/InstitutionCollection.yaml +++ b/openapi/v2/components/responses/InstitutionCollection.yaml @@ -6,19 +6,27 @@ jsonapi: href: "http://jsonapi.org/format/1.1/" data: - type: hei - id: 12345678-90ab-cdef-1234-567890abcdef + id: domain.tld attributes: title: - string: Example Institution lang: en - abbreviation: EI + abbreviation: + - string: EI heiId: domain.tld url: - uri: www.domain.tld lang: en + lastModified: 2025-09-01T12:00:00Z links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld' + href: 'http://example.com/occapi/v2/hei/domain.tld' + ounit: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit' + programme: + href: 'http://example.com/occapi/v2/hei/domain.tld/programme' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/course' links: self: - href: 'http://example.com/occapi/v1/hei' + href: 'http://example.com/occapi/v2/hei' diff --git a/openapi/v2/components/responses/InstitutionResource.yaml b/openapi/v2/components/responses/InstitutionResource.yaml index 7f7cebe..9c75dff 100644 --- a/openapi/v2/components/responses/InstitutionResource.yaml +++ b/openapi/v2/components/responses/InstitutionResource.yaml @@ -6,25 +6,27 @@ jsonapi: href: "http://jsonapi.org/format/1.1/" data: type: hei - id: 12345678-90ab-cdef-1234-567890abcdef + id: domain.tld attributes: title: - string: Example Institution lang: en - abbreviation: EI + abbreviation: + - string: EI heiId: domain.tld url: - uri: www.domain.tld lang: en + lastModified: 2025-09-01T12:00:00Z links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld' + href: 'http://example.com/occapi/v2/hei/domain.tld' + ounit: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit' + programme: + href: 'http://example.com/occapi/v2/hei/domain.tld/programme' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld' - ounit: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit' - programme: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme' - course: - href: 'http://example.com/occapi/v1/hei/domain.tld/course' + href: 'http://example.com/occapi/v2/hei/domain.tld' diff --git a/openapi/v2/components/responses/OunitCollection.yaml b/openapi/v2/components/responses/OunitCollection.yaml index da027f9..5dbc58c 100644 --- a/openapi/v2/components/responses/OunitCollection.yaml +++ b/openapi/v2/components/responses/OunitCollection.yaml @@ -11,7 +11,8 @@ data: title: - string: Example Organisational Unit lang: en - abbreviation: EOU + abbreviation: + - string: EOU ounitId: 11223344-5566-7788-9900-aabbccddeeff ounitCode: EI-EOU url: @@ -19,7 +20,11 @@ data: lang: en links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' + programme: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit' diff --git a/openapi/v2/components/responses/OunitCourseCollection.yaml b/openapi/v2/components/responses/OunitCourseCollection.yaml index 7ce4ef3..e001957 100644 --- a/openapi/v2/components/responses/OunitCourseCollection.yaml +++ b/openapi/v2/components/responses/OunitCourseCollection.yaml @@ -12,38 +12,63 @@ data: - 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 - academicTerm: '1/2' - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: 'zero' + 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: - global: - eqfLevel: 6 - year: '1/3' - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' + href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' diff --git a/openapi/v2/components/responses/OunitProgrammeCollection.yaml b/openapi/v2/components/responses/OunitProgrammeCollection.yaml index c3126bd..5960cf2 100644 --- a/openapi/v2/components/responses/OunitProgrammeCollection.yaml +++ b/openapi/v2/components/responses/OunitProgrammeCollection.yaml @@ -12,23 +12,44 @@ data: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: 0000 - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: 2020-01-01 + validUntil: 2029-12-31 + lastModified: 2025-09-01T12:00:00Z links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' diff --git a/openapi/v2/components/responses/OunitResource.yaml b/openapi/v2/components/responses/OunitResource.yaml index e012ede..641cfc4 100644 --- a/openapi/v2/components/responses/OunitResource.yaml +++ b/openapi/v2/components/responses/OunitResource.yaml @@ -11,7 +11,8 @@ data: title: - string: Example Organisational Unit lang: en - abbreviation: EOU + abbreviation: + - string: EOU ounitId: 11223344-5566-7788-9900-aabbccddeeff ounitCode: EI-EOU url: @@ -19,11 +20,11 @@ data: lang: en links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' + programme: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' - programme: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme' - course: - href: 'http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course' + href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' diff --git a/openapi/v2/components/responses/ProgrammeCollection.yaml b/openapi/v2/components/responses/ProgrammeCollection.yaml index 1ace5ac..de2c84b 100644 --- a/openapi/v2/components/responses/ProgrammeCollection.yaml +++ b/openapi/v2/components/responses/ProgrammeCollection.yaml @@ -12,23 +12,44 @@ data: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: 0000 - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: 2020-01-01 + validUntil: 2029-12-31 + lastModified: 2025-09-01T12:00:00Z links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme' diff --git a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml index 08e570d..b14bc32 100644 --- a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml +++ b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml @@ -12,38 +12,63 @@ data: - 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 - academicTerm: '1/2' - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: 'zero' + 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: - global: - eqfLevel: 6 - year: '1/3' - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' + href: 'http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' diff --git a/openapi/v2/components/responses/ProgrammeResource.yaml b/openapi/v2/components/responses/ProgrammeResource.yaml index 86da34d..d982672 100644 --- a/openapi/v2/components/responses/ProgrammeResource.yaml +++ b/openapi/v2/components/responses/ProgrammeResource.yaml @@ -12,25 +12,44 @@ data: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: '0000' - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: 2020-01-01 + validUntil: 2029-12-31 + lastModified: 2025-09-01T12:00:00Z links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' + course: + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' links: self: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' - course: - href: 'http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course' + href: 'http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890' diff --git a/openapi/v2/components/responses/Root.yaml b/openapi/v2/components/responses/Root.yaml index 85acfe6..86cd9ec 100644 --- a/openapi/v2/components/responses/Root.yaml +++ b/openapi/v2/components/responses/Root.yaml @@ -4,9 +4,22 @@ jsonapi: links: self: href: "http://jsonapi.org/format/1.1/" +data: + type: "server" + id: 12345678-90ab-cdef-1234-567890abcdef + attributes: + serverName: + - string: "Test server" + lang: "en" + - string: "Servidor de testes" + lang: "pt" + termsOfService: [] + links: + self: + href: "http://example.com/occapi/v2" + hei: + href: "http://example.com/occapi/v2/hei" meta: {} links: self: - href: 'http://example.com/occapi/v1' - hei: - href: 'http://example.com/occapi/v1/hei' + href: "http://example.com/occapi/v2" diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 21a64af..ab4fe29 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -58,12 +58,25 @@ paths: links: self: href: http://jsonapi.org/format/1.1/ + data: + type: server + id: 12345678-90ab-cdef-1234-567890abcdef + attributes: + serverName: + - string: Test server + lang: en + - string: Servidor de testes + lang: pt + termsOfService: [] + links: + self: + href: http://example.com/occapi/v2 + hei: + href: http://example.com/occapi/v2/hei meta: {} links: self: - href: http://example.com/occapi/v1 - hei: - href: http://example.com/occapi/v1/hei + href: http://example.com/occapi/v2 '404': description: Endpoint not available. content: @@ -115,22 +128,30 @@ paths: href: http://jsonapi.org/format/1.1/ data: - type: hei - id: 12345678-90ab-cdef-1234-567890abcdef + id: domain.tld attributes: title: - string: Example Institution lang: en - abbreviation: EI + abbreviation: + - string: EI heiId: domain.tld url: - uri: www.domain.tld lang: en + lastModified: '2025-09-01T12:00:00Z' links: self: - href: http://example.com/occapi/v1/hei/domain.tld + href: http://example.com/occapi/v2/hei/domain.tld + ounit: + href: http://example.com/occapi/v2/hei/domain.tld/ounit + programme: + href: http://example.com/occapi/v2/hei/domain.tld/programme + course: + href: http://example.com/occapi/v2/hei/domain.tld/course links: self: - href: http://example.com/occapi/v1/hei + href: http://example.com/occapi/v2/hei '404': description: Endpoint not available. content: @@ -191,28 +212,30 @@ paths: href: http://jsonapi.org/format/1.1/ data: type: hei - id: 12345678-90ab-cdef-1234-567890abcdef + id: domain.tld attributes: title: - string: Example Institution lang: en - abbreviation: EI + abbreviation: + - string: EI heiId: domain.tld url: - uri: www.domain.tld lang: en + lastModified: '2025-09-01T12:00:00Z' links: self: - href: http://example.com/occapi/v1/hei/domain.tld + href: http://example.com/occapi/v2/hei/domain.tld + ounit: + href: http://example.com/occapi/v2/hei/domain.tld/ounit + programme: + href: http://example.com/occapi/v2/hei/domain.tld/programme + course: + href: http://example.com/occapi/v2/hei/domain.tld/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld - ounit: - href: http://example.com/occapi/v1/hei/domain.tld/ounit - programme: - href: http://example.com/occapi/v1/hei/domain.tld/programme - course: - href: http://example.com/occapi/v1/hei/domain.tld/course + href: http://example.com/occapi/v2/hei/domain.tld '404': description: Resource not found. content: @@ -274,7 +297,8 @@ paths: title: - string: Example Organisational Unit lang: en - abbreviation: EOU + abbreviation: + - string: EOU ounitId: 11223344-5566-7788-9900-aabbccddeeff ounitCode: EI-EOU url: @@ -282,10 +306,14 @@ paths: lang: en links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff + programme: + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme + course: + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit + href: http://example.com/occapi/v2/hei/domain.tld/ounit '404': description: Endpoint not available. content: @@ -355,7 +383,8 @@ paths: title: - string: Example Organisational Unit lang: en - abbreviation: EOU + abbreviation: + - string: EOU ounitId: 11223344-5566-7788-9900-aabbccddeeff ounitCode: EI-EOU url: @@ -363,14 +392,14 @@ paths: lang: en links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff + programme: + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme + course: + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff - programme: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme - course: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff '404': description: Resource not found. content: @@ -430,26 +459,47 @@ paths: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: 0 - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: '2020-01-01' + validUntil: '2029-12-31' + lastModified: '2025-09-01T12:00:00Z' links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + course: + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme + href: http://example.com/occapi/v2/hei/domain.tld/programme '404': description: Endpoint not available. content: @@ -516,26 +566,47 @@ paths: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: 0 - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: '2020-01-01' + validUntil: '2029-12-31' + lastModified: '2025-09-01T12:00:00Z' links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + course: + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/programme '404': description: Endpoint not available. content: @@ -603,28 +674,47 @@ paths: - string: Example Programme lang: en code: PROG01 + ects: 120 + eqfLevelProvided: 5 + abbreviation: + - string: P1 description: - multiline: | This is the description of the Programme. This is a long text field. lang: en - ects: 120 - eqfLevelProvided: 5 - iscedCode: '0000' - languageOfInstruction: en - length: 2 + elmLearningOpportunityType: + - 74a4a268e8 + elmLearningScheduleType: + - 67395e6b5a + elmModeOfLearning: + - e92d221e4d + iscedCode: + - '0000' + languageOfInstruction: + - en + learningOutcomes: + - multiline: | + These are the learning outcomes of the Programme. + + This is a long text field. + lang: en + length: 4/2 url: - uri: www.domain.tld/example/programme lang: en + validSince: '2020-01-01' + validUntil: '2029-12-31' + lastModified: '2025-09-01T12:00:00Z' links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 + course: + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 - course: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890 '404': description: Resource not found. content: @@ -684,42 +774,66 @@ paths: - 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 - academicTerm: 1/2 - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: zero - unavailableForIncomingMobility: false + 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: - global: - eqfLevel: 6 - year: 1/3 - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 + href: http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 links: self: - href: http://example.com/occapi/v1/hei/domain.tld/course + href: http://example.com/occapi/v2/hei/domain.tld/course '404': description: Endpoint not available. content: @@ -786,41 +900,66 @@ paths: - 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 - academicTerm: 1/2 - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: zero + 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: - global: - eqfLevel: 6 - year: 1/3 - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 + href: http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 links: self: - href: http://example.com/occapi/v1/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course + href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff/course '404': description: Endpoint not available. content: @@ -887,41 +1026,66 @@ paths: - 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 - academicTerm: 1/2 - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: zero + 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: - global: - eqfLevel: 6 - year: 1/3 - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 + href: http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 links: self: - href: http://example.com/occapi/v1/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course + href: http://example.com/occapi/v2/hei/domain.tld/programme/abcdef12-3456-7890-abcd-ef1234567890/course '404': description: Endpoint not available. content: @@ -991,25 +1155,41 @@ paths: - 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 - academicTerm: 1/2 - ects: 6 - languageOfInstruction: en - iscedCode: '0000' - subjectArea: '00.0' - otherCategorization: zero - unavailableForIncomingMobility: false + localClassification: + - classificationSystem: erasmus + classificationValue: '00.0' + restrictedToLocalStudents: false + restrictedToAllianceStudents: true url: - uri: www.domain.tld/example/course lang: en @@ -1049,20 +1229,28 @@ paths: This is a long text field. lang: en + lastModified: '2025-09-01T12:00:00Z' + deprecated: false meta: - global: - eqfLevel: 6 - year: 1/3 - programme: + 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/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 + href: http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 links: self: - href: http://example.com/occapi/v1/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 + href: http://example.com/occapi/v2/hei/domain.tld/course/aabbccdd-eeff-1122-3344-556677889900 '404': description: Resource not found. content: @@ -1387,7 +1575,7 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1467,7 +1655,7 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1550,7 +1738,7 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1629,7 +1817,7 @@ components: format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1883,19 +2071,19 @@ components: format: date description: | The first date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: type: string format: date description: | The last date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). lastModified: type: string format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2017,19 +2205,19 @@ components: format: date description: | The first date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). validUntil: type: string format: date description: | The last date in which the Programme was offered, formatted as - [_YYYY-MM-DD_](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). lastModified: type: string format: date-time description: | Time of latest change to this resource, formatted as - [_YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. From 1e744b2d26541fce53b895f0000476f547dd4adc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 17:51:33 +0200 Subject: [PATCH 17/23] Introduces support for Course instances --- openapi/occapi_v2.yaml | 5 + .../responses/CourseCollection.yaml | 2 + .../responses/CourseInstanceCollection.yaml | 25 ++ .../responses/CourseInstanceResource.yaml | 25 ++ .../components/responses/CourseResource.yaml | 2 + .../components/responses/OunitCollection.yaml | 1 + .../responses/OunitCourseCollection.yaml | 2 + .../components/responses/OunitResource.yaml | 1 + .../responses/ProgrammeCourseCollection.yaml | 2 + openapi/v2/components/schemas/CourseData.yaml | 2 + .../schemas/CourseDataExtended.yaml | 2 + .../schemas/CourseInstanceCollection.yaml | 26 ++ .../schemas/CourseInstanceData.yaml | 32 ++ .../schemas/CourseInstanceRelationships.yaml | 38 ++ .../schemas/CourseInstanceResource.yaml | 24 ++ .../links/LinksCourseInstanceCollection.yaml | 9 + openapi/v2/paths/course@{id}-instance.yaml | 44 +++ openapi/v2/paths/instance@{id}.yaml | 45 +++ public/v2/openapi.yaml | 329 ++++++++++++++++++ 19 files changed, 616 insertions(+) create mode 100644 openapi/v2/components/responses/CourseInstanceCollection.yaml create mode 100644 openapi/v2/components/responses/CourseInstanceResource.yaml create mode 100644 openapi/v2/components/schemas/CourseInstanceCollection.yaml create mode 100644 openapi/v2/components/schemas/CourseInstanceData.yaml create mode 100644 openapi/v2/components/schemas/CourseInstanceRelationships.yaml create mode 100644 openapi/v2/components/schemas/CourseInstanceResource.yaml create mode 100644 openapi/v2/components/schemas/links/LinksCourseInstanceCollection.yaml create mode 100644 openapi/v2/paths/course@{id}-instance.yaml create mode 100644 openapi/v2/paths/instance@{id}.yaml diff --git a/openapi/occapi_v2.yaml b/openapi/occapi_v2.yaml index 65a4e18..9e20bfb 100644 --- a/openapi/occapi_v2.yaml +++ b/openapi/occapi_v2.yaml @@ -63,3 +63,8 @@ paths: $ref: 'v2/paths/programme@{id}-course.yaml' '/hei/{heiId}/course/{id}': $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' diff --git a/openapi/v2/components/responses/CourseCollection.yaml b/openapi/v2/components/responses/CourseCollection.yaml index 62770d2..18ddf4c 100644 --- a/openapi/v2/components/responses/CourseCollection.yaml +++ b/openapi/v2/components/responses/CourseCollection.yaml @@ -69,6 +69,8 @@ data: 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' diff --git a/openapi/v2/components/responses/CourseInstanceCollection.yaml b/openapi/v2/components/responses/CourseInstanceCollection.yaml new file mode 100644 index 0000000..51a55ea --- /dev/null +++ b/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' diff --git a/openapi/v2/components/responses/CourseInstanceResource.yaml b/openapi/v2/components/responses/CourseInstanceResource.yaml new file mode 100644 index 0000000..ceda378 --- /dev/null +++ b/openapi/v2/components/responses/CourseInstanceResource.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/instance/13579bdf-0246-8ace-1357-9bdf02468ace' diff --git a/openapi/v2/components/responses/CourseResource.yaml b/openapi/v2/components/responses/CourseResource.yaml index fd05f9b..7227f1a 100644 --- a/openapi/v2/components/responses/CourseResource.yaml +++ b/openapi/v2/components/responses/CourseResource.yaml @@ -105,6 +105,8 @@ data: 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' diff --git a/openapi/v2/components/responses/OunitCollection.yaml b/openapi/v2/components/responses/OunitCollection.yaml index 5dbc58c..af52707 100644 --- a/openapi/v2/components/responses/OunitCollection.yaml +++ b/openapi/v2/components/responses/OunitCollection.yaml @@ -18,6 +18,7 @@ data: url: - uri: www.domain.tld/eou lang: en + lastModified: 2025-09-01T12:00:00Z links: self: href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' diff --git a/openapi/v2/components/responses/OunitCourseCollection.yaml b/openapi/v2/components/responses/OunitCourseCollection.yaml index e001957..37c57d9 100644 --- a/openapi/v2/components/responses/OunitCourseCollection.yaml +++ b/openapi/v2/components/responses/OunitCourseCollection.yaml @@ -69,6 +69,8 @@ data: 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/ounit/11223344-5566-7788-9900-aabbccddeeff/course' diff --git a/openapi/v2/components/responses/OunitResource.yaml b/openapi/v2/components/responses/OunitResource.yaml index 641cfc4..46382ef 100644 --- a/openapi/v2/components/responses/OunitResource.yaml +++ b/openapi/v2/components/responses/OunitResource.yaml @@ -18,6 +18,7 @@ data: url: - uri: www.domain.tld/eou lang: en + lastModified: 2025-09-01T12:00:00Z links: self: href: 'http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff' diff --git a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml index b14bc32..616895a 100644 --- a/openapi/v2/components/responses/ProgrammeCourseCollection.yaml +++ b/openapi/v2/components/responses/ProgrammeCourseCollection.yaml @@ -69,6 +69,8 @@ data: 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/programme/abcdef12-3456-7890-abcd-ef1234567890/course' diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index 82349e2..0cdbd61 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -29,3 +29,5 @@ links: properties: self: $ref: ./links/LinksResource.yaml + instance: + $ref: ./links/LinksCourseInstanceCollection.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index 5b70047..a793b6b 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -29,3 +29,5 @@ links: properties: self: $ref: ./links/LinksResource.yaml + instance: + $ref: ./links/LinksCourseInstanceCollection.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceCollection.yaml b/openapi/v2/components/schemas/CourseInstanceCollection.yaml new file mode 100644 index 0000000..bffcf27 --- /dev/null +++ b/openapi/v2/components/schemas/CourseInstanceCollection.yaml @@ -0,0 +1,26 @@ +type: object +description: JSON:API collection of _Course instance_ resources. +required: + - data +properties: + jsonapi: + $ref: ./links/Jsonapi.yaml + data: + type: array + description: List of _Course instance_ resources. + items: + type: object + required: + - type + - id + - attributes + - relationships + - links + properties: + $ref: ./CourseInstanceData.yaml + links: + type: object + description: JSON:API _links_ object. + properties: + self: + $ref: ./links/LinksCollection.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceData.yaml b/openapi/v2/components/schemas/CourseInstanceData.yaml new file mode 100644 index 0000000..36bc312 --- /dev/null +++ b/openapi/v2/components/schemas/CourseInstanceData.yaml @@ -0,0 +1,32 @@ +type: + type: string + description: JSON:API resource type. + enum: ['instance'] +id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value + that is unique within the Institution may be used. + # format: uuid + format: uuid +attributes: + type: object + description: JSON:API _attributes_ object. + required: + - lastModified + properties: + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +relationships: + $ref: ./CourseInstanceRelationships.yaml +links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceRelationships.yaml b/openapi/v2/components/schemas/CourseInstanceRelationships.yaml new file mode 100644 index 0000000..a922673 --- /dev/null +++ b/openapi/v2/components/schemas/CourseInstanceRelationships.yaml @@ -0,0 +1,38 @@ +type: object +description: | + JSON:API _relationships_ object. +required: + - course +properties: + course: + type: object + description: | + The _Course_ resource the _Course instance_ refers to. + required: + - data + - links + properties: + data: + type: object + description: _Course_ data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: ['course'] + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but + any value that is unique within the Institution may be used. + # format: uuid + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceResource.yaml b/openapi/v2/components/schemas/CourseInstanceResource.yaml new file mode 100644 index 0000000..34e0544 --- /dev/null +++ b/openapi/v2/components/schemas/CourseInstanceResource.yaml @@ -0,0 +1,24 @@ +type: object +description: JSON:API _Course instance_ resource. +required: + - data +properties: + jsonapi: + $ref: ./links/Jsonapi.yaml + data: + type: object + description: _Course instance_ resource data. + required: + - type + - id + - attributes + - relationships + - links + properties: + $ref: ./CourseInstanceData.yaml + links: + type: object + description: JSON:API _links_ object. + properties: + self: + $ref: ./links/LinksResource.yaml diff --git a/openapi/v2/components/schemas/links/LinksCourseInstanceCollection.yaml b/openapi/v2/components/schemas/links/LinksCourseInstanceCollection.yaml new file mode 100644 index 0000000..08133fe --- /dev/null +++ b/openapi/v2/components/schemas/links/LinksCourseInstanceCollection.yaml @@ -0,0 +1,9 @@ +type: object +description: | + Hypermedia link to the _Course instance_ collection associated with this resource. +required: + - href +properties: + href: + type: string + format: uri diff --git a/openapi/v2/paths/course@{id}-instance.yaml b/openapi/v2/paths/course@{id}-instance.yaml new file mode 100644 index 0000000..31fb189 --- /dev/null +++ b/openapi/v2/paths/course@{id}-instance.yaml @@ -0,0 +1,44 @@ +get: + tags: + - Course instance + summary: GET /hei/{heiId}/course/{id}/instance + description: | + This endpoint lists all _Course instances_ filtered by _Course_. + operationId: getCourseInstances + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + - name: id + in: path + description: The UUID of the _Course_ resource to filter by. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseInstanceCollection.yaml + example: + $ref: ../components/responses/CourseInstanceCollection.yaml + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/EndpointNotAvailable.yaml diff --git a/openapi/v2/paths/instance@{id}.yaml b/openapi/v2/paths/instance@{id}.yaml new file mode 100644 index 0000000..bfef15d --- /dev/null +++ b/openapi/v2/paths/instance@{id}.yaml @@ -0,0 +1,45 @@ +get: + tags: + - Course instance + summary: GET /hei/{heiId}/instance/{id} + description: | + This endpoint exposes extended information about a _Course instance_. + operationId: getCourseInstanceByUuid + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + format: hostname + - name: id + in: path + description: The UUID of the _Course instance_ resource. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/CourseInstanceResource.yaml + example: + $ref: ../components/responses/CourseInstanceResource.yaml + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: ../components/schemas/Error.yaml + example: + $ref: ../components/responses/ResourceNotFound.yaml diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index ab4fe29..6bc8ffc 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -304,6 +304,7 @@ paths: url: - uri: www.domain.tld/eou lang: en + lastModified: '2025-09-01T12:00:00Z' links: self: href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff @@ -390,6 +391,7 @@ paths: url: - uri: www.domain.tld/eou lang: en + lastModified: '2025-09-01T12:00:00Z' links: self: href: http://example.com/occapi/v2/hei/domain.tld/ounit/11223344-5566-7788-9900-aabbccddeeff @@ -831,6 +833,8 @@ paths: 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 @@ -957,6 +961,8 @@ paths: 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/ounit/11223344-5566-7788-9900-aabbccddeeff/course @@ -1083,6 +1089,8 @@ paths: 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/programme/abcdef12-3456-7890-abcd-ef1234567890/course @@ -1248,6 +1256,8 @@ paths: 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 @@ -1267,6 +1277,161 @@ paths: errors: - status: '404' title: Resource not found. + /hei/{heiId}/course/{id}/instance: + get: + tags: + - Course instance + summary: GET /hei/{heiId}/course/{id}/instance + description: | + This endpoint lists all _Course instances_ filtered by _Course_. + operationId: getCourseInstances + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + - name: id + in: path + description: The UUID of the _Course_ resource to filter by. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/CourseInstanceCollection' + example: + 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 + '404': + description: Endpoint not available. + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/Error' + example: + jsonapi: + version: '1.1' + meta: + links: + self: + href: http://jsonapi.org/format/1.1/ + errors: + - status: '404' + title: Endpoint not available. + /hei/{heiId}/instance/{id}: + get: + tags: + - Course instance + summary: GET /hei/{heiId}/instance/{id} + description: | + This endpoint exposes extended information about a _Course instance_. + operationId: getCourseInstanceByUuid + parameters: + - name: heiId + in: path + description: The SCHAC code of the Institution. + required: true + schema: + type: string + format: hostname + - name: id + in: path + description: The UUID of the _Course instance_ resource. + required: true + schema: + type: string + format: uuid + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user. + schema: + type: integer + format: int32 + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/CourseInstanceResource' + example: + 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/instance/13579bdf-0246-8ace-1357-9bdf02468ace + '404': + description: Resource not found. + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/Error' + example: + jsonapi: + version: '1.1' + meta: + links: + self: + href: http://jsonapi.org/format/1.1/ + errors: + - status: '404' + title: Resource not found. components: schemas: Jsonapi: @@ -2477,6 +2642,16 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + LinksCourseInstanceCollection: + type: object + description: | + Hypermedia link to the _Course instance_ collection associated with this resource. + required: + - href + properties: + href: + type: string + format: uri CourseCollection: type: object description: JSON:API collection of _Course_ resources. @@ -2632,6 +2807,8 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + instance: + $ref: '#/components/schemas/LinksCourseInstanceCollection' links: type: object description: JSON:API _links_ object. @@ -2826,6 +3003,158 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + instance: + $ref: '#/components/schemas/LinksCourseInstanceCollection' + links: + type: object + description: JSON:API _links_ object. + properties: + self: + $ref: '#/components/schemas/LinksResource' + CourseInstanceRelationships: + type: object + description: | + JSON:API _relationships_ object. + required: + - course + properties: + course: + type: object + description: | + The _Course_ resource the _Course instance_ refers to. + required: + - data + - links + properties: + data: + type: object + description: _Course_ data. + required: + - type + - id + properties: + type: + type: string + description: JSON:API resource type. + enum: + - course + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: '#/components/schemas/LinksResource' + CourseInstanceCollection: + type: object + description: JSON:API collection of _Course instance_ resources. + required: + - data + properties: + jsonapi: + $ref: '#/components/schemas/Jsonapi' + data: + type: array + description: List of _Course instance_ resources. + items: + type: object + required: + - type + - id + - attributes + - relationships + - links + properties: + type: + type: string + description: JSON:API resource type. + enum: + - instance + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + format: uuid + attributes: + type: object + description: JSON:API _attributes_ object. + required: + - lastModified + properties: + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + relationships: + $ref: '#/components/schemas/CourseInstanceRelationships' + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: '#/components/schemas/LinksResource' + links: + type: object + description: JSON:API _links_ object. + properties: + self: + $ref: '#/components/schemas/LinksCollection' + CourseInstanceResource: + type: object + description: JSON:API _Course instance_ resource. + required: + - data + properties: + jsonapi: + $ref: '#/components/schemas/Jsonapi' + data: + type: object + description: _Course instance_ resource data. + required: + - type + - id + - attributes + - relationships + - links + properties: + type: + type: string + description: JSON:API resource type. + enum: + - instance + id: + type: string + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + format: uuid + attributes: + type: object + description: JSON:API _attributes_ object. + required: + - lastModified + properties: + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + relationships: + $ref: '#/components/schemas/CourseInstanceRelationships' + links: + type: object + description: JSON:API _links_ object. + required: + - self + properties: + self: + $ref: '#/components/schemas/LinksResource' links: type: object description: JSON:API _links_ object. From 86976066be7ced7588808ad9bd3fc2e6751e1e9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 18:08:57 +0200 Subject: [PATCH 18/23] Adds Course inherited properties to Instance --- .../schemas/CourseDataExtendedProperties.yaml | 2 +- .../schemas/CourseDataProperties.yaml | 2 +- .../schemas/CourseInstanceData.yaml | 11 ++-- .../schemas/CourseInstanceDataProperties.yaml | 33 ++++++++++ public/v2/openapi.yaml | 66 +++++++++++++++++-- 5 files changed, 101 insertions(+), 13 deletions(-) create mode 100644 openapi/v2/components/schemas/CourseInstanceDataProperties.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index a305d95..966eb98 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -9,7 +9,7 @@ code: minItems: 1 description: Human readable code identifying the Course. ects: - type: integer + type: float minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index db4eb8b..491d880 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -9,7 +9,7 @@ code: minItems: 1 description: Human readable code identifying the Course. ects: - type: integer + type: float minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. diff --git a/openapi/v2/components/schemas/CourseInstanceData.yaml b/openapi/v2/components/schemas/CourseInstanceData.yaml index 36bc312..4cc5b73 100644 --- a/openapi/v2/components/schemas/CourseInstanceData.yaml +++ b/openapi/v2/components/schemas/CourseInstanceData.yaml @@ -7,19 +7,16 @@ id: description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. # format: uuid - format: uuid attributes: type: object description: JSON:API _attributes_ object. required: + - startDate + - endDate + - ects - lastModified properties: - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + $ref: ./CourseInstanceDataProperties.yaml relationships: $ref: ./CourseInstanceRelationships.yaml links: diff --git a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml new file mode 100644 index 0000000..a9eca02 --- /dev/null +++ b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml @@ -0,0 +1,33 @@ +startDate: + type: string + format: date + description: | + The first date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +endDate: + type: string + format: date + description: | + The last date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +ects: + type: float + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the Course. +elmAssessmentType: + $ref: ./fields/ElmAssessmentType.yaml +elmLearningActivityType: + $ref: ./fields/ElmLearningActivityType.yaml +elmLearningOpportunityType: + $ref: ./fields/ElmLearningOpportunityTypeCourse.yaml +elmModeOfLearning: + $ref: ./fields/ElmModeOfLearningAndAssessment.yaml +languageOfInstruction: + $ref: ./fields/LanguageOfInstruction.yaml +lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 6bc8ffc..aa7447e 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2699,7 +2699,7 @@ components: minItems: 1 description: Human readable code identifying the Course. ects: - type: integer + type: float minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. @@ -2859,7 +2859,7 @@ components: minItems: 1 description: Human readable code identifying the Course. ects: - type: integer + type: float minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. @@ -3077,13 +3077,42 @@ components: id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. - format: uuid attributes: type: object description: JSON:API _attributes_ object. required: + - startDate + - endDate + - ects - lastModified properties: + startDate: + type: string + format: date + description: | + The first date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + endDate: + type: string + format: date + description: | + The last date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + ects: + type: float + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the Course. + elmAssessmentType: + $ref: '#/components/schemas/ElmAssessmentType' + elmLearningActivityType: + $ref: '#/components/schemas/ElmLearningActivityType' + elmLearningOpportunityType: + $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' + elmModeOfLearning: + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' lastModified: type: string format: date-time @@ -3132,13 +3161,42 @@ components: id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. - format: uuid attributes: type: object description: JSON:API _attributes_ object. required: + - startDate + - endDate + - ects - lastModified properties: + startDate: + type: string + format: date + description: | + The first date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + endDate: + type: string + format: date + description: | + The last date in which the Course instance was offered, formatted as + [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + ects: + type: float + minimum: 0 + description: | + Number of ECTS credits awarded to the learner upon completing the Course. + elmAssessmentType: + $ref: '#/components/schemas/ElmAssessmentType' + elmLearningActivityType: + $ref: '#/components/schemas/ElmLearningActivityType' + elmLearningOpportunityType: + $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' + elmModeOfLearning: + $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' lastModified: type: string format: date-time From 54b690147571b4273b8745fa58bef1281930ea90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Tue, 9 Sep 2025 19:45:58 +0200 Subject: [PATCH 19/23] More elements of CourseInstance --- .../responses/CourseInstanceResource.yaml | 17 +++++++ .../schemas/CourseInstanceData.yaml | 1 + .../schemas/CourseInstanceDataProperties.yaml | 5 ++ .../schemas/fields/AcademicTermId.yaml | 16 +++++++ public/v2/openapi.yaml | 46 +++++++++++++++++++ 5 files changed, 85 insertions(+) create mode 100644 openapi/v2/components/schemas/fields/AcademicTermId.yaml diff --git a/openapi/v2/components/responses/CourseInstanceResource.yaml b/openapi/v2/components/responses/CourseInstanceResource.yaml index ceda378..222610b 100644 --- a/openapi/v2/components/responses/CourseInstanceResource.yaml +++ b/openapi/v2/components/responses/CourseInstanceResource.yaml @@ -8,6 +8,23 @@ 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: diff --git a/openapi/v2/components/schemas/CourseInstanceData.yaml b/openapi/v2/components/schemas/CourseInstanceData.yaml index 4cc5b73..4879ca1 100644 --- a/openapi/v2/components/schemas/CourseInstanceData.yaml +++ b/openapi/v2/components/schemas/CourseInstanceData.yaml @@ -13,6 +13,7 @@ attributes: required: - startDate - endDate + - academicTermId - ects - lastModified properties: diff --git a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml index a9eca02..c4eb3b6 100644 --- a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml @@ -10,6 +10,8 @@ endDate: description: | The last date in which the Course instance was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +academicTermId: + $ref: ./fields/AcademicTermId.yaml ects: type: float minimum: 0 @@ -23,6 +25,9 @@ elmLearningOpportunityType: $ref: ./fields/ElmLearningOpportunityTypeCourse.yaml elmModeOfLearning: $ref: ./fields/ElmModeOfLearningAndAssessment.yaml +engagementHours: + type: float + description: Total number of engagement hours during the entire Instance. languageOfInstruction: $ref: ./fields/LanguageOfInstruction.yaml lastModified: diff --git a/openapi/v2/components/schemas/fields/AcademicTermId.yaml b/openapi/v2/components/schemas/fields/AcademicTermId.yaml new file mode 100644 index 0000000..d66aa9b --- /dev/null +++ b/openapi/v2/components/schemas/fields/AcademicTermId.yaml @@ -0,0 +1,16 @@ + type: string + description: | + The academic term ID, as defined by [Erasmus Without Paper](#), + combines the exact academic year with the (generic) academic term as seen + at the Course level. + + **Usage** + + - The exact academic year component is described as `yearStart/yearEnd`; + - Wherever the academic year begins and ends in different calendar years, + the values of `yearStart` and `yearEnd` will be consecutive: `2025/2026`; + - Wherever the academic year begins and ends in the same calendar year, + the values of `yearStart` and `yearEnd` will be the same: `2026/2026`; + - The (generic) academic term component is taken from the [Course](); + - The resulting format is `YYYY/YYYY-t/T` i.e. `2025/2026-1/2` means the + **first** (1) **semester** (2) of the academic year **2025/2026**. diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index aa7447e..4a517fe 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1401,6 +1401,23 @@ paths: 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: @@ -3011,6 +3028,23 @@ components: properties: self: $ref: '#/components/schemas/LinksResource' + AcademicTermId: + type: string + description: | + The academic term ID, as defined by [Erasmus Without Paper](#), + combines the exact academic year with the (generic) academic term as seen + at the Course level. + + **Usage** + + - The exact academic year component is described as `yearStart/yearEnd`; + - Wherever the academic year begins and ends in different calendar years, + the values of `yearStart` and `yearEnd` will be consecutive: `2025/2026`; + - Wherever the academic year begins and ends in the same calendar year, + the values of `yearStart` and `yearEnd` will be the same: `2026/2026`; + - The (generic) academic term component is taken from the [Course](); + - The resulting format is `YYYY/YYYY-t/T` i.e. `2025/2026-1/2` means the + **first** (1) **semester** (2) of the academic year **2025/2026**. CourseInstanceRelationships: type: object description: | @@ -3083,6 +3117,7 @@ components: required: - startDate - endDate + - academicTermId - ects - lastModified properties: @@ -3098,6 +3133,8 @@ components: description: | The last date in which the Course instance was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + academicTermId: + $ref: '#/components/schemas/AcademicTermId' ects: type: float minimum: 0 @@ -3111,6 +3148,9 @@ components: $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' elmModeOfLearning: $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + engagementHours: + type: float + description: Total number of engagement hours during the entire Instance. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' lastModified: @@ -3167,6 +3207,7 @@ components: required: - startDate - endDate + - academicTermId - ects - lastModified properties: @@ -3182,6 +3223,8 @@ components: description: | The last date in which the Course instance was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + academicTermId: + $ref: '#/components/schemas/AcademicTermId' ects: type: float minimum: 0 @@ -3195,6 +3238,9 @@ components: $ref: '#/components/schemas/ElmLearningOpportunityTypeCourse' elmModeOfLearning: $ref: '#/components/schemas/ElmModeOfLearningAndAssessment' + engagementHours: + type: float + description: Total number of engagement hours during the entire Instance. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' lastModified: From 7a78dc5b7e231a32ae8ae5267d743e1582c0ee31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Wed, 10 Sep 2025 11:03:16 +0200 Subject: [PATCH 20/23] Language of instruction is always required --- openapi/v2/components/schemas/CourseData.yaml | 1 + .../schemas/CourseDataExtended.yaml | 1 + .../schemas/CourseDataExtendedProperties.yaml | 4 +- .../schemas/CourseDataProperties.yaml | 4 +- .../schemas/CourseInstanceData.yaml | 1 + .../schemas/CourseInstanceDataProperties.yaml | 4 +- .../v2/components/schemas/ProgrammeData.yaml | 1 + .../schemas/ProgrammeDataProperties.yaml | 4 +- public/v2/openapi.yaml | 76 ++++++++++--------- 9 files changed, 53 insertions(+), 43 deletions(-) diff --git a/openapi/v2/components/schemas/CourseData.yaml b/openapi/v2/components/schemas/CourseData.yaml index 0cdbd61..b85d928 100644 --- a/openapi/v2/components/schemas/CourseData.yaml +++ b/openapi/v2/components/schemas/CourseData.yaml @@ -14,6 +14,7 @@ attributes: - title - code - ects + - languageOfInstruction - lastModified properties: $ref: ./CourseDataProperties.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtended.yaml b/openapi/v2/components/schemas/CourseDataExtended.yaml index a793b6b..0091245 100644 --- a/openapi/v2/components/schemas/CourseDataExtended.yaml +++ b/openapi/v2/components/schemas/CourseDataExtended.yaml @@ -14,6 +14,7 @@ attributes: - title - code - ects + - languageOfInstruction - lastModified properties: $ref: ./CourseDataExtendedProperties.yaml diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index 966eb98..14aab3c 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -13,6 +13,8 @@ ects: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. +languageOfInstruction: + $ref: ./fields/LanguageOfInstruction.yaml academicTerm: type: array description: | @@ -59,8 +61,6 @@ iscedCode: type: string minLength: 2 maxLength: 4 -languageOfInstruction: - $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index 491d880..cce6168 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -13,6 +13,8 @@ ects: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. +languageOfInstruction: + $ref: ./fields/LanguageOfInstruction.yaml academicTerm: type: array description: | @@ -59,8 +61,6 @@ iscedCode: type: string minLength: 2 maxLength: 4 -languageOfInstruction: - $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 diff --git a/openapi/v2/components/schemas/CourseInstanceData.yaml b/openapi/v2/components/schemas/CourseInstanceData.yaml index 4879ca1..6098fc8 100644 --- a/openapi/v2/components/schemas/CourseInstanceData.yaml +++ b/openapi/v2/components/schemas/CourseInstanceData.yaml @@ -15,6 +15,7 @@ attributes: - endDate - academicTermId - ects + - languageOfInstruction - lastModified properties: $ref: ./CourseInstanceDataProperties.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml index c4eb3b6..6e95203 100644 --- a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml @@ -17,6 +17,8 @@ ects: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. +languageOfInstruction: + $ref: ./fields/LanguageOfInstruction.yaml elmAssessmentType: $ref: ./fields/ElmAssessmentType.yaml elmLearningActivityType: @@ -28,8 +30,6 @@ elmModeOfLearning: engagementHours: type: float description: Total number of engagement hours during the entire Instance. -languageOfInstruction: - $ref: ./fields/LanguageOfInstruction.yaml lastModified: type: string format: date-time diff --git a/openapi/v2/components/schemas/ProgrammeData.yaml b/openapi/v2/components/schemas/ProgrammeData.yaml index 8b64142..7722c40 100644 --- a/openapi/v2/components/schemas/ProgrammeData.yaml +++ b/openapi/v2/components/schemas/ProgrammeData.yaml @@ -15,6 +15,7 @@ attributes: - code - ects - eqfLevelProvided + - languageOfInstruction - lastModified properties: $ref: ./ProgrammeDataProperties.yaml diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index 792adeb..e357697 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -14,6 +14,8 @@ ects: description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: $ref: ./fields/EqfLevelProvided.yaml +languageOfInstruction: + $ref: ./fields/LanguageOfInstruction.yaml abbreviation: type: array description: Abbbreviation with optional language code. @@ -48,8 +50,6 @@ iscedCode: type: string minLength: 2 maxLength: 4 -languageOfInstruction: - $ref: ./fields/LanguageOfInstruction.yaml learningOutcomes: type: array minItems: 1 diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 4a517fe..2fc46a1 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -2036,6 +2036,29 @@ components: **References** [European Qualifications Framework - EU Vocabularies](https://op.europa.eu/en/web/eu-vocabularies/concept-scheme/-/resource?uri=http://data.europa.eu/snb/eqf/25831c2) + LanguageOfInstruction: + type: array + minItems: 1 + description: | + IETF BCP 47 language tag. + + Language tags allow to specify languages and their variations on script, + region, etc. + + **Usage** + + - `el` for Greek + - `el-Latn` for Greek in Latin script. + - `el-CY` for Cypriot Greek + - `el-Latn-CY` for Cypriot Greek in Latin script. + + **References** + + - [Current specification](https://www.rfc-editor.org/info/bcp47) + - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) + items: + type: string + minLength: 2 MultilineStringWithOptionalLang: type: object required: @@ -2103,29 +2126,6 @@ components: - 7813801c77 - ed4c557045 - 729f3bed4b - LanguageOfInstruction: - type: array - minItems: 1 - description: | - IETF BCP 47 language tag. - - Language tags allow to specify languages and their variations on script, - region, etc. - - **Usage** - - - `el` for Greek - - `el-Latn` for Greek in Latin script. - - `el-CY` for Cypriot Greek - - `el-Latn-CY` for Cypriot Greek in Latin script. - - **References** - - - [Current specification](https://www.rfc-editor.org/info/bcp47) - - [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - items: - type: string - minLength: 2 ProgrammeLength: type: string pattern: ^\d{1,2}\/\d$ @@ -2181,6 +2181,7 @@ components: - code - ects - eqfLevelProvided + - languageOfInstruction - lastModified properties: title: @@ -2199,6 +2200,8 @@ components: description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: $ref: '#/components/schemas/EqfLevelProvided' + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' abbreviation: type: array description: Abbbreviation with optional language code. @@ -2233,8 +2236,6 @@ components: type: string minLength: 2 maxLength: 4 - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -2315,6 +2316,7 @@ components: - code - ects - eqfLevelProvided + - languageOfInstruction - lastModified properties: title: @@ -2333,6 +2335,8 @@ components: description: Number of ECTS credits required to complete the Programme. eqfLevelProvided: $ref: '#/components/schemas/EqfLevelProvided' + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' abbreviation: type: array description: Abbbreviation with optional language code. @@ -2367,8 +2371,6 @@ components: type: string minLength: 2 maxLength: 4 - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -2703,6 +2705,7 @@ components: - title - code - ects + - languageOfInstruction - lastModified properties: title: @@ -2720,6 +2723,8 @@ components: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' academicTerm: type: array description: | @@ -2766,8 +2771,6 @@ components: type: string minLength: 2 maxLength: 4 - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -2863,6 +2866,7 @@ components: - title - code - ects + - languageOfInstruction - lastModified properties: title: @@ -2880,6 +2884,8 @@ components: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' academicTerm: type: array description: | @@ -2926,8 +2932,6 @@ components: type: string minLength: 2 maxLength: 4 - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' learningOutcomes: type: array minItems: 1 @@ -3119,6 +3123,7 @@ components: - endDate - academicTermId - ects + - languageOfInstruction - lastModified properties: startDate: @@ -3140,6 +3145,8 @@ components: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' elmAssessmentType: $ref: '#/components/schemas/ElmAssessmentType' elmLearningActivityType: @@ -3151,8 +3158,6 @@ components: engagementHours: type: float description: Total number of engagement hours during the entire Instance. - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' lastModified: type: string format: date-time @@ -3209,6 +3214,7 @@ components: - endDate - academicTermId - ects + - languageOfInstruction - lastModified properties: startDate: @@ -3230,6 +3236,8 @@ components: minimum: 0 description: | Number of ECTS credits awarded to the learner upon completing the Course. + languageOfInstruction: + $ref: '#/components/schemas/LanguageOfInstruction' elmAssessmentType: $ref: '#/components/schemas/ElmAssessmentType' elmLearningActivityType: @@ -3241,8 +3249,6 @@ components: engagementHours: type: float description: Total number of engagement hours during the entire Instance. - languageOfInstruction: - $ref: '#/components/schemas/LanguageOfInstruction' lastModified: type: string format: date-time From cca3fdd9dc4333a5f2331446f06df38a57c3adfc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Wed, 10 Sep 2025 11:52:32 +0200 Subject: [PATCH 21/23] Adds grading scheme and result distribution (EWP Courses) --- .../schemas/CourseInstanceDataProperties.yaml | 5 ++ .../v2/components/schemas/GradingScheme.yaml | 17 +++++ .../schemas/ResultDistribution.yaml | 18 +++++ .../fields/ResultDistributionCategory.yaml | 20 ++++++ public/v2/openapi.yaml | 67 +++++++++++++++++++ 5 files changed, 127 insertions(+) create mode 100644 openapi/v2/components/schemas/GradingScheme.yaml create mode 100644 openapi/v2/components/schemas/ResultDistribution.yaml create mode 100644 openapi/v2/components/schemas/fields/ResultDistributionCategory.yaml diff --git a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml index 6e95203..233d98d 100644 --- a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml @@ -30,6 +30,11 @@ elmModeOfLearning: engagementHours: type: float description: Total number of engagement hours during the entire Instance. + minimum: 0 +gradingScheme: + $ref: './GradingScheme.yaml' +resultDistribution: + $ref: ./ResultDistribution.yaml lastModified: type: string format: date-time diff --git a/openapi/v2/components/schemas/GradingScheme.yaml b/openapi/v2/components/schemas/GradingScheme.yaml new file mode 100644 index 0000000..645f7a7 --- /dev/null +++ b/openapi/v2/components/schemas/GradingScheme.yaml @@ -0,0 +1,17 @@ +type: object +description: | + Grading scheme used at the Institution. +required: + - label +properties: + label: + type: array + description: Human readable label of the grading scheme with optional + language code. + items: + $ref: ./fields/StringWithOptionalLang.yaml + description: + type: array + description: Description of the grading scheme with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/ResultDistribution.yaml b/openapi/v2/components/schemas/ResultDistribution.yaml new file mode 100644 index 0000000..72f2e0d --- /dev/null +++ b/openapi/v2/components/schemas/ResultDistribution.yaml @@ -0,0 +1,18 @@ +type: object +description: | + _Optional. Describes a histogram of results achieved by all the students of + this course instance (including the ones who have failed the course). Note + that labels of the histogram are not integers, e.g. they may contain ranges + (like "10-20", or "more than 150")._ +properties: + category: + type: array + minItems: 1 + items: + $ref: ./fields/ResultDistributionCategory.yaml + description: + type: array + description: | + Additional description of the histogram with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml diff --git a/openapi/v2/components/schemas/fields/ResultDistributionCategory.yaml b/openapi/v2/components/schemas/fields/ResultDistributionCategory.yaml new file mode 100644 index 0000000..4a96bde --- /dev/null +++ b/openapi/v2/components/schemas/fields/ResultDistributionCategory.yaml @@ -0,0 +1,20 @@ +type: object +description: | + _This describes a single range within the histogram._ +required: + - label + - count +properties: + label: + type: string + minLength: 1 + description: | + _The label of the histogram range. Should correspond to the grading scheme + which have been used. E.g. "C", or "20-30". If possible, the label + should be understandable in any language. If not, you should try to use + English._ + count: + type: integer + minimum: 0 + description: | + _The number of students whose grades fall within that category._ diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 2fc46a1..5f37d50 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -3049,6 +3049,63 @@ components: - The (generic) academic term component is taken from the [Course](); - The resulting format is `YYYY/YYYY-t/T` i.e. `2025/2026-1/2` means the **first** (1) **semester** (2) of the academic year **2025/2026**. + GradingScheme: + type: object + description: | + Grading scheme used at the Institution. + required: + - label + properties: + label: + type: array + description: Human readable label of the grading scheme with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' + description: + type: array + description: Description of the grading scheme with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + ResultDistributionCategory: + type: object + description: | + _This describes a single range within the histogram._ + required: + - label + - count + properties: + label: + type: string + minLength: 1 + description: | + _The label of the histogram range. Should correspond to the grading scheme + which have been used. E.g. "C", or "20-30". If possible, the label + should be understandable in any language. If not, you should try to use + English._ + count: + type: integer + minimum: 0 + description: | + _The number of students whose grades fall within that category._ + ResultDistribution: + type: object + description: | + _Optional. Describes a histogram of results achieved by all the students of + this course instance (including the ones who have failed the course). Note + that labels of the histogram are not integers, e.g. they may contain ranges + (like "10-20", or "more than 150")._ + properties: + category: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/ResultDistributionCategory' + description: + type: array + description: | + Additional description of the histogram with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' CourseInstanceRelationships: type: object description: | @@ -3158,6 +3215,11 @@ components: engagementHours: type: float description: Total number of engagement hours during the entire Instance. + minimum: 0 + gradingScheme: + $ref: '#/components/schemas/GradingScheme' + resultDistribution: + $ref: '#/components/schemas/ResultDistribution' lastModified: type: string format: date-time @@ -3249,6 +3311,11 @@ components: engagementHours: type: float description: Total number of engagement hours during the entire Instance. + minimum: 0 + gradingScheme: + $ref: '#/components/schemas/GradingScheme' + resultDistribution: + $ref: '#/components/schemas/ResultDistribution' lastModified: type: string format: date-time From b12edf71978224a98364486c400ba866eecb4d61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Wed, 10 Sep 2025 15:29:26 +0200 Subject: [PATCH 22/23] Path review, HTTP headers --- openapi/occapi_v2.yaml | 13 +- .../links/LinksInstitutionCollection.yaml | 2 +- .../schemas/links/LinksOunitCollection.yaml | 2 +- openapi/v2/info-description.md | 2 +- openapi/v2/paths/README.md | 12 +- openapi/v2/paths/course.yaml | 8 +- openapi/v2/paths/course@{id}-instance.yaml | 8 +- openapi/v2/paths/course@{id}.yaml | 8 +- openapi/v2/paths/echo.yaml | 54 ------- openapi/v2/paths/hei.yaml | 8 +- openapi/v2/paths/hei@{heiId}.yaml | 8 +- openapi/v2/paths/instance@{id}.yaml | 10 +- openapi/v2/paths/ounit.yaml | 13 +- openapi/v2/paths/ounit@{id}-course.yaml | 8 +- openapi/v2/paths/ounit@{id}-programme.yaml | 8 +- openapi/v2/paths/ounit@{id}.yaml | 8 +- openapi/v2/paths/path-item-with-examples.yaml | 43 ----- openapi/v2/paths/path-item.yaml | 34 ---- openapi/v2/paths/programme.yaml | 8 +- openapi/v2/paths/programme@{id}-course.yaml | 8 +- openapi/v2/paths/programme@{id}.yaml | 8 +- openapi/v2/paths/root.yaml | 8 +- openapi/v2/paths/users@{username}.yaml | 81 ---------- public/v2/openapi.yaml | 148 ++++++++++-------- templates/index.html | 2 +- 25 files changed, 161 insertions(+), 351 deletions(-) delete mode 100644 openapi/v2/paths/echo.yaml delete mode 100644 openapi/v2/paths/path-item-with-examples.yaml delete mode 100644 openapi/v2/paths/path-item.yaml delete mode 100644 openapi/v2/paths/users@{username}.yaml diff --git a/openapi/occapi_v2.yaml b/openapi/occapi_v2.yaml index 9e20bfb..adbbab5 100644 --- a/openapi/occapi_v2.yaml +++ b/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,9 +13,6 @@ 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 server description: Information about the server. @@ -30,8 +27,12 @@ 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) diff --git a/openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml b/openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml index b76405f..efa3ec9 100644 --- a/openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml +++ b/openapi/v2/components/schemas/links/LinksInstitutionCollection.yaml @@ -1,6 +1,6 @@ type: object description: | - Hypermedia link to the _Institution_ collection covered with this server. + Hypermedia link to the _Institution_ collection covered by this server. required: - href properties: diff --git a/openapi/v2/components/schemas/links/LinksOunitCollection.yaml b/openapi/v2/components/schemas/links/LinksOunitCollection.yaml index 37a9bbf..5c9faa4 100644 --- a/openapi/v2/components/schemas/links/LinksOunitCollection.yaml +++ b/openapi/v2/components/schemas/links/LinksOunitCollection.yaml @@ -1,6 +1,6 @@ type: object description: | - Hypermedia link to the _Organizational Unit_ collection associated with this + Hypermedia link to the _Organisational Unit_ collection associated with this resource. required: - href diff --git a/openapi/v2/info-description.md b/openapi/v2/info-description.md index 93deb67..1fe06dd 100644 --- a/openapi/v2/info-description.md +++ b/openapi/v2/info-description.md @@ -1,3 +1,3 @@ # Current status -This version (`v2@dev`) of the OCCAPI specification is a **work in progress** and reflects the discussions within the community, which are documented in the [GitHub issue queue](https://github.com/EuropeanUniversityFoundation/occapi-openapi/issues). +This version (`v2@alpha`) of the OCCAPI specification is a **work in progress** and reflects the discussions within the community, which are documented in the [GitHub issue queue](https://github.com/EuropeanUniversityFoundation/occapi-openapi/issues). diff --git a/openapi/v2/paths/README.md b/openapi/v2/paths/README.md index 0449659..02e3995 100644 --- a/openapi/v2/paths/README.md +++ b/openapi/v2/paths/README.md @@ -9,9 +9,9 @@ It may help you to adopt some conventions: * path parameter (e.g. `{example}`) * file-per-path or file-per-operation -There are different benefits and drawbacks to each decision. +There are different benefits and drawbacks to each decision. -You can adopt any organization you wish. We have some tips for organizing paths based on common practices. +You can adopt any organisation you wish. We have some tips for organizing paths based on common practices. ## Each path in a separate file @@ -39,9 +39,9 @@ In addition, Redocly recommends placing path parameters within `{}` curly braces ## Each operation in a separate file -You may also place each operation in a separate file. +You may also place each operation in a separate file. -In this case, if you want all paths at the top-level, you can concatenate the http method to the path name. Similar to the above option, you can +In this case, if you want all paths at the top-level, you can concatenate the http method to the path name. Similar to the above option, you can ### Files at top-level of `paths` @@ -90,7 +90,7 @@ paths: #### Drawbacks -If you have a lot of nested folders, it may be confusing to reference your schemas. +If you have a lot of nested folders, it may be confusing to reference your schemas. Example ``` @@ -98,7 +98,7 @@ file: /paths/customers/{id}/timeline/{messageId}/get.yaml # excerpt of file headers: - Rate-Limit-Remaining: + Rate-Limit-Remaining: $ref: ../../../../../components/headers/Rate-Limit-Remaining.yaml ``` diff --git a/openapi/v2/paths/course.yaml b/openapi/v2/paths/course.yaml index f88c605..5dbb00a 100644 --- a/openapi/v2/paths/course.yaml +++ b/openapi/v2/paths/course.yaml @@ -16,11 +16,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/course@{id}-instance.yaml b/openapi/v2/paths/course@{id}-instance.yaml index 31fb189..b6b4e00 100644 --- a/openapi/v2/paths/course@{id}-instance.yaml +++ b/openapi/v2/paths/course@{id}-instance.yaml @@ -23,11 +23,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/course@{id}.yaml b/openapi/v2/paths/course@{id}.yaml index 8be1bb6..81d4e77 100644 --- a/openapi/v2/paths/course@{id}.yaml +++ b/openapi/v2/paths/course@{id}.yaml @@ -26,11 +26,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/echo.yaml b/openapi/v2/paths/echo.yaml deleted file mode 100644 index d8e9c8c..0000000 --- a/openapi/v2/paths/echo.yaml +++ /dev/null @@ -1,54 +0,0 @@ -post: - tags: - - Echo - summary: Echo test - description: Receive the exact message you've sent - operationId: echo - security: - - api_key: [] - - basic_auth: [] - responses: - '200': - description: OK - headers: - X-Rate-Limit: - description: calls per hour allowed by the user - schema: - type: integer - format: int32 - X-Expires-After: - $ref: ../components/headers/ExpiresAfter.yaml - content: - application/json: - schema: - type: string - examples: - response: - value: Hello world! - application/xml: - schema: - type: string - text/csv: - schema: - type: string - '400': - description: Unauthorized - requestBody: - content: - application/json: - schema: - type: string - example: Hello world! - application/xml: - schema: - type: string - example: Hello world! - description: Echo payload - required: true - x-codeSamples: - - lang: "C#" - source: - $ref: "../code_samples/csharp/echo/post.cs" - - lang: PHP - source: - $ref: ../code_samples/PHP/echo/post.php diff --git a/openapi/v2/paths/hei.yaml b/openapi/v2/paths/hei.yaml index d799db1..8d05781 100644 --- a/openapi/v2/paths/hei.yaml +++ b/openapi/v2/paths/hei.yaml @@ -14,11 +14,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/hei@{heiId}.yaml b/openapi/v2/paths/hei@{heiId}.yaml index 97dff35..41be78f 100644 --- a/openapi/v2/paths/hei@{heiId}.yaml +++ b/openapi/v2/paths/hei@{heiId}.yaml @@ -23,11 +23,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/instance@{id}.yaml b/openapi/v2/paths/instance@{id}.yaml index bfef15d..be458fe 100644 --- a/openapi/v2/paths/instance@{id}.yaml +++ b/openapi/v2/paths/instance@{id}.yaml @@ -3,7 +3,7 @@ get: - Course instance summary: GET /hei/{heiId}/instance/{id} description: | - This endpoint exposes extended information about a _Course instance_. + This endpoint exposes information about a _Course instance_. operationId: getCourseInstanceByUuid parameters: - name: heiId @@ -24,11 +24,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/ounit.yaml b/openapi/v2/paths/ounit.yaml index 93d38c7..393acff 100644 --- a/openapi/v2/paths/ounit.yaml +++ b/openapi/v2/paths/ounit.yaml @@ -5,8 +5,9 @@ get: description: | This endpoint lists all _Organisational Units_ in an _Institution_. - Implementation is optional but **recommended** since exposing collections by - _Organisational Unit_ can help avoid large HTTP responses. + Implementation is optional but **recommended** since exposing collections of + _Programmes_ or _Courses_ filtered by _Organisational Unit_ can help avoid + large HTTP responses. operationId: getOunits parameters: - name: heiId @@ -19,11 +20,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/ounit@{id}-course.yaml b/openapi/v2/paths/ounit@{id}-course.yaml index 79efb10..58f97e3 100644 --- a/openapi/v2/paths/ounit@{id}-course.yaml +++ b/openapi/v2/paths/ounit@{id}-course.yaml @@ -23,11 +23,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/ounit@{id}-programme.yaml b/openapi/v2/paths/ounit@{id}-programme.yaml index 3df2ba0..c01acb3 100644 --- a/openapi/v2/paths/ounit@{id}-programme.yaml +++ b/openapi/v2/paths/ounit@{id}-programme.yaml @@ -23,11 +23,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/ounit@{id}.yaml b/openapi/v2/paths/ounit@{id}.yaml index 18f1e1c..f7505f7 100644 --- a/openapi/v2/paths/ounit@{id}.yaml +++ b/openapi/v2/paths/ounit@{id}.yaml @@ -27,11 +27,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/path-item-with-examples.yaml b/openapi/v2/paths/path-item-with-examples.yaml deleted file mode 100644 index 46b511f..0000000 --- a/openapi/v2/paths/path-item-with-examples.yaml +++ /dev/null @@ -1,43 +0,0 @@ -post: - tags: - - Tag - summary: Operation summary with examples - description: | - Operation description **markdown**. - operationId: postPathItemWithExamples - security: - - api_key: [] - - basic_auth: [] - requestBody: - content: - application/json: - schema: - $ref: ../components/schemas/Schema.yaml - examples: - mapName: - summary: My first example - description: My first example's description. - value: - stringProperty: tada - mapNameDoesNotShowInDocsUnlessSummaryIsNotProvided: - value: - stringProperty: checkmark - description: requestBody description - required: true - responses: - '200': - description: OK - headers: - X-Rate-Limit: - description: calls per hour allowed by the user - schema: - type: integer - format: int32 - X-Expires-After: - $ref: ../components/headers/ExpiresAfter.yaml - content: - application/json: - schema: - $ref: ../components/schemas/Schema.yaml - '400': - $ref: ../components/responses/Problem.yaml diff --git a/openapi/v2/paths/path-item.yaml b/openapi/v2/paths/path-item.yaml deleted file mode 100644 index 92ebaa9..0000000 --- a/openapi/v2/paths/path-item.yaml +++ /dev/null @@ -1,34 +0,0 @@ -post: - tags: - - Tag - summary: Operation summary - description: | - Operation description **Markdown**. - operationId: operationId - security: - - api_key: [] - - basic_auth: [] - requestBody: - content: - application/json: - schema: - $ref: ../components/schemas/Schema.yaml - description: requestBody description - required: true - responses: - '200': - description: OK - headers: - X-Rate-Limit: - description: Calls per hour allowed by the user. - schema: - type: integer - format: int32 - X-Expires-After: - $ref: ../components/headers/ExpiresAfter.yaml - content: - application/json: - schema: - $ref: ../components/schemas/Schema.yaml - '400': - $ref: ../components/responses/Problem.yaml diff --git a/openapi/v2/paths/programme.yaml b/openapi/v2/paths/programme.yaml index 8848c01..6d53363 100644 --- a/openapi/v2/paths/programme.yaml +++ b/openapi/v2/paths/programme.yaml @@ -16,11 +16,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/programme@{id}-course.yaml b/openapi/v2/paths/programme@{id}-course.yaml index d899567..42ff2ff 100644 --- a/openapi/v2/paths/programme@{id}-course.yaml +++ b/openapi/v2/paths/programme@{id}-course.yaml @@ -23,11 +23,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/programme@{id}.yaml b/openapi/v2/paths/programme@{id}.yaml index 84d6c5a..bbcded3 100644 --- a/openapi/v2/paths/programme@{id}.yaml +++ b/openapi/v2/paths/programme@{id}.yaml @@ -24,11 +24,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/root.yaml b/openapi/v2/paths/root.yaml index a8507cf..bead2f8 100644 --- a/openapi/v2/paths/root.yaml +++ b/openapi/v2/paths/root.yaml @@ -8,11 +8,11 @@ get: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: ['application/vnd.api+json'] content: application/vnd.api+json: schema: diff --git a/openapi/v2/paths/users@{username}.yaml b/openapi/v2/paths/users@{username}.yaml deleted file mode 100644 index 5271dc4..0000000 --- a/openapi/v2/paths/users@{username}.yaml +++ /dev/null @@ -1,81 +0,0 @@ -parameters: - - name: pretty_print - in: query - description: Pretty print response - schema: - type: boolean -get: - tags: - - User - summary: Get user by user name - description: | - Some description of the operation. - You can use `Markdown` here. - operationId: getUserByName - parameters: - - name: username - in: path - description: The name that needs to be fetched - required: true - schema: - type: string - - name: with_email - in: query - description: Filter users without email - schema: - type: boolean - security: - - main_auth: - - 'read:users' - - api_key: [] - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: ../components/schemas/User.yaml - example: - username: user1 - email: user@example.com - '403': - description: Forbidden - $ref: ../components/responses/Problem.yaml - '404': - description: User not found - $ref: ../components/responses/Problem.yaml -put: - tags: - - User - summary: Updated user - description: This can only be done by the logged in user. - operationId: updateUser - parameters: - - name: username - in: path - description: The name that needs to be updated - required: true - schema: - type: string - security: - - main_auth: - - 'write:users' - requestBody: - content: - application/json: - schema: - $ref: ../components/schemas/User.yaml - application/xml: - schema: - $ref: ../components/schemas/User.yaml - description: Updated user object - required: true - responses: - '200': - description: OK - '400': - description: Invalid user supplied - $ref: ../components/responses/Problem.yaml - '404': - description: User not found - $ref: ../components/responses/Problem.yaml diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 5f37d50..27b665c 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.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: @@ -11,7 +11,7 @@ info: description: | # Current status - This version (`v2@dev`) of the OCCAPI specification is a **work in progress** and reflects the discussions within the community, which are documented in the [GitHub issue queue](https://github.com/EuropeanUniversityFoundation/occapi-openapi/issues). + This version (`v2@alpha`) of the OCCAPI specification is a **work in progress** and reflects the discussions within the community, which are documented in the [GitHub issue queue](https://github.com/EuropeanUniversityFoundation/occapi-openapi/issues). servers: - url: /occapi/v2 description: Sandbox server (example data) @@ -29,7 +29,12 @@ 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. + 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. paths: /: get: @@ -42,11 +47,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -110,11 +116,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -194,11 +201,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -260,8 +268,9 @@ paths: description: | This endpoint lists all _Organisational Units_ in an _Institution_. - Implementation is optional but **recommended** since exposing collections by - _Organisational Unit_ can help avoid large HTTP responses. + Implementation is optional but **recommended** since exposing collections of + _Programmes_ or _Courses_ filtered by _Organisational Unit_ can help avoid + large HTTP responses. operationId: getOunits parameters: - name: heiId @@ -274,11 +283,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -361,11 +371,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -437,11 +448,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -544,11 +556,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -652,11 +665,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -752,11 +766,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -880,11 +895,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -1008,11 +1024,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -1139,11 +1156,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -1303,11 +1321,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -1360,7 +1379,7 @@ paths: - Course instance summary: GET /hei/{heiId}/instance/{id} description: | - This endpoint exposes extended information about a _Course instance_. + This endpoint exposes information about a _Course instance_. operationId: getCourseInstanceByUuid parameters: - name: heiId @@ -1381,11 +1400,12 @@ paths: '200': description: OK headers: - X-Rate-Limit: - description: calls per hour allowed by the user. + Content-Type: + description: HTTP Content-Type representation header. schema: - type: integer - format: int32 + type: string + enum: + - application/vnd.api+json content: application/vnd.api+json: schema: @@ -1541,7 +1561,7 @@ components: LinksInstitutionCollection: type: object description: | - Hypermedia link to the _Institution_ collection covered with this server. + Hypermedia link to the _Institution_ collection covered by this server. required: - href properties: @@ -1659,7 +1679,7 @@ components: LinksOunitCollection: type: object description: | - Hypermedia link to the _Organizational Unit_ collection associated with this + Hypermedia link to the _Organisational Unit_ collection associated with this resource. required: - href diff --git a/templates/index.html b/templates/index.html index 6042553..04ab42a 100644 --- a/templates/index.html +++ b/templates/index.html @@ -35,7 +35,7 @@ background-color: green; } .latest { - background-color: darkred; + background-color: orangered; } From 251fbd29c94e6166233f7efad70dad30341882c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Sim=C3=B5es?= Date: Wed, 10 Sep 2025 15:47:23 +0200 Subject: [PATCH 23/23] Consistent field order; ready for first alpha #34 --- .../schemas/CourseDataExtendedProperties.yaml | 90 +++--- .../schemas/CourseDataProperties.yaml | 36 +-- .../schemas/CourseInstanceDataProperties.yaml | 12 +- .../components/schemas/InstitutionData.yaml | 12 +- openapi/v2/components/schemas/OunitData.yaml | 16 +- .../schemas/ProgrammeDataProperties.yaml | 34 +-- public/v2/openapi.yaml | 274 +++++++++--------- 7 files changed, 237 insertions(+), 237 deletions(-) diff --git a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml index 14aab3c..7b4af05 100644 --- a/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataExtendedProperties.yaml @@ -15,6 +15,24 @@ ects: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: ./fields/LanguageOfInstruction.yaml +lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml academicTerm: type: array description: | @@ -31,10 +49,27 @@ academicTerm: items: type: string pattern: '^[1-9]\/[1/9]$' -description: +assessmentMethod: type: array - minItems: 1 - description: Description with optional language code. + description: | + Assessment method with optional language code. + + **Note:** It is preferable to use `elmAssessmentType` instead. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +bibliography: + type: array + description: Bibliography with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +courseAvailability: + type: array + description: Course availability with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +courseContent: + type: array + description: Course content with optional language code. items: $ref: ./fields/MultilineStringWithOptionalLang.yaml elmAssessmentType: @@ -61,14 +96,13 @@ iscedCode: type: string minLength: 2 maxLength: 4 -learningOutcomes: +localClassification: + $ref: ./fields/LocalClassification.yaml +prerequisites: type: array - minItems: 1 - description: Learning outcomes with optional language code. + description: Prerequisites with optional language code. items: $ref: ./fields/MultilineStringWithOptionalLang.yaml -localClassification: - $ref: ./fields/LocalClassification.yaml restrictedToLocalStudents: type: boolean description: | @@ -79,31 +113,6 @@ restrictedToAllianceStudents: description: | Return `true` when enrollment in the Course is restricted to students enrolled at a partner Institution in the same University Alliance. -url: - type: array - description: External URL with optional language code. - items: - $ref: ./fields/HttpWithOptionalLang.yaml -bibliography: - type: array - description: Bibliography with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml -courseContent: - type: array - description: Course content with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml -prerequisites: - type: array - description: Prerequisites with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml -courseAvailability: - type: array - description: Course availability with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml teachingMethod: type: array description: | @@ -112,20 +121,11 @@ teachingMethod: **Note:** It is preferable to use `elmLearningActivityType` instead. items: $ref: ./fields/MultilineStringWithOptionalLang.yaml -assessmentMethod: +url: type: array - description: | - Assessment method with optional language code. - - **Note:** It is preferable to use `elmAssessmentType` instead. + description: External URL with optional language code. items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml -lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + $ref: ./fields/HttpWithOptionalLang.yaml deprecated: type: boolean description: | diff --git a/openapi/v2/components/schemas/CourseDataProperties.yaml b/openapi/v2/components/schemas/CourseDataProperties.yaml index cce6168..4090fb6 100644 --- a/openapi/v2/components/schemas/CourseDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseDataProperties.yaml @@ -15,6 +15,24 @@ ects: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: ./fields/LanguageOfInstruction.yaml +lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). +description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml academicTerm: type: array description: | @@ -31,12 +49,6 @@ academicTerm: items: type: string pattern: '^[1-9]\/[1/9]$' -description: - type: array - minItems: 1 - description: Description with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml elmAssessmentType: $ref: ./fields/ElmAssessmentType.yaml elmLearningActivityType: @@ -61,12 +73,6 @@ iscedCode: type: string minLength: 2 maxLength: 4 -learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml localClassification: $ref: ./fields/LocalClassification.yaml restrictedToLocalStudents: @@ -84,12 +90,6 @@ url: description: External URL with optional language code. items: $ref: ./fields/HttpWithOptionalLang.yaml -lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). deprecated: type: boolean description: | diff --git a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml index 233d98d..ab9521c 100644 --- a/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml +++ b/openapi/v2/components/schemas/CourseInstanceDataProperties.yaml @@ -19,6 +19,12 @@ ects: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: ./fields/LanguageOfInstruction.yaml +lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). elmAssessmentType: $ref: ./fields/ElmAssessmentType.yaml elmLearningActivityType: @@ -35,9 +41,3 @@ gradingScheme: $ref: './GradingScheme.yaml' resultDistribution: $ref: ./ResultDistribution.yaml -lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/openapi/v2/components/schemas/InstitutionData.yaml b/openapi/v2/components/schemas/InstitutionData.yaml index 1d033c5..4b87624 100644 --- a/openapi/v2/components/schemas/InstitutionData.yaml +++ b/openapi/v2/components/schemas/InstitutionData.yaml @@ -24,6 +24,12 @@ attributes: type: string description: The SCHAC code of the Institution. format: hostname + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language @@ -35,12 +41,6 @@ attributes: description: External URL with optional language code. items: $ref: ./fields/HttpWithOptionalLang.yaml - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/OunitData.yaml b/openapi/v2/components/schemas/OunitData.yaml index 2c32988..49d74e2 100644 --- a/openapi/v2/components/schemas/OunitData.yaml +++ b/openapi/v2/components/schemas/OunitData.yaml @@ -5,7 +5,7 @@ type: id: type: string description: JSON:API resource ID; UUID v4 is **recommended**, but any value - that is unique within the Institution may be used. + that is unique within the Institution may be used. **Must** match `ounitId`. # format: uuid format: uuid attributes: @@ -23,7 +23,13 @@ attributes: $ref: ./fields/StringWithOptionalLang.yaml ounitId: type: string - description: Unique identifier within the Institution. Can be a UUID. + description: Unique identifier within the Institution. + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language @@ -38,12 +44,6 @@ attributes: description: External URL with optional language code. items: $ref: ./fields/HttpWithOptionalLang.yaml - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. diff --git a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml index e357697..0e8ecca 100644 --- a/openapi/v2/components/schemas/ProgrammeDataProperties.yaml +++ b/openapi/v2/components/schemas/ProgrammeDataProperties.yaml @@ -16,17 +16,29 @@ eqfLevelProvided: $ref: ./fields/EqfLevelProvided.yaml languageOfInstruction: $ref: ./fields/LanguageOfInstruction.yaml -abbreviation: - type: array - description: Abbbreviation with optional language code. - items: - $ref: ./fields/StringWithOptionalLang.yaml +lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). description: type: array minItems: 1 description: Description with optional language code. items: $ref: ./fields/MultilineStringWithOptionalLang.yaml +learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: ./fields/MultilineStringWithOptionalLang.yaml +abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: ./fields/StringWithOptionalLang.yaml elmLearningOpportunityType: $ref: ./fields/ElmLearningOpportunityTypeProgramme.yaml elmLearningScheduleType: @@ -50,12 +62,6 @@ iscedCode: type: string minLength: 2 maxLength: 4 -learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: ./fields/MultilineStringWithOptionalLang.yaml length: $ref: ./fields/ProgrammeLength.yaml url: @@ -75,9 +81,3 @@ validUntil: description: | The last date in which the Programme was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). -lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). diff --git a/public/v2/openapi.yaml b/public/v2/openapi.yaml index 27b665c..a6100a1 100644 --- a/public/v2/openapi.yaml +++ b/public/v2/openapi.yaml @@ -1762,6 +1762,12 @@ components: type: string description: The SCHAC code of the Institution. format: hostname + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language code. @@ -1772,12 +1778,6 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1842,6 +1842,12 @@ components: type: string description: The SCHAC code of the Institution. format: hostname + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language code. @@ -1852,12 +1858,6 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1904,7 +1904,7 @@ components: - ounit id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. **Must** match `ounitId`. format: uuid attributes: type: object @@ -1921,7 +1921,13 @@ components: $ref: '#/components/schemas/StringWithOptionalLang' ounitId: type: string - description: Unique identifier within the Institution. Can be a UUID. + description: Unique identifier within the Institution. + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language code. @@ -1935,12 +1941,6 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -1983,7 +1983,7 @@ components: - ounit id: type: string - description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. + description: JSON:API resource ID; UUID v4 is **recommended**, but any value that is unique within the Institution may be used. **Must** match `ounitId`. format: uuid attributes: type: object @@ -2000,7 +2000,13 @@ components: $ref: '#/components/schemas/StringWithOptionalLang' ounitId: type: string - description: Unique identifier within the Institution. Can be a UUID. + description: Unique identifier within the Institution. + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). abbreviation: type: array description: Most widely recognized abbbreviation with optional language code. @@ -2014,12 +2020,6 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2222,17 +2222,29 @@ components: $ref: '#/components/schemas/EqfLevelProvided' languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' - abbreviation: - type: array - description: Abbbreviation with optional language code. - items: - $ref: '#/components/schemas/StringWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). description: type: array minItems: 1 description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' elmLearningOpportunityType: $ref: '#/components/schemas/ElmLearningOpportunityTypeProgramme' elmLearningScheduleType: @@ -2256,12 +2268,6 @@ components: type: string minLength: 2 maxLength: 4 - learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: $ref: '#/components/schemas/ProgrammeLength' url: @@ -2281,12 +2287,6 @@ components: description: | The last date in which the Programme was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2357,17 +2357,29 @@ components: $ref: '#/components/schemas/EqfLevelProvided' languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' - abbreviation: - type: array - description: Abbbreviation with optional language code. - items: - $ref: '#/components/schemas/StringWithOptionalLang' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). description: type: array minItems: 1 description: Description with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + abbreviation: + type: array + description: Abbbreviation with optional language code. + items: + $ref: '#/components/schemas/StringWithOptionalLang' elmLearningOpportunityType: $ref: '#/components/schemas/ElmLearningOpportunityTypeProgramme' elmLearningScheduleType: @@ -2391,12 +2403,6 @@ components: type: string minLength: 2 maxLength: 4 - learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' length: $ref: '#/components/schemas/ProgrammeLength' url: @@ -2416,12 +2422,6 @@ components: description: | The last date in which the Programme was offered, formatted as [YYYY-MM-DD](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). links: type: object description: JSON:API _links_ object. @@ -2745,6 +2745,24 @@ components: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' academicTerm: type: array description: | @@ -2761,12 +2779,6 @@ components: items: type: string pattern: ^[1-9]\/[1/9]$ - description: - type: array - minItems: 1 - description: Description with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' elmAssessmentType: $ref: '#/components/schemas/ElmAssessmentType' elmLearningActivityType: @@ -2791,12 +2803,6 @@ components: type: string minLength: 2 maxLength: 4 - learningOutcomes: - type: array - minItems: 1 - description: Learning outcomes with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' localClassification: $ref: '#/components/schemas/LocalClassification' restrictedToLocalStudents: @@ -2814,12 +2820,6 @@ components: description: External URL with optional language code. items: $ref: '#/components/schemas/HttpWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). deprecated: type: boolean description: | @@ -2906,6 +2906,24 @@ components: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + description: + type: array + minItems: 1 + description: Description with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + learningOutcomes: + type: array + minItems: 1 + description: Learning outcomes with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' academicTerm: type: array description: | @@ -2922,10 +2940,27 @@ components: items: type: string pattern: ^[1-9]\/[1/9]$ - description: + assessmentMethod: type: array - minItems: 1 - description: Description with optional language code. + description: | + Assessment method with optional language code. + + **Note:** It is preferable to use `elmAssessmentType` instead. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + bibliography: + type: array + description: Bibliography with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + courseAvailability: + type: array + description: Course availability with optional language code. + items: + $ref: '#/components/schemas/MultilineStringWithOptionalLang' + courseContent: + type: array + description: Course content with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' elmAssessmentType: @@ -2952,14 +2987,13 @@ components: type: string minLength: 2 maxLength: 4 - learningOutcomes: + localClassification: + $ref: '#/components/schemas/LocalClassification' + prerequisites: type: array - minItems: 1 - description: Learning outcomes with optional language code. + description: Prerequisites with optional language code. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' - localClassification: - $ref: '#/components/schemas/LocalClassification' restrictedToLocalStudents: type: boolean description: | @@ -2970,31 +3004,6 @@ components: description: | Return `true` when enrollment in the Course is restricted to students enrolled at a partner Institution in the same University Alliance. - url: - type: array - description: External URL with optional language code. - items: - $ref: '#/components/schemas/HttpWithOptionalLang' - bibliography: - type: array - description: Bibliography with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - courseContent: - type: array - description: Course content with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - prerequisites: - type: array - description: Prerequisites with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - courseAvailability: - type: array - description: Course availability with optional language code. - items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' teachingMethod: type: array description: | @@ -3003,20 +3012,11 @@ components: **Note:** It is preferable to use `elmLearningActivityType` instead. items: $ref: '#/components/schemas/MultilineStringWithOptionalLang' - assessmentMethod: + url: type: array - description: | - Assessment method with optional language code. - - **Note:** It is preferable to use `elmAssessmentType` instead. + description: External URL with optional language code. items: - $ref: '#/components/schemas/MultilineStringWithOptionalLang' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). + $ref: '#/components/schemas/HttpWithOptionalLang' deprecated: type: boolean description: | @@ -3224,6 +3224,12 @@ components: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). elmAssessmentType: $ref: '#/components/schemas/ElmAssessmentType' elmLearningActivityType: @@ -3240,12 +3246,6 @@ components: $ref: '#/components/schemas/GradingScheme' resultDistribution: $ref: '#/components/schemas/ResultDistribution' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). relationships: $ref: '#/components/schemas/CourseInstanceRelationships' links: @@ -3320,6 +3320,12 @@ components: Number of ECTS credits awarded to the learner upon completing the Course. languageOfInstruction: $ref: '#/components/schemas/LanguageOfInstruction' + lastModified: + type: string + format: date-time + description: | + Time of latest change to this resource, formatted as + [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). elmAssessmentType: $ref: '#/components/schemas/ElmAssessmentType' elmLearningActivityType: @@ -3336,12 +3342,6 @@ components: $ref: '#/components/schemas/GradingScheme' resultDistribution: $ref: '#/components/schemas/ResultDistribution' - lastModified: - type: string - format: date-time - description: | - Time of latest change to this resource, formatted as - [YYYY-MM-DDThh:mm:ssZ](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). relationships: $ref: '#/components/schemas/CourseInstanceRelationships' links: