How to create a 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:

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