Merge pull request #155 from ehn-dcc-development/release/1.3.3

Release EU DCC Schema version 1.3.3
ehn-dcc-development · May 26, 2023 · ce3aa13 · ce3aa13
2 parents bfda9aa + a1303c9
commit ce3aa13
Show file tree

Hide file tree

Showing 64 changed files with 758 additions and 81 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -14,4 +14,4 @@ jobs:
     - name: Install AJV
       run: make install-ajv
     - name: Run tests
-      run: make test
+      run: make validate-all
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1 @@
-node_modules
-package-lock.json
-package.json
+/node_modules
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Change log
 
+## Release 1.3.3
+
+* Update the sub schema `DCC.ValueSets.schema.json` for the new valueset `vaccine-encoding-instructions` corresponding to Annex A of (version 1.14 of) [guidelines document](https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-value-sets_en.pdf).
+  * Also synchronize the `description` field of each valueset with v1.14 of the [eHN EU DCC Value Sets Guidelines document](https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-value-sets_en.pdf).
+* Move contents of GitHub Wiki - mainly the [FAQ](wiki/FAQ.md) - to a [`wiki/` folder](wiki/), to use one mode of persisting knowledge.
+* Improve the description of the `person_name` schema definition.
+* Implement a pre-commit Git hook that prevents committing when tests fail, or when the sub schemas haven't been properly merged into the combined schema.
+* Commit NPM artifacts (`package*.json`) to shrinkwrap dependencies' versions.
+
+*Note:* none of these changes modify the effective JSON Schema for the EU DCC in any way.
+They are simply improvements intended to benefit the longevity of this repository and the EU DCC standard.
+
 
 ## Release 1.3.2
 

diff --git a/DCC.Core.Types.schema.json b/DCC.Core.Types.schema.json
@@ -15,7 +15,7 @@
       "maxLength": 80
     },
     "person_name": {
-      "description": "Person name: Surname(s), forename(s) - in that order",
+      "description": "Person name: The person's name consisting at least of a separate standardised surname, or a standardised forename, or both - with standardisation done according to the rules defined in ICAO Doc 9303 Part 3",
       "anyOf": [
         {
           "required": [

diff --git a/DCC.ValueSets.schema.json b/DCC.ValueSets.schema.json
@@ -5,45 +5,50 @@
   "description": "EU Digital Covid Certificate Value Set Data Types",
   "$defs": {
     "disease-agent-targeted": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.1",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.1",
       "type": "string",
       "valueset-uri": "valuesets/disease-agent-targeted.json"
     },
     "vaccine-prophylaxis": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.2",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.2",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-prophylaxis.json"
     },
     "vaccine-medicinal-product": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.3",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.3",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-medicinal-product.json"
     },
     "vaccine-mah-manf": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.4",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.4",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-mah-manf.json"
     },
     "country_vt": {
-      "description": "Country of Vaccination / Test, ISO 3166 alpha-2 where possible",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.6 - Country of Vaccination / Test, ISO 3166 alpha-2 where possible",
       "type": "string",
       "pattern": "[A-Z]{1,10}",
       "valueset-uri": "valuesets/country-2-codes.json"
     },
     "test-manf": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.8",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.8",
       "type": "string",
       "valueset-uri": "valuesets/test-manf.json"
     },
     "test-result": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.9",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.9",
       "type": "string",
       "valueset-uri": "valuesets/test-result.json"
     },
     "test-type": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.7",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.7",
       "type": "string",
       "valueset-uri": "valuesets/test-type.json"
+    },
+    "vaccine-encoding-instructions": {
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Annex A",
+      "type": "string",
+      "valueset-uri": "valuesets/vaccine-encoding-instructions.json"
     }
   }
 }
diff --git a/DCC.combined-schema.json b/DCC.combined-schema.json
@@ -3,7 +3,7 @@
   "$id": "https://id.uvci.eu/DCC.combined-schema.json",
   "title": "EU DCC",
   "description": "EU Digital Covid Certificate",
-  "$comment": "Schema version 1.3.2",
+  "$comment": "Schema version 1.3.3",
   "type": "object",
   "oneOf": [
     {
@@ -41,7 +41,8 @@
         "1.0.0",
         "1.3.0",
         "1.3.1",
-        "1.3.2"
+        "1.3.2",
+        "1.3.3"
       ]
     },
     "nam": {
@@ -100,7 +101,7 @@
       "maxLength": 80
     },
     "person_name": {
-      "description": "Person name: Surname(s), forename(s) - in that order",
+      "description": "Person name: The person's name consisting at least of a separate standardised surname, or a standardised forename, or both - with standardisation done according to the rules defined in ICAO Doc 9303 Part 3",
       "anyOf": [
         {
           "required": [
@@ -324,45 +325,50 @@
       }
     },
     "disease-agent-targeted": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.1",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.1",
       "type": "string",
       "valueset-uri": "valuesets/disease-agent-targeted.json"
     },
     "vaccine-prophylaxis": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.2",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.2",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-prophylaxis.json"
     },
     "vaccine-medicinal-product": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.3",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.3",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-medicinal-product.json"
     },
     "vaccine-mah-manf": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.4",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.4",
       "type": "string",
       "valueset-uri": "valuesets/vaccine-mah-manf.json"
     },
     "country_vt": {
-      "description": "Country of Vaccination / Test, ISO 3166 alpha-2 where possible",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.6 - Country of Vaccination / Test, ISO 3166 alpha-2 where possible",
       "type": "string",
       "pattern": "[A-Z]{1,10}",
       "valueset-uri": "valuesets/country-2-codes.json"
     },
     "test-manf": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.8",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.8",
       "type": "string",
       "valueset-uri": "valuesets/test-manf.json"
     },
     "test-result": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.9",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.9",
       "type": "string",
       "valueset-uri": "valuesets/test-result.json"
     },
     "test-type": {
-      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. version 1.0, 2021-04-16, section 2.7",
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Section 2.7",
       "type": "string",
       "valueset-uri": "valuesets/test-type.json"
+    },
+    "vaccine-encoding-instructions": {
+      "description": "EU eHealthNetwork: Value Sets for Digital Covid Certificates. Version 1.14, 2023-01-25, Annex A",
+      "type": "string",
+      "valueset-uri": "valuesets/vaccine-encoding-instructions.json"
     }
   }
 }
diff --git a/DCC.schema.json b/DCC.schema.json
@@ -3,7 +3,7 @@
   "$id": "https://id.uvci.eu/DCC.schema.json",
   "title": "EU DCC",
   "description": "EU Digital Covid Certificate",
-  "$comment": "Schema version 1.3.2",
+  "$comment": "Schema version 1.3.3",
   "type": "object",
   "oneOf": [
     {
@@ -41,7 +41,8 @@
         "1.0.0",
         "1.3.0",
         "1.3.1",
-        "1.3.2"
+        "1.3.2",
+        "1.3.3"
       ]
     },
     "nam": {

diff --git a/Makefile b/Makefile
@@ -18,14 +18,14 @@ JSON_FILES=	*.json \
 AJV=		./node_modules/.bin/ajv -c ajv-formats --spec=draft2020 --strict=false
 
 
-test:: compile validate-examples check-formatting $(MERGED_SCHEMA)
+# validate all DCC JSON files against the merged schema:
+validate-all:: compile $(MERGED_SCHEMA)
 	$(AJV) test -s $(MERGED_SCHEMA) -d "examples/vaccination/*.json" --valid
 	$(AJV) test -s $(MERGED_SCHEMA) -d "examples/recovery/*.json" --valid
 	$(AJV) test -s $(MERGED_SCHEMA) -d "examples/test/*.json" --valid
+	$(AJV) test -s $(MERGED_SCHEMA) -d "test/valid/*.json" --valid
 	$(AJV) test -s $(MERGED_SCHEMA) -d "test/invalid/*.json" --invalid
 
-combined: $(MERGED_SCHEMA)
-
 compile::
 	@echo "Compiling schemata..."
 	$(AJV) compile -r "DCC.*.schema.json" -s "DCC.schema.json"
@@ -36,21 +36,28 @@ check-formatting::
 		jq . <$$file >$$file.tmp; \
 		if ! cmp $$file $$file.tmp; then \
 			echo "Please reformat $$file"; \
+			rm $$file.tmp; \
+			exit 1; \
+		else \
+			rm $$file.tmp; \
 		fi; \
-		rm $$file.tmp; \
 	done
 
+# validate valid example DCC JSON files against the unmerged schema:
 validate-examples:
 	$(AJV) validate -r "DCC.*.schema.json" -s "DCC.schema.json" -d "examples/vaccination/*.json"
 	$(AJV) validate -r "DCC.*.schema.json" -s "DCC.schema.json" -d "examples/recovery/*.json"
 	$(AJV) validate -r "DCC.*.schema.json" -s "DCC.schema.json" -d "examples/test/*.json"
 
+# validate valid test DCC JSON files against the unmerged schema:
 validate-valid-tests:
 	$(AJV) validate -r "DCC.*.schema.json" -s "DCC.schema.json" -d "test/valid/*.json"
 
+# validate invalid test DCC JSON files against the unmerged schema:
 validate-invalid-tests:
 	$(AJV) test -r "DCC.*.schema.json" -s "DCC.schema.json" -d "test/invalid/*.json" --invalid
 
+# merge the schemata:
 $(MERGED_SCHEMA): $(SCHEMATA)
 	python3 merge.py --id $(MERGED_ID) $(SCHEMATA) | jq . > $@
 	$(AJV) compile -s $@

diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 This repository contains a JSON schema for the EU Digital Covid Certificate.
 
-**Schema version:** 1.3.2
+**Schema version:** 1.3.3
 
-**Release date:** 2022-06-30
+**Release date:** 2023-05-24 (tentative, dependent on eHN Coordinated Actions meeting)
 
 
 ## Introduction
@@ -43,9 +43,10 @@ _Note:_ the first 4, non-combined schema files are always leading.
 
 See https://github.com/ehn-dcc-development/ehn-dcc-valuesets
 
+
 ## Implementation Notes
 
-A list of [Frequently Asked Questions](https://github.com/ehn-dcc-development/ehn-dcc-schema/wiki/FAQ) for implementors can be found in the [repository wiki](https://github.com/ehn-dcc-development/ehn-dcc-schema/wiki).
+A list of Frequently Asked Questions (FAQ) for implementors can be found [here](wiki/FAQ.md).
 
 
 ## Prerequisites
@@ -57,6 +58,7 @@ The Makefile assumes that the following tools are installed, and are available o
 * [Node.js](https://nodejs.org/en/download/): installing Node.js also installs the [NPM package manager](https://www.npmjs.com/) which is used to install a couple of dependencies.
 * [jq](https://stedolan.github.io/jq/)
 
+
 The Makefile also relies on the [`ajv` JSON Schema validator](https://ajv.js.org/), which is installed by the `install-ajv` rule in the Makefile:
 
     $ make install-ajv
@@ -70,10 +72,20 @@ To validate all of the examples:
 
 	make validate-examples
 
-..and all of expected valid tests:
+...and all of expected valid tests:
 
 	make validate-valid-tests
 
-..and all of the expected invalid tests:
+...and all of the expected invalid tests:
 
 	make validate-invalid-tests
+
+
+## Committing: Git hooks
+
+This project uses Git hooks to validate the JSON files and the above test cases.
+To use the hooks, configure Git to use the hooks we provide, as follows:
+
+```
+git config core.hooksPath hooks
+```
diff --git a/examples/recovery/simple.json b/examples/recovery/simple.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/recovery/special-case-birthday-year-month-only.json b/examples/recovery/special-case-birthday-year-month-only.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/recovery/special-case-birthday-year-only.json b/examples/recovery/special-case-birthday-year-only.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/recovery/special-case-only-family-name.json b/examples/recovery/special-case-only-family-name.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES"

diff --git a/examples/recovery/special-case-only-given-name.json b/examples/recovery/special-case-only-given-name.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "gn": "Charles",
     "gnt": "CHARLES"

diff --git a/examples/recovery/transliterated.json b/examples/recovery/transliterated.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "ابو بكر محمد بن زكريا الرازي",
     "fnt": "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",

diff --git a/examples/test/simple-naat.json b/examples/test/simple-naat.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/test/simple-rat.json b/examples/test/simple-rat.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/test/special-case-birthday-year-month-only.json b/examples/test/special-case-birthday-year-month-only.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/test/special-case-birthday-year-only.json b/examples/test/special-case-birthday-year-only.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES",

diff --git a/examples/test/special-case-only-family-name.json b/examples/test/special-case-only-family-name.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "Smith-Jones",
     "fnt": "SMITH<JONES"

diff --git a/examples/test/special-case-only-given-name.json b/examples/test/special-case-only-given-name.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "gn": "Charles",
     "gnt": "CHARLES"

diff --git a/examples/test/transliterated.json b/examples/test/transliterated.json
@@ -1,5 +1,5 @@
 {
-  "ver": "1.3.2",
+  "ver": "1.3.3",
   "nam": {
     "fn": "ابو بكر محمد بن زكريا الرازي",
     "fnt": "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",