Learn

PDF Template Design Guideline

Introduction

A PDF template is required to be used to generate a digital PDF file of the Compact Credential.  This page provides best practice guidance for designing the Compact Credential PDF template.

template.zip

Copy to clipboard.
template.zip
├─ config.json                  //MANDATORY
├─ template.pdf                 //MANDATORY
└─ fonts                        //optional
   ├─ PublicSans-Regular.ttf
   └─ PublicSans-Bold.ttf

A template.zip file is required to be uploaded. It is structured as follows: 

  •  A maximum of 1MB is permitted for the template.zip file.

  • template.pdf (mandatory): a PDF template designed by your organization.

  • config.json (mandatory): a JSON file for field mappings 

  • Custom fonts are supported. If a template uses custom fonts, font files in otf or ttf format must be provided.

template.pdf

  • The maximum size of template.pdf is 700kb.

  • The template must have a qrCode button field. This is not part of the config as there is no value mapping will be required. QR code is generated from the payload.  

  • All other fields in the template should be plain text fields.  

  • Other field types are not supported. i.e. checkboxes, radio buttons, list boxes or dropdown boxes. 

  • Plain fields only, no macros, rules, formulation or calculations. 

  • It is possible to have the same claim in the PDF multiple times. The field name must contain a suffix. e.g. firstName#1, firstName#2

  • A multi-page template is supported. However, The qrCode field must be on the first page of the PDF template.

  • To support accessibility, the reading order of each field should be specified in template.pdf. Unselect "Display like elements in a single block".

config.json

This file is structured as follows:

  • name is the name of the template

  • fileName is the file name of the generated PDF file

  • metadata is the metadata of the generated PDF file

json
Copy to clipboard.
1"name": "SamplePDF_WorkingAtHeightsCertVC",
2"fileName": "CWT_{{ name }}",
3"metadata": {
4    "title": "{{ certificationName }} Certification – {{ name }}"
5}

  • fonts are a set of custom fonts applied to a field in the PDF. The name of the font should match the fontName of a field. For example:

json
Copy to clipboard.
1"fonts": [
2    {
3        "name": "PublicSans-Regular",
4        "fileName": "PublicSans-Regular.ttf"
5    }
6]
json
Copy to clipboard.
1{
2    "key": "expiry",
3    "value": "{{ date vc.credentialSubject.expiry 'dd MMM yyyy' }}",
4    "isRequired": true,
5    "alternativeText": "{{ date vc.credentialSubject.expiry 'PPP' }}",
6    "fontName": "PublicSans-Regular"
7}

  • text fields defined in pdf.template:

    • key is the field name defined in pdf.template.

    • value is mapped claim from the payload.

    • date value can be formatted. e.g. {{ date expiry 'dd MMM yyyy' }}

    • isRequired: true means a field value is expected, if it is not provided in the payload, an error will occur.

    • To support Accessibility, alternativeText must be specified in config.json except for qrCode field. If the alternativeText of the same field is defined in both files, the one in config.json overwrites the one in template.pdf.

    • fontName is the custom font name. if no custom font is specified, it uses Helvetica by default.

Note: the default "Helvetica" only supports Windows-1252 encoding character sets. See what this means and its implications on Implementation Considerations – Internationalization.

json
Copy to clipboard.
1"fields": [
2    {
3        "key": "name",
4        "value": "{{ name }}",
5        "isRequired": true,
6        "alternativeText": "{{ name }}",
7        "fontName": "PublicSans-Regular"
8    },
9    {
10        "key": "code",
11        "value": "{{ code }}",
12        "isRequired": true,
13        "alternativeText": "{{code }}",
14        "fontName": "PublicSans-Bold"
15    },
16    {
17        "key": "certificationName",
18        "value": "{{certificationName }}",
19        "isRequired": true,
20        "alternativeText": "{{ certificationName }}",
21        "fontName": "PublicSans-Bold"
22    },
23    {
24        "key": "certificationLevel",
25        "value": "{{ certificationLevel }}",
26        "isRequired": true,
27        "alternativeText": "{{ certificationLevel }}",
28        "fontName": "PublicSans-Regular"
29    },
30    {
31        "key": "expiry",
32        "value": "{{ date expiry 'dd MMM yyyy' }}",
33        "isRequired": true,
34        "alternativeText": "{{ date expiry 'PPP' }}",
35        "fontName": "PublicSans-Regular"
36    }
37]

Samples: Working at Heights

Download the compact credential sample template.zip file here. 
Download the semantic compact credential sample template.zip file here.