QualityLink Data Source Discovery 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.

3. User Stories

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

3.1. Expose data

As a higher education institution or education provider I want to advertise my data source to a Europe-wide aggregator in a secure way, but without the need for additional action or manual intervention by another organisation.

3.2. Manage data sources

As manager of an aggregator (e.g. the QualityLink consortium) I want to manage trusted sources of data providers whose data should be integrated in the QualityLink platform.

3.3. Access statistics

As a data provider I want to access a dashboard or similar to manage my data sources and get insights/stats on how my data was harvested and processed.

4. Requirements

• The approach should be as flexible and as easy to adopt as possible for HEIs and other data providers.

• The approach should be scalable. Hence, data sources of HEIs need to be discovered automatically and without manual registration or intervention, in line with the policies defined above. (Authoritative sources and other data sources are managed manually, as each case will need to be screened against the applicable policies.)

• Discovery of data from education providers/HEIs should be based on data from the EWP Registry, the EUF HEI API and DEQAR (which includes all HEIs listed in ETER and OrgReg).

5. Manifest File

The location of one or several data files or API endpoints (see Data Exchange spec) is indicated in a simple, standardised “manifest” file published by the data provider.

For authoritative sources and other data sources, the location of the manifest file is managed manually. For higher education institutions the location of the manifest file is auto-discovered as described in the following chapter.

The manifest file can be expressed as [JSON] or [YAML] file. The file must be a single object/mapping with at least a top-level key named sources. An additional meta key can be provided.

5.1. Data sources

sources must be an array/sequence of objects/mapping, each representing a data source of the provider. At least one data source must be specified. The following keys are supported for each source:

Keys marked with an asterisk are required. Additional, data source type-specific keys are specified in [QL-EXCH].

5.2. Additional metadata

The meta key is optional and may be used to specify institutional identifiers. Aggregators may use this for diagnostic purposes or identify changed identifiers.

5.3. JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://data.quality-link.eu/schema/manifest-v1.json",
  "title": "QualityLink manifest file",
  "description": "A manifest file listing data sources on learning opportunities.",
  "type": "object",
  "properties": {
    "sources": {
      "description": "Defines one or more data sources",
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "description": "Type of the data source: string, using the identifier specified in QualityLink Data Exchange Specification",
            "type": "string",
            "enum": [
              "elm",
              "ooapi",
              "edu-api"
            ]
          },
          "path": {
            "description": "File or API root",
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "version": {
            "description": "Version identifier (see data source tyope-specific information)",
            "type": "string"
          },
          "id": {
            "description": "Identifier of the data source",
            "type": "string"
          },
          "name": {
            "description": "Human-readable name or description",
            "type": "string"
          },
          "auth": {
            "description": "Authorisation parameters",
            "type": "object",
            "properties": {
              "type": {
                "description": "Access control strategy required for this data source",
                "type": "string",
                "enum": [
                  "none",
                  "httpsig",
                  "httpheader",
                  "oauth2.0"
                ]
              }
            },
            "required": [
              "type"
            ]
          }
        },
        "required": [
          "type",
          "path"
        ]
      }
    },
    "meta": {
      "description": "Defines metadata about the institution providing the manifest file.",
      "type": "object",
      "properties": {
        "schac": {
          "description": "SCHAC code of the institution covered by the data source(s)",
          "type": "string"
        },
        "eterid": {
          "description": "ETER identifier, as used in the EHESO and OrgReg",
          "type": "string"
        },
        "deqarid": {
          "description": "DEQAR institutional identifier",
          "type": "string"
        },
        "did": {
          "description": "Decentralised Identifier (DID) used by the institution",
          "type": "string"
        }
      }
    }
  },
  "required": [
    "sources"
  ]
}

6. Discovery Mechanism

The specification offers two options how to auto-discover a manifest file.

higher education institutions may use either option. Aggregators must support both options.

6.1. DNS TXT Record

The higher education institution can create a DNS TXT record of the following format:

v=qldiscover1; m=[URL]

The URL must point to a manifest file.

6.2. Well-known URL

The higher education institution can place a manifest file at a URL of the form:

• [DOMAIN]/.well-known/quality-link-manifest

• [DOMAIN]/.well-known/quality-link-manifest.json

• [DOMAIN]/.well-known/quality-link-manifest.yaml

These locations are tried in this order and the first file found is used.

6.3. Domain Search Order

An aggregator should consider a combined list of higher education institutions appearing in one or more of the following datasets:

• EUF HEI API

• EWP Registry

• eduGAIN (?)

• DEQAR (including institutions from OrgReg and ETER)

For each higher education institution, the aggregator attempts to fetch a manifest file from a known domain in this order:

1. domain/host name that is the higher education institution’s SCHAC code (if available)

2. host name of the higher education institution’s website (as indicated in OrgReg or DEQAR)

3. website host name stripped off www or similar generic first component

4. highest level registrable domain name determined from the website host name (i.e. public suffix \+ one further DNS component)

For each domain, both of the above mechanisms are tried.

Once a manifest file has successfully been obtained, no further domains or mechanisms are tried.

7. Security Considerations

The location and content of manifest files are not sensitive information. Access to data sources themselves can be protected as described in [QL-EXCH].

8. Examples

{
    "meta": {
        "schac": "example.ac.at",
        "eterid": "AT4711",
        "deqarid": "DEQARINST0815"
    },
    "sources": [
        {
            "type": "elm",
            "path": "https://data.example.org/feed/elm.ttl",
            "version": "3.2",
            "auth": {
                "type": "none"
            }
        },
        {
            "type": "ooapi",
            "path": "https://data.example.org/ooapi/v5/",
            "version": "5",
            "auth": {
                "type": "httpheader"
            },
            "id": "eua-courses-virt",
            "name": "Courses offered on the Alliance's virtual campus"
        },
        {
            "type": "edu-api",
            "path": "https://edu-api.example.org/",
            "version": "1.0",
            "auth": {
                "type": "oauth2.0",
                "token_endpoint": "https://auth.example.org/oauth2/get_token"
            },
            "name": "Experimental data source using Edu-API"
        }
    ]
}

meta:
  schac: example.ac.at
  eterid: AT4711
  deqarid: DEQARINST0815
sources:
  - type: elm
    path: https://data.example.org/feed/elm.ttl
    version: "3.2"
    auth:
      type: none
  - type: ooapi
    path: https://data.example.org/ooapi/v5/
    version: "5"
    auth:
      type: httpheader
    id: eua-courses-virt
    name: "Courses offered on the Alliance's virtual campus"
  - type: edu-api
    path: https://edu-api.example.org/
    version: "1.0"
    auth:
      type: oauth2.0
      token_endpoint: https://auth.example.org/oauth2/get_token
    name: "Experimental data source using Edu-API"