Skip to main content

Design a PDF template

A PDF template is required to format a Compact or Semantic Compact 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.

tip

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:


{
  "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.

What's next?​

After designing your template locally, use it to create a Sovrin PDF template.