QualityLink Data Exchange Specification

1. Introduction

2. Key Concepts

The following key concepts and terminology are used throughout the document, as well as other QualityLink specifications:

learning opportunity

an opportunity to realise a given set of learning outcomes through a learning activity or assessment [ELM]. Offered by a higher education institution or other provider. A learning opportunity can be part of a larger one and contain smaller ones. Specific learning opportunities are courses, modules and programmes.

learning opportunity specification

the general specification of a learning opportunity, i.e. including the learning outcomes and credits. It is usually permanent and does not change from year to year or semester to semester.

learning opportunity instance

the specific offering of a learning opportunity in a specific academic term (e.g. year or semester) and specific setting (e.g. online vs face-to-face, different locations, ...). A single learning opportunity specification will usually be offered in many instances over time.

course

smallest learning opportunity that awards credits (i.e. ECTS) to the learner, either in the context of a study programme or as a self-standing offer. A course can be part of a module or programme.

module

a learning opportunity that is a group or collection of courses. A module may be part of a programme.

micro-credential

a proof of the learning outcomes that a learner has acquired following a short learning experience. These learning outcomes have been assessed against transparent standards. [CR-MC]

programme

collection of learning opportunities. Finalising a study programme usually leads to a degree (e.g. Bachelor degree, Master degree, etc.) or to another type of certificate, e.g. a micro-credential, for a shorter programme. A programme is a "top-level" learning opportunity and has no parent.

joint programme

an integrated curriculum coordinated and offered jointly by different higher education institutions, and leading to double/multiple degrees or a joint degree. [DEQAR]

education provider

any actor that provides degree programmes, micro-credentials or other learning opportunities. This may include higher education institutions as well as other providers, including employers, companies, social partners, NGOs, public authorities and others. [DEQAR]

higher education institution

an entity that has full degree awarding powers at higher education level (i.e. EQF levels 5 to 8; QF-EHEA cycle first to third) recognised by at least one national authority. [DEQAR]

other provider

an entity that provides learning opportunities, but that does not have officially-recognised authority to award degrees or other formally recognised qualifications.

data provider

an entity providing data on learning opportunities. This can be an education provider providing data on its own learning opportunities or another organisation providing data on various education providers.

aggregator

any service that harvests data from different data providers, matches and compiles the data into one single dataset. For example, the aggregator service developed within the QualityLink project.

manifest file

a file listing a data provider’s data sources available for aggregation, as described in [QL-DISCO]

3. User Stories

The following usage scenarios illustrate ways in which this specification might be used or desired features it should enable:

3.1. Feed data

As a higher education institution I want to feed my data into a Europe-wide aggregator easily and flexibly, in order to avoid unnecessary burden.

3.2. Efficient aggregation

As a data aggregator I want to aggregate data from higher education institutions and other data providers efficiently, i.e. avoiding too much overhead or redundant data transfers.

3.3. Access control

As a data provider I want to ensure that only specified aggregators (e.g. the QualityLink one) can harvest my data.

4. Requirements

• Data providers should be able to choose between several widely-used formats in which to provide their data.

• Data providers must be able to implement access control mechanisms so that only the QualityLink aggregator can harvest their data.

• There needs to be a mechanism to indicate whether data has changed since the last harvest/connection.

• The QualityLink aggregator should be able to harvest data from several sources of one data provider, e.g. different faculties or sub-units of a higher education institution

Note: The current version specifies a pull strategy only, where the QualityLink aggregator periodically polls the available data sources. A push option might be realised later.

5. Methods

The following sections outline the available data transport methods and formats, as well as their specific requirements.

A data provider may choose one or several options in which to provide their data.

An aggregator should support all formats described.

None of the formats mandate the use of encrypted connections, i.e. HTTPS, necessarily. Data providers should, however, use HTTPS wherever possible; the use of HTTPS is ensured by providing https:// URIs in the manifest file.

5.1. Static ELM File

Data on learning opportunities described in [ELM] format can be serialised as:

• RDF/XML (application/rdf+xml)

• Turtle (text/turtle)

• JSON-LD (application/ld+json)

The data source must return the correct content type for the serialisation used.

5.1.1. Required Fields

The minimum required fields are defined by a set of [SHACL] constraints, which are based on the [ELM] Application Profile "Learning Opportunities and Qualifcations".

ELM data must comply with the requirements specified by the shape http://data.quality-link.eu/ontology/v1#LearningOpportunity [QL-ONT].

5.1.2. Incremental Transport

Data providers should implement at least one of two options:

• Provide an accurate Last-Modified [RFC9110] header in response to a HTTP HEAD request, indicating when the data was last changed/updated.

• Process the If-Modified-Since header if provided in a HTTP HEAD or GET request, return a 200 (OK) status code (and data in case of GET) only if modifications occured, and a 304 (Not Modified) status code otherwise. [RFC9110]

Aggregators should harvest data sources less frequently if neither of the two options are implemented.

5.1.3. Metadata

Data providers must provide the following metadata in their manifest file for this method:

5.2. OOAPI

Education providers can expose data on their learning opportunities according to the Open Edcuation API specification [OOAPI].

The aggregator may use the following endpoints to acquire data:

• GET /education-specifications

• GET /education-specifications/{educationSpecificationId}

• GET /courses/{courseId}/offerings

• GET /courses/{courseId}/components

• GET /programs/{programId}/offerings

• GET /components/{componentId}/offerings

• GET /offerings/{offeringId}

5.2.1. Required Fields

Per the OOAPI specification, the following fields are required:

• primaryCode

• abbreviation

• name

• description

• teachingLanguage

• level (for courses)

• programType (for programmes)

In addition, the following fields need to be present for the purposes of the QualityLink aggregator in order to align with ELM requirements:

• fieldsOfStudy

• learningOutcomes

• levelOfQualification (programme only)

5.2.2. Incremental Transport

While OOAPI does include the ability to query learning opportunities based on the year/semester in which they are offered, the standard does not include query parameters based on modification dates or similar.

Standard HTTP headers are, however, compatible with OOAPI and data providers should thus implement at least one of two options, at least for the GET /education-specifications endpoint:

• Provide an accurate Last-Modified [RFC9110] header in response to a HTTP HEAD request, indicate when the data was last changed/updated.

• Process the If-Modified-Since [RFC9110] header if provided in a HTTP request and only return data if modifications occured.

5.2.3. Metadata

Data providers must provide the following metadata in their manifest file for this method:

5.3. Edu-API

Education providers can expose data on their learning opportunities using the Edu-API specification [Edu-API], a RESTful API standard maintained by 1EdTech. This method delivers JSON-formatted responses and supports real-time querying of educational data, such as courses and programs, making it suitable for dynamic aggregation scenarios.

The aggregator may use the following endpoints to acquire data (non-exhaustive list, based on Edu-API Core):

• GET /courses - Retrieve a list of courses.

• GET /courses/{courseId} - Retrieve details of a specific course.

• GET /programs - Retrieve a list of programs.

• GET /programs/{programId} - Retrieve details of a specific program.

Additional endpoints (e.g., for offerings or components) may be supported depending on the provider’s implementation.

5.3.1. Required Fields

The Edu-API specification defines a core set of fields for learning opportunities, aligned with its Learning Resource Core profile. At a minimum, data providers must include:

• id: Unique identifier for the learning opportunity.

• title: Name or title of the course or program.

• description: Brief description of the learning opportunity.

• type: Type of learning opportunity (e.g., "Course", "Program").

• primaryCode:

• level:

• gradingScheme:

• teachingLanguage / recordLanguage:

In addition, the fields credits and learningOutcomes are recommended to align with the European Learning Model [ELM] and QualityLink goals. Providers should refer to the Edu-API Learning Resource Core bindings for full details.

5.3.2. Incremental Updates

The [Edu-API] specification includes a dateLastModified property in resource responses (e.g., for courses and programs), indicating the last modification date in ISO 8601 format.

This property enables tracking changes to individual resources and can be combined with the filter parameter on collections like GET /courses or GET /programs to support efficient aggregation, providing patterns for both initial bulk loads and delta updates, data providers and aggregators should follow this choreography where possible:

• Initial or Bulk Load: The aggregator makes a series of "get all" requests (e.g., GET /courses, GET /programs) to retrieve all resources needed, establishing a baseline dataset. The dateLastModified value for each resource should be recorded for subsequent delta updates.

• Delta or True-Up: The aggregator repeats the "get all" requests, ideally using a filter on dateLastModified (e.g., GET /courses?modifiedAfter=2025-03-01T00:00:00Z) to retrieve only resources modified since the last sync. If this filter is not supported, the aggregator must fetch the full collection and compare dateLastModified values locally against the last sync timestamp.

The QualityLink aggregator may use the dateLastModified value from previous responses to determine which resources have changed since the last harvest.

5.3.3. Metadata

Data providers must provide the following metadata in their manifest file for this method:

5.3.4. Authentication with OAuth 2.0

Edu-API mandates the use of OAuth 2.0 for securing API endpoints, ensuring that only authorized aggregators (e.g., the QualityLink aggregator) can access protected data. Data providers must implement OAuth 2.0 as specified below.

5.4. OCCAPI

The aggregator may use the following endpoints to acquire data:

• GET /hei/{heiId}

• GET /hei/{heiId}/course

• GET /hei/{heiId}/course/{courseId}

• GET /hei/{heiId}/ounit

• GET /hei/{heiId}/ounit/{ounitId}

• GET /hei/{heiId}/ounit/{ounitId}/course

• GET /hei/{heiId}/ounit/{ounitId}/programme

• GET /hei/{heiId}/programme

• GET /hei/{heiId}/programme/{programmeId}

• GET /hei/{heiId}/programme/{programmeId}/course

OCCAPI makes use of hypermedia links to indicate which collection endpoints are available, scoped to higher education institution and optionally to organisational units and programme resources.

5.4.1. Required fields

Data required in any resource type:

• type

• id

Data attributes required for higher education institutions and organisational units:

• title

• heiId or ounitId (for higher education institutions and organisational units respectively)

Data attributes required for both programme and course resources:

• title

• code

• description

• ects

• iscedCode

• languageOfInstruction

Data attributes required for programme resources only:

• eqfLevelProvided

• length

Data attributes required for course resources only:

• description

• learningOutcomes

• academicTerm

5.4.2. Metadata

Data providers must provide the following metadata in their manifest file for this method:

5.5. EWP Courses API

Note: similar structure as for OOAPI

6. Access Control

Currently all transport methods operate over HTTP. Hence the following access control strategies can all be used for either method.

A data provider may choose one of the strategies if they wish to control access to their data, but no access control is required.

An aggregator should support all formats described.

The exchange of access credentials or additional data that some of these options might require (e.g. certificates, trusted IPs, or client/secrets) is an out-of-band activity. The details of this are to be agreed between the aggregator and data providers during an onboarding/discovery process; the following sections describe in general terms what out-of-band communication is required.

6.1. Based on IP address

A data provider can limit access to certain ranges of IP addresses. To that end, aggregators should publish the IP address ranges from which their services may contact the exposed methods.

Data providers can omit the auth key from their manifest file or provide the following metadata for this method:

This mechanism does not require out-of-band communication beyond the aggregator publishing its IP address range.

Note: The QualityLink aggregator will publish the IP address range from which it operates.

6.2. HTTP Request Header

The data provider may request that the aggregator include a specific HTTP header in all requests, e.g. a secret token.

Data providers must provide the following metadata under auth in their manifest file for this method:

This mechanism requires out-of-band communication in which the data provider communicates a HTTP header field and the value to include to the aggregator. The modalities need to be specified by the aggregator separately from this specification.

6.3. OAuth 2.0

A data provider may secure their endpoints using OAuth 2.0, requiring the aggregator to authenticate via an access token. This method is the standard authentication mechanism of [Edu-API] (see § 5.3.4 Authentication with OAuth 2.0).

Data providers must implement OAuth 2.0 as follows:

• Grant Type: Support the Client Credentials Grant (per [RFC6749], Section 4.4) for machine-to-machine authentication, suitable for aggregator access without user interaction.

• Token Endpoint: Provide a dedicated OAuth 2.0 token endpoint (e.g., https://provider.example.edu/oauth/token) where the aggregator can obtain an access token.

• Scopes: Define scopes to limit access (e.g. http://purl.1edtech.org/spec/eduapi/v1p0/scope/core.readonly for read-only access to learning opportunity data).

Data providers further should:

• Issue access tokens with a reasonable expiration time (e.g., 1 hour) and support refresh tokens.

• Validate tokens server-side per [RFC6750] (Bearer Token Usage).

An aggregator must support the following:

• Grant Type: Support OAuth 2.0 Client Credentials Grant as a minimum.

• Credentials: Obtain and securely store client credentials (client_id and client_secret) provided by the data provider.

• Access Token: The aggregator must request and include a valid OAuth 2.0 Bearer token in the Authorization header of each request (i.e. Authorization: Bearer <token> per [RFC6750]).

• Handle token expiration and renewal gracefully.

Data providers must provide the following metadata under auth in their manifest file for this method:

This method requires out-of-band communication in which the data provider supplied the aggregator with secret credentials, namely client_id and client_secret to be used when using the mechanism descibred in Section 2.3 of [RFC6749].

6.4. HTTP Signature

A data provider may request that the aggregator authenticates itself by signing all HTTP requests using HTTP Message Signatures according to [RFC9421].

The aggregator must provide a signature that covers the @authority component as well as the following signature parameters (see Section 2.3 of [RFC9421])):

• created: signature creation time (UNIX timestamp)

• expires: expiration time (UNIX timestamp), at most 1 hour after creation time

• alg: the signature algorithm

• keyid: the identifier for the key used (from the list published by the aggregator)

• tag: qualitylink-v1 to identity the purpose

The aggregator must publish the following information in order to allow data providers to verify its signatures:

• A (list of) supported signature algorithm(s) (alg), including only algorithms based on asymmetric cryptography

• One public key per supported signature algorithm, together with a keyid that will be used

A data provider must support one of signature algorithm(s) supported by the aggregator. Unless it supports all algorithms, it needs to select the desired algorithm in the manifest file.

The data provider should handle requests that are authenticated by a verified HTTP Message Signature, i.e. verify against the aggregator’s public key, are applicable to the data provider based on the @authority component and are valid based on the expires parameter. If the data provider receives a request without a HTTP Message Signature, it should return a 401 (Unauthorized) response unless the request could be authenticated through another mechanism. If the request cannot be authenticated, the data provider should return a 403 (Forbidden) response. If the request contains corrupted or invalid Signature or Signature-Input headers, the data provider should return a 400 (Bad Request) response.

Data providers must provide the following metadata under auth in their manifest file for this method:

This mechanism does not require out-of-band communication beyond the aggregator publishing the information mentioned above.

7. Security Considerations

The previous chapter describes how data providers can implement access control to their exposed data. The authors are aware that these mechanisms do not provide perfect security, e.g. IP addresses could be spoofed and HTTP Message Signatures could be replayed for a short amount of time if compromised.

This specification is, however, about exchange of data on learning opportunities, which is generally meant to be public. The authors consider the described options reasonably secure for the purposes of limiting unauthorised harvesting of data.

Data providers should not expose any data through the methods described herein that is not meant to be public, especially no personal data.