Learn

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:

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 in otf or ttf 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:

json
Copy to clipboard.
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 your template.pdf to set the generated PDF file name.

  • metadata: Use values from your template.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 a fonts folder in your template.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 font otf/ttf file in the fonts folder.

  • fields: This array includes fields that are defined in your template.pdf file:

    • key: Field name in the template.pdf file.

    • value: Mapped claim from the credential payload.

    • isRequired: When set to true, 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 for qrCode. If the value is defined in both template.pdf and config.json, the value from config.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.