How to create a PDF template

A PDF template is required to format a CWT or Semantic CWT credential as a PDF document.

Overview

Creating a PDF template comprises the following steps:

Design a template
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:

CWT credential sample PDF template.
Semantic CWT credential sample PDF template.

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 Internationalization 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 CWT credential PDF template:

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

You can make a similar request to a different endpoint to create a Semantic CWT credential PDF template:

POST /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 CWT 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.

CWT Apple Digital Pass templates