Merge pull request #75 from ehn-dcc-development/release/2.12.0

Release 2.12.0 with v1.15 of guidelines document + technical and documentation improvements

.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: Tests
+
+on: 
+  - push
+  - pull_request
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install general dependencies
+      run: sudo apt-get install jq nodejs
+    - name: Install node dependencies
+      run: npm install
+    - name: Validate the valuesets
+      run: npm test

.gitignore

@@ -0,0 +1 @@
+node_modules/

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Change log
 
+## Release 2.12.0
+
+* Update to eHN guidelines document for value sets, version 1.15:
+    1. New vaccine entry added: “Bimervax“, ID'd as “EU/1/22/1709”.
+       This new entry does not have an explicit version because it's an EMA-approved vaccine, and EMA has their own versioning system.
+    2. Addition of a marketing authorization holder or manufacturer “Hipra Human Health S.L.” for the new vaccine entry, ID'd as “ORG-100036914”.
+    3. Addition of a vaccine encoding instruction corresponding to the combination of sub items 1 and 2.
+
+  The [guidelines document v1.15 has been adopted and published](https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-value-sets_en.pdf) through the [eHealth network page on the EU DCC](https://ec.europa.eu/health/ehealth/covid-19_en).
+
+* Implement validation of valuesets against the EU DCC Schema.
+  * Implement a Git hook that runs that validation prior to committing.
+
+* Improve the documentation - [README](./README.md) an [VERSIONING](./VERSIONING.md) - in various ways.
+  * Fix not-yet-renamed links to repos which formerly were prefixed with "`ehn-dcc-`".
+
+
 ## Release 2.11.0
 
 * Add a value set that encodes Annex A of the guidelines document, including its derivation.
@@ -13,6 +30,8 @@
     2. The derivation script for this value set has been updated to check for deprecated ACT/SCT codes.
        (It also reports the correct row numbers now.)
 
+  The [guidelines document v1.14 has been adopted and published](https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-value-sets_en.pdf) through the [eHealth network page on the EU DCC](https://ec.europa.eu/health/ehealth/covid-19_en).
+
 
 ## Release 2.10.0
 
@@ -140,5 +159,5 @@ The [guidelines document v1.5 has been adopted and published](https://ec.europa.
 
 ## Prior releases
 
-Change log for releases before 2.3.0 are available through the [releases page](https://github.com/ehn-dcc-development/ehn-dcc-valuesets/releases).
+Change log for releases before 2.3.0 are available through the [releases page](https://github.com/ehn-dcc-development/eu-dcc-valuesets/releases).
 

README.md

@@ -1,10 +1,83 @@
-# EU eHealthNetwork Digitial COVID Certificate value sets
+# EU eHealthNetwork Digital COVID Certificate valuesets
 
-This repository contains the value sets referenced by the EU Digital COVID Certificate (DCC) [JSON Schema](https://github.com/ehn-dcc-development/ehn-dcc-schema).
+Welcome to the EU-DCC valuesets repository. This repository contains a snapshot of the valuesets referenced by the EU Digital COVID Certificate (DCC) [JSON Schema](https://github.com/ehn-dcc-development/eu-dcc-schema). The most up-to-date version of the valuesets are distributed on the [EU DGC Gateway](https://github.com/eu-digital-green-certificates/dgc-gateway).
 
-Release: 2.11.0
+All of the file found in this repository should be considered for reference usage only. The current official release is published on the EU DGC Gateway. As access to this gateway is only available to Member States please refer to your own Member State to for access to those files.
 
-Note that these value sets do not form a core part of the [JSON Schema](https://github.com/ehn-dcc-development/ehn-dcc-schema) but are referenced by it. These value sets can (and should) be regularly updated and distributed from the main Digital COVID Certificate Gateway (DCCG), under clear versioning and release management.
+Release: 2.12.0
 
-This repository has been created to provide a home for the value sets (for development purposes only) which have up until then (2021-06-16) been living a somewhat orphaned life in the [JSON Schema](https://github.com/ehn-dcc-development/ehn-dcc-schema) repository.
 
+## Overview
+
+Here is an overview of the files available in this repository. The column "managed on" describes the place where the value-set is managed. In most cases that is in this GitHub repository. Those valuesets will usually be very close to the versions provided on the EU DGC Gateway. As they are managed in the GitHub they will always be the newest version, just bear in mind that the version provided by the EU DGC Gateway is always considered the **current** version.
+
+**Reminder: the valuesets on the EU DGC Gateway are leading, the valuesets here are provided for purposes of development and as part of our release process.**
+
+File name 							 | Description														 | Managed on
+------------------------------------ | ----------------------------------------------------------------- | ------------
+country-2-codes.json				 | List of ISO-3166-2 country codes used for issuers 				 | Github
+disease-targeted-agent.json			 | List of diseases/targeted agent (i.e. covid)						 | Github
+test-manf-example.json				 | Example of the test manufacturers value-set						 | DGC Gateway
+test-result.json					 | List of supported test results (i.e. detected, not detected..)	 | Github
+test-type.json						 | List of supported test types (i.e. PCR, rapid-antigen..)			 | Github
+vaccine-encoding-instructions.json	 | List of valid encodings (manufacturer + medical product)			 | Github
+vaccine-mah-manf.json				 | List of vaccine manufacturers									 | Github
+vaccine-medical-product.json		 | List of the vaccines												 | Github
+vaccine-prophylaxis.json			 | List of the vaccine/prophylaxis types							 | Github
+
+The JSON Schema definition for the structure used for all of the above valuesets can be found in [DCC.ValueSets.schema.json](DCC.ValueSets.schema.json)
+
+Finally, we have [changelog](CHANGELOG.md), [license](LICENSE.md) and [versioning](VERSIONING.md) files and, of course, this [readme](README.md).
+
+
+## Working with the valuesets
+
+### NOTE FOR WINDOWS USERS
+
+The scripts we used are bash-based, if you're a Windows users you will either need to use the amazing [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) or use another [Cygwin](https://www.cygwin.com/).
+
+Although the maintainers are primarily Windows developers the internet - and the git eco-system - are POSIX focused. With the fantastic support for POSIX on modern Windows we have decided to focus on a POSIX-based workflow.
+
+### Pre-reqs
+
+[Node.js 18.14.2 or above ](https://nodejs.org/en/)
+NPM 9.5.0 (included with Node.js)
+
+### Configuring git hooks
+
+This repository makes use of the `pre-commit` git hook. This executes the schema validation scripts (which are described below).
+
+To enable git hooks you need to tell git to use them, you can do that by running this command from the terminal in the root directory of this project:
+
+	git config core.hooksPath hooks
+
+### Validating schema
+
+First lets ask node to install the dependencies:
+
+	npm install
+
+Then to run the schema validator simply:
+
+	npm test
+
+If there are any validation errors they will be shown on the screen.
+
+## How the schema and validator work
+
+We use [JSON Schema 2020-12](https://json-schema.org/specification.html) to define the schema of the valuesets. For most of the valuesets there is a [shared schema](schemas/DCC.ValueSets.schema.json).
+
+For files which have a different schema - such as `vaccine-encoding-instructions` - the validator supports the definition of a custom schema. By convention these schema files are named `<valueset-file-name>.schema.json` and are stored in `./schema`. So for `vaccine-encoding-instructions.json` the schema `vaccine-encoding-instructions.schema.json` is used.
+
+The validator also checks whether the set of actual valuesets coincides with the set expected by the [EU DCC Schema standard](https://github.com/ehn-dcc-development/eu-dcc-schema/blob/release/1.3.3/DCC.ValueSets.schema.json).
+The exact GitHub reference - being a (release) tag, or branch - is configured through the `EU_DCC_SCHEMA_REF` constant defined in [this config file](./schemas/config.js).
+This constant needs to be updated when a new release of the EU DCC Schema is released, or while being worked on.
+
+The validator code has been written in an imperative style for ease of understanding and [can be found in the schema directory](schemas/validate-valuesets.js).
+
+
+## Governance
+
+The valuesets are owned by the eHealth Network Subgroup on Semantics (SSG). Any requests for additions or changes must be directed to that group. If you or your country are not members of that subgroup then you can raise an issue on this GitHub repository and, if appropriate, we will raise it with the SSG on your behalf.
+
+This repository, as with all of the eHN GitHub repositories, is maintained by a number of volunteers from the eHealth Network Technical IOP Subgroup.

VERSIONING.md

@@ -13,7 +13,7 @@ Each release is identified through a [semver version number](https://semver.org/
 
 Releases are prepared in branches named `release/<release version>`.
 After preparation has finished, a _Pull Request_ (PR) from the release branch into `main` is created on GitHub.
-That can e.g. be done by clicking the “New Pull Request” button on the [branches page](https://github.com/ehn-dcc-development/ehn-dcc-valuesets/branches).
+That can e.g. be done by clicking the “New Pull Request” button on the [branches page](https://github.com/ehn-dcc-development/eu-dcc-valuesets/branches).
 
 Such a PR serves as the trigger a code review for that release.
 That possibly leads to discussion conducted inside the PR page, and further work being committed to that release branch.
@@ -34,6 +34,10 @@ That can be done on the commandline as follows (assuming the `main` branch is cu
     $ git tag <release version>
     $ git push --tags
 
+After this, a release page can be made for that tag, using the [GitHub releases overview](https://github.com/ehn-dcc-development/eu-dcc-valuesets/releases).
+
+After releasing, the European Commission's (EC) representative in the eHN should be notified of the release, so they can notify TSi to update the EU DCC Gateway.
+
 It's advisable to rebase a release branch manually, and check it afterwards, as there's no guarantee that a conflict-free automatic rebase is syntactically, or semantically correct.
 On the commandline, that's (assuming the release branch is currently checked out):
 
@@ -46,11 +50,13 @@ After a manual rebase, the rebased branch has to be force-pushed, using:
 
     $ git push --force
 
-The release branch can be deleted after merging the PR, for the following reasons:
+The release branch _could_ be deleted after merging the PR, for the following reasons:
 
 - A branch is essentially a label on a HEAD commit, and a tag fulfills the labelling function just as well.
 - Having many branches can be confusing.
 
+However, currently (essentially) all release branches are kept.
+
 
 ### Fixing a release
 

annex-A/table.tsv

@@ -37,3 +37,4 @@ Soberana 02	Soberana-02	Finlay-Institute	28531000087107	Also known as FINLAY-FR-
 Soberana Plus	Soberana-Plus	Finlay-Institute	28531000087107	Also known as FINLAY-FR-1A.
 COVID-19 Vaccine Valneva	"EU/1/21/1624"	ORG-100036422	28531000087107	Previously known as VLA2001.
 VidPrevtyn Beta	EU/1/21/1580	ORG-100000788	28531000087107	Previously known as Vidprevtyn.
+Bimervax	EU/1/22/1709	ORG-100036914	28531000087107	Previously known as COVID-19 Vaccine HIPRA

hooks/pre-commit

@@ -0,0 +1,8 @@
+#!/bin/sh
+#
+
+# Ensure npm pre-reqs are installed
+npm install
+
+# Run the NPM tests
+npm test || exit 1