Skip to Content
GuidesDirect issuanceCWTPDF templates

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:

  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 700kb.
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 (700kb).
  • Fields set as required in config.json are not available in template.pdf.
Last updated on