Skip to content
This repository has been archived by the owner on Jul 26, 2023. It is now read-only.

FAQ

Jump to bottom
Gaby Whitehead edited this page May 3, 2021 · 26 revisions

EU Digital Green Certificate JSON Schema FAQ

What are the certificate types supported?

As per the EU legislation, the three certificate types are:

  • Vaccination
  • Test
  • Recovery

What do the typical processing stages look like for:

Issuance of QR

Verification of QR

In both these cases there is a stage of processing in software in which business rules are applied. Examples of actions that may be present in business rules:

Issuance

  • If a required portion of a name is missing from the original data, set it to an empty value (see also: Mandatory Fields and Missing Data)
  • If an ISO8601 date-time field is specified as mandatory in the DGC JSON schema but do not wish to include the time portion as a matter of policy for your Member State, then you can set the hours, minutes and seconds (hh:mm:ss) fields to 00:00:00
  • In generating the certificate id, the choice of which option to choose from Annex 2 in the eHealthNetwork Vaccination Interoperability Guidelines is delegated to a member state. The business rules for issuance is an ideal place to create such a certificate id as per Member State policy.

Verification

  • If the QR payload you are reading contains a value unknown to you in a field governed by a defined ValueSet type, then you may choose whether you wish to validate the QR payload or not. An example of this is if there is a newer vaccine type available than is known to the verifier application. Assuming, the issuing state is using a known, valid vaccine type, then it can well be the case that the Verifier application is referring to a somewhat out-dated version of the ValueSet for vaccine types. One possible action at this point as a Verifier application could be to ensure that the latest ValueSet values are available to it and to re-try validation.

  • Process fields to arrive at a concrete payload. An example of this is to pass the certificate_id field in full (see UVCI Format) to a name resolution service which will map this to a resource that can be used for further processing, according to the Member State name resolution rules.

Reconciliation of Mandatory Fields and Missing Data

It can be the case that the data required to populate the DGC JSON schema is simply not present in the source data when queried. An oft-encountered example of this is with the patient name, where often the Family Name (EU Regulations: "Surname") is present, but the Given Name (EU Regulations: "Forename") is not. In the Annex to the proposed EU legislation it is stated that Surname(s), Forename(s) shall be given, in that order. In order to make the DGC JSON Schema as conformant as possible to this legislation, both fields Family Name and Given Name are marked as ["required"] so we need to supply the values. However, our data source only has Family Name and not Given Name.

The solution is to use the DICOM approach of Type 2 values. In summary, this allows a value to be specified as mandatory but can be marked as being empty and have no value. The rich DICOM metadata approach to values is not available to us in JSON (although we could get very close using XML), but we can approximate the DICOM approach by setting the mandatory field to an empty value (i.e. empty string for string types, 0 for numeric types). In this way, we can both support a mandatory value but allow the flexibility of handling the case when the source data simply does not have the value available for us.

Please note that if the value is available, then it is required to be set, as per DICOM Type 2:

[... defines] Type 2 Data Elements that shall be included and are mandatory Data Elements. However, it is permissible that if a Value for a Type 2 element is unknown it can be encoded with zero Value Length and no Value. If the Value is known the Value Field shall contain that value [...]. These Data Elements shall be included in the Data Set and their absence is a protocol violation.

Annex 2 specifies three different formats for certificate id (UVCI). Which one do I use?

For generating the certificate id: the choice of which option to choose from Annex 2 in the eHealthNetwork Vaccination Interoperability Guidelines is delegated to the Member State.

For verifying the certificate id: the complete certificate id field is simply passed to a standard (arpa) name resolution mechanism. Annex 2 also states that it is the responsibility of each Member State to maintain its own valid name resolution mapping:

[...] the Country or Authority identifier is well-managed; and each country (authority) is expected to manage its segment of the namespace well by never recycling or re-issuing identifiers.

Why does the DGC Schema does not conform precisely to the EU legislation in manner "X"?

The DGC Schema supports conformity to the proposed EU legislation is intended to be a vehicle for serialization and de-serialization according to several differing Member State requirements. For example, one Member State wishes to generate one QR code per certificate type and another may wish to generate a QR code combining two or three types of certificate. Both of these scenarios are supported by the DGC Schema. The business rules for that Member State, however, determine precisely which data the DGC schema will be populated with.

Why are the certificate type entries specified as an array?

The DGC schema presented here allows for multiple of all entries (in essence: array of ). This is because, the DGC schema (1) is designed in such a way that if regulations require (or allow) more than one entry per type, then there is no fundamental schema structure change, and (2) that the current regulation-conform implementation of only one entry can just be considered as an array of one element.

The proposed EU legislation specifies in the Annex which fields shall be present for a given instance of a particular certificate type. It must therefore be possible to create a QR payload (the DGC schema) with this information foR

The current schema allows us to conform to EU regulation, so that's the main criteria. It also allows for extension if / when needed (the Open-Closed Principle of "open for extension, closed for modification") - the 'O' in SOLID. The absolute final say on what is valid for (i) the EU and (ii) a given member state can be applied in the business rules part of the processing.

The checksum used is Luhn-Mod-N. What is the codeset and are there examples?

For ease of reference, the following is taken directly from Annex 2 in the [eHealthNetwork Vaccination Interop Guidelines] (https://ec.europa.eu/health/sites/health/files/ehealth/docs/vaccination-proof_interoperability-guidelines_en.pdf)

  1. Charset: Only uppercase US-ASCII alpha numerical characters (A to Z, 0 to 9) are allowed; with additional special characters for separation from RFC3986 , namely {/, #, :};
  2. Maximum length: designers should try to aim for a length of 27-30 characters
  3. Version prefix: This refers to the version of the UVCI schema. The version prefix is 01 for this version of the document. The version prefix is composed of two digits.
  4. Country prefix: The country code is specified by ISO 3166-1 alpha-2. Longer codes (e.g. 3 characters and up (e.g UNHCR) are reserved for future use
  5. Code suffix / Checksum:
    1. Member States should use a checksum when it is likely that transmission, (human) transcription or other corruptions may occur (i.e. when used in print).
    2. The checksum must not be relied upon for validating the certificate and is not technically part of the identifier but is used to verify the integrity of the code. This checksum should be the ISO-7812-1 (LUHN-10)7 summary of the entire UVCI in digital/wire transport format. The checksum is separated from the rest of the UVCI by a # character.

Luhn-Mod-N charset

ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#/:

Absolute Maximum Length

Note that for consistency with the rest of the DGC JSON Schema the absolute maximum field length will be set to 50.

Example

01 LUX/18737512422923 using the charset above, the checksum charset index is 12 and thus the corresponding checksum character is M.

Presentation in print

The checksum is mandatory in print. When presented in print the - the full, recommended presentations is that of

Version <space> Country [ / element ]+ # checksum character

E.g:

01 LUX/18737512422923 # M

Which can be abbreviated, if the context is sufficiently clear to

18738912478923 M

Implementers are encouraged to add a space every 3 and 4 char (alternating).

Clone this wiki locally