Guides
Credential Issuance
Direct
Templates
PDF

How to create a PDF template

A PDF template is required to format a Compact or Compact Semantic Credential as a PDF document.

Overview

Creating a PDF template comprises the following steps:

  1. Design a template
  2. Create a MATTR VII template

Sample templates: You can download the following sample templates to better understand how to structure your own templates as you follow along this guide:

Design a template

Bundle the following template components into a .zip file:

  • 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 template .zip file cannot be larger than 1mb.

template.pdf

  • 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
{
    "name": "SamplePDF_WorkingAtHights",
    "fileName": "{{ vc.credentialSubject.code }}_{{ vc.credentialSubject.name }}",
    "metadata": {
        "title": "{{ vc.credentialSubject.certificationName }} Certification – {{ vc.credentialSubject.name }}"
    },
    "fonts": [
        {
            "name": "PublicSans-Regular",
            "fileName": "PublicSans-Regular.ttf"
        },
        {
            "name": "PublicSans-Bold",
            "fileName": "PublicSans-Bold.ttf"
        }
    ],
    "fields": [
        {
            "key": "name",
            "value": "{{ vc.credentialSubject.name }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.name }}",
            "fontName": "PublicSans-Regular"
        },
        {
            "key": "code",
            "value": "{{ vc.credentialSubject.code }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.code }}",
            "fontName": "PublicSans-Bold"
        }
    ]
}
  • 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.

Create a MATTR VII template

Request

Make a request of the following structure with the template .zip file included as a binary file to create a Compact Credential PDF template:

POST /core/v2/credentials/compact/pdf/templates
Header: Content-Type: application/zip

You can make a similar request to a different endpoint to create a Compact Semantic Credential PDF template:

POST /core/v2/credentials/compact-semantic/pdf/templates
Header: Content-Type: application/zip

Response

{
    "id": "682f203a-f5bd-4304-95e3-c8c708e90d26",
    "name": "SamplePDF_WorkingAtHights",
    "fileName": "{{ vc.credentialSubject.code }}_{{ vc.credentialSubject.name }}",
    "fonts": [
        {
            "name": "PublicSans-Regular",
            "fileName": "PublicSans-Regular.ttf"
        },
        {
            "name": "PublicSans-Bold",
            "fileName": "PublicSans-Bold.ttf"
        }
    ],
    "fields": [
        {
            "key": "name",
            "value": "{{ vc.credentialSubject.name }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.name }}",
            "fontName": "PublicSans-Regular"
        },
        {
            "key": "code",
            "value": "{{ vc.credentialSubject.code }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.code }}",
            "fontName": "PublicSans-Bold"
        },
        {
            "key": "certificationName",
            "value": "{{ vc.credentialSubject.certificationName }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.certificationName }}",
            "fontName": "PublicSans-Bold"
        },
        {
            "key": "certificationLevel",
            "value": "{{ vc.credentialSubject.certificationLevel }}",
            "isRequired": true,
            "alternativeText": "{{ vc.credentialSubject.certificationLevel }}",
            "fontName": "PublicSans-Regular"
        },
        {
            "key": "expiry",
            "value": "{{ date vc.credentialSubject.expiry 'dd MMM yyyy' }}",
            "isRequired": true,
            "alternativeText": "{{ date vc.credentialSubject.expiry 'PPP' }}",
            "fontName": "PublicSans-Regular"
        }
    ],
    "metadata": {
        "title": "{{ vc.credentialSubject.certificationName }} Certification – {{ vc.credentialSubject.name }}"
    }
}
  • id : This is a unique identifier for this PDF template. You will use it as the templateId when formatting a Compact Credential as a PDF.
  • All other fields in the response include information retrieved from your PDF template.

Troubleshooting

Errors may occur in the following scenarios:

  • Unable to decompress the template .zip file.
  • Either template.pdf or config.json are missing from the bundle.
  • Either template.pdf or config.json are malformed.
  • Custom fonts are used but not provided in template.zip.
  • Either the template .zip file or template.pdf exceed the maximum allowed file size (1mb and 700kb, respectively).
  • Fields set as required in config.json are not available in template.pdf.