Transition from v1 metadata schema to v2

1 Introduction
- 1.1 Quick overview of changes in v2 compared to v1
2 Process
- 2.1 Updating existing metadata
- 2.2 Updating FDP metadata
- 2.3 SPARQL solution
  - 2.3.1 Scenario 1: RDF-typed URLs without the right properties
3 Questions?

Introduction

This is a documentation regarding migrating from the Health-RI v1 model, to Health-RI v2 model (as available in preparation for the v2-rc1 release on github at the time of writing).

Users are advised to upgrade to version 1.7.4 of the FDP server and 1.17.1 of the FDP client to make full use of all functionalities with v2 of the metdata

Quick overview of changes in v2 compared to v1

The new version (v2) of the Health-RI model is somewhat more extensive than v1. While it introduces only a limited number of new mandatory properties, there are many new recommended properties a data holder can use to describe their data.

In this sheet available on Github we state for each property whether it is identical to v1, adapted compared to v1, or completely new (column I). In below table you find an overview of the number of mandatory and recommended properties in both versions.

Mandatory classes				Remaining classes

Mandatory classes				Remaining classes
Class		v1	v2	Class		v1	v2
Dataset	Mandatory	10	10	Distribution	Mandatory	4	5
Dataset	Recommended	5	37	Distribution	Recommended	2	17
Catalog	Mandatory	3	5	Dataset Series	Mandatory	10	2
Catalog	Recommended	2	15	Dataset Series	Recommended	3	10
Agent	Mandatory	2	4	Data Service	Mandatory	2	10
Agent	Recommended	0	4	Data Service	Recommended	2	12
Kind	Mandatory	2	2
Kind	Recommended	1	1
Total	Mandatory	17	21
Total	Recommended	8	57

New mandatory properties of the mandatory classes (linked to the source of the constraint, if applicable):

Dataset:
- access rights
- keyword
- applicable legislation (for health datasets filled with the ELI of the EHDS).
Three properties are no longer mandatory properties of the Dataset class: release date, modification date, licence (licence is a property of the Distribution class).
Catalog:
- contact point
- dataset.
Agent:
- email
- homepage.

The Data Service class has 10 mandatory properties in v2 (compared to 2 in v1) due to the model being compliant to DCAT-AP NL, where many properties of Data Service are mandatory that are not in DCAT-AP 3.

Process

If the FDP instance does not contain any metadata yet, the v1 shapes can simply be overwritten with the v2 shapes. In the FairDataPointShapes folder there are pre-processed shape files available, ready for import into the FDP.

The shapes have been tested with the FDP Rerefence Implementation, version 1.16. Due to bugs in version 1.17 and higher the shapes have not been tested on other versions.

You can import the shapes manually or via a script. For details please refer to4B_2 Metadata entry into an FDP .

Updating existing metadata

If the FDP instance contains metadata conforming to the v1 shapes already, there are steps that need to be taken to ensure the instance metadata is properly migrated. Due to the introduction of new constraints or modification of existing constraints, there can be scenarios where the FDP reference implementation will cause an error when trying to edit existing metadata.

Updating FDP metadata

Since the FDP relies on the specifications of the dcat:DataService class, the metadata of your FDP instance also has to be updated based on changes in that class in v2 compared to v1.
Note this will only have to be done once when you update the FDP to the new schema.
Specifically, this means providing metadata for all the mandatory fields of the dcat:DataService class in v2. Compared to v1 (two mandatory properties), in v2 10 mandatory properties have to be filled. In the table below you can find which properties those are and some guidance on how to fill.

property label	property URI	Usage note for FDP metadata

property label	property URI	Usage note for FDP metadata
access rights	`dct:accessRights`	Use a value from the EU access rights vocabulary to indicate whether this FDP has public, non-public or restricted access.
contact point	`dcat:contactPoint`	Uses `vcard:Kind` supporting class. Indicate the contact point who can provide more information about your instance of the FDP, for example the IT department responsible for running it. Preferably provide general contact details instead of contact details of an individual person.
description	`dct:description`	Describe this instance of the FDP, for example whether it is the central FDP from a node, how it is organized/structured or what kind of metadata it contains.
end point description	`dcat:endpointDescription`	Provides technical documentation that explains how to access and interact with the FDP’s endpoint.
end point URL	`dcat:endPointURL`	(Also mandatory in v1). This is the URL of this FDP; it should already be filled in.
identifier	`dct:identifier`	Automatically generated.
licence	`dct:license`	A licence is automatically filled by the reference impl. Verify if this is correct, otherwise change to a correct licence.
publisher	`dct:publisher`	Uses `foaf:Agent` supporting class. The agent responsible for publishing this FDP. Preferably provide general details instead of details of an individual person.
theme	`dcat:theme`	Use a value from the EU theme vocabulary to indicate the theme of the FDP. Most probably this takes the value of http://publications.europa.eu/resource/authority/data-theme/HEAL (Health), but it is possible to provide multiple themes, if applicable to this FDP.
title	`dct:title`	(Also mandatory in v1). The title of this FDP.

SPARQL solution

This solution requires a deployment with access to the underlying triplestore.

Scenario 1: RDF-typed URLs without the right properties

There can be situations where certain URLs have received a type (such as vcard:Kind for mailto: urls). This is caused by the client handling certain nested structures incorrectly. The example query below can be adapted to the actual scenario by filling in the right values, and can then be executed by a user with write access to the underlying triplestore.

PREFIX vcard: <http://www.w3.org/2006/vcard/ns#>
DELETE DATA {
  GRAPH <http://fdp.example.com/dataset/1477479e-f372-4bf9-b12c-79ed00f48c26> {
    <mailto:email@example.com> a vcard:Kind .
  }
}

The values that need to be updated:

Line 3, the GRAPH identifier should match the name that that contains the offending values.
Line 4, the mailto: URL should match the offending subject value.
Note: the offending subject is not always a mailto: URL.
Line 4, the vcard:Kind type should match the offending type value.
Note: the offending type is not always a vcard:Kind.

Questions?

If you have questions about the onboarding process or would like to learn more. Reach out to

onboarding@health-ri.nl

You can also join our walk-in hour to discuss your specific scenario (Agenda | Health-RI ) or use onboarding@health-ri.nl to request assitance.