matthieutexier / ehn-dcc-schema

Schema for the ehn DCC payload

Digital Covid Certificate Schema

This repository contains a JSON schema for the EU Digital Covid Certificate.

Schema version: 1.3.0 Release date: 2020-06-11

Introduction

The Digital Covid Certificate (DCC) JSON schema is provided as a mechanism for supporting the serialization and deserialization of the DCC payload, initially with focus on generation of a 2D barcode (QR Code).

The schema is intended to support different use cases that EU Member States require. The schema shall also support conformity to the EU legislation regarding what shall present in a certificate to ensure freedom of movement within EU Member States and also to allow interoperability with countries outside of the EU zone.

The schema in conjunction with business rules (which may also be specific to a Member State) shall ensure conformity to the EU legislation, whereby the burden of conformity lies with the business rules and the DCC JSON schema plays a supporting role in allowing the data to be serialized and deserialized in a flexible, yet structured, manner.

Schema files

The main schema file is:

• DCC.schema.json

With the definitions in:

• DCC.Core.Types.schema.json
• DCC.Types.schema.json
• DCC.ValueSets.schema.json

For easy testing, they are combined in:

• DCC.combined-schema.json

The rule labeled as $(MERGED_SCHEMA) in the Makefile makes this target by combining the 4 schema files (“schemata”) mentioned above into one schema file, and also reformatting and validating it. The merge.sh script does the same, but without reformatting and validating the resulting JSON. This can be useful for development purposes, but make sure to also run make prior to committing.

Note: the first 4, non-combined schema files are always leading.

Value sets

The value set JSON files MUST validate against the valueset.json schema file. The value set file test-manf.json can be generated by running the following CLI command:

$ source valuesets/source-update/update-rat.sh > valuesets/test-manf.json

The update-rat.sh shell script retrieves the required information from https://covid-19-diagnostics.jrc.ec.europa.eu/. This is primarily meant as a tool for whoever is managing the governance of the central deployment. In particular, this script is not (to be) run by the Makefile, nor the CI.

Implementation Notes

A list of Frequently Asked Questions for implementors can be found in the repository wiki.

Prerequisites

The Makefile assumes that the following tools are installed, and are available on the shell's path:

• Python (version 3)
• A(ny) Make (such as GNU Make) to execute the Makefile.
• Node.js: installing Node.js also installs the NPM package manager which is used to install a couple of dependencies.
• jq

The Makefile also relies on the ajv JSON Schema validator, which is installed by the install-ajv rule in the Makefile:

$ make install-ajv

Examples and test cases

The examples and the test cases can be validated with ajv by using the following commands.

To validate all of the examples:

make validate-examples

..and all of expected valid tests:

make validate-valid-tests

..and all of the expected invalid tests:

make validate-invalid-tests