Design a PDF template
A PDF template is required to format a Compact or Compact Semantic Credential as a PDF document. This guide will show you how to design a PDF template. The design is similar whether you are creating a Compact or a Semantic Compact PDF template.
You can download the following sample files to better understand how to structure your own templates as you follow along this guide:
Compact credential sample PDF template.
Compact Semantic Credential sample PDF template.
Template structure
Your PDF template must be bundled as a single file named template.zip
, which bundles the following components:
template.pdf
: This is a required PDF file used as the PDF template.config.json
: This is a required JSON file used for field mappings.fonts
: This is an optional folder that includes any custom fonts being used in the template inotf
orttf
format.
The maximum size of the
template.zip
file is 1mb.
template.pdf
The maximum size of template.pdf is 700kb.
The template must have a qrCode button field. The QR code is generated from the payload and there is no value mapping required for this field.
All other fields in the template should be plain text fields
Other field types (e.g. checkboxes, radio buttons, list boxes, dropdown boxes) are not supported.
No macros, rules, formulation or calculations are supported.
It is possible to have identical claims in the same PDF. The field names be suffixed (e.g. firstName#1, firstName#2).
Multi-page templates are supported as long as the qrCode field is on the first page.
Reading order for each field should be specified to support accessibility. Unselect "Display like elements in a single block".
config.json
This JSON file should be structured as follows:
1{
2 "name": "SamplePDF_WorkingAtHights",
3 "fileName": "{{ vc.credentialSubject.code }}_{{ vc.credentialSubject.name }}",
4 "metadata": {
5 "title": "{{ vc.credentialSubject.certificationName }} Certification – {{ vc.credentialSubject.name }}"
6 },
7 "fonts": [
8 {
9 "name": "PublicSans-Regular",
10 "fileName": "PublicSans-Regular.ttf"
11 },
12 {
13 "name": "PublicSans-Bold",
14 "fileName": "PublicSans-Bold.ttf"
15 }
16 ],
17 "fields": [
18 {
19 "key": "name",
20 "value": "{{ vc.credentialSubject.name }}",
21 "isRequired": true,
22 "alternativeText": "{{ vc.credentialSubject.name }}",
23 "fontName": "PublicSans-Regular"
24 },
25 {
26 "key": "code",
27 "value": "{{ vc.credentialSubject.code }}",
28 "isRequired": true,
29 "alternativeText": "{{ vc.credentialSubject.code }}",
30 "fontName": "PublicSans-Bold"
31 }
32 ]
33}
name
: Template name.fileName
: Use values from yourtemplate.pdf
to set the generated PDF file name.metadata
: Use values from yourtemplate.pdf
to set the generated PDF metadata.fonts
: This array includes custom fonts that are used in your PDF template. Note that these custom fonts must be included in afonts
folder in yourtemplate.zip
bundle for the template to be valid.name
: The name of the font to be referenced by fields using it.fileName
: The name of the fontotf
/ttf
file in thefonts
folder.
fields
: This array includes fields that are defined in yourtemplate.pdf
file:key
: Field name in the template.pdf file.value
: Mapped claim from the credential payload.isRequired
: When set totrue
, the value must be provided in the credential payload to generate a valid PDF. If it is not provided, an error would occur.alternativeText
: Alternative text to support accessibility. Must be specified for every field except forqrCode
. If the value is defined in bothtemplate.pdf
andconfig.json
, the value fromconfig.json
is used.fontName
: Custom font name to display the field. When no font is specified Helvetica is used by default. Note that this default font only supports Windows-1252 encoding character sets. Refer to Internationalisation implementation considerations for more information.
What's next?
After designing your template locally, use it to create a MATTR VII PDF template.