Card Templates

Card templates define how credentials issued through the platform are displayed in wallets.
While credentials contain the signed data, templates describe how that data should be presented to the user, including layout, branding, and which claims are visible on the card.

Templates allow issuers to customize the visual appearance of credentials without requiring updates to the wallet application.

Template Metadata

A card template is defined by a JSON document that instructs the wallet how to render a credential.

Templates describe:

• layout structure
• branding
• field mappings
• display labels
• supported assets

The wallet combines the template metadata with the credential claims to render the card.

---

Template Metadata Structure

Property	Type	Required	Description
vct	string	yes	The credential type this template applies to
displayName	string	yes	Human-readable name of the card
layout	string	yes	Layout used to render the card
branding	object	no	Visual styling for the card
fields	array	yes	Mapping of credential claims to card UI slots
description	string	no	Optional description of the card
version	string	no	Template version identifier

---

Example Template Metadata

{
  "vct": "com.platform.customerA.membership.v1",
  "displayName": "Customer A Membership Card",
  "layout": "photo_list",
  "branding": {
    "logoUrl": "https://example.com/assets/customerA/logo.png",
    "backgroundColor": "#1E3A8A",
    "textColor": "#FFFFFF",
    "accentColor": "#FBBF24"
  },
  "fields": [
    {
      "slot": "photo",
      "claim": "photo"
    },
    {
      "slot": "hero",
      "claim": "fullName",
      "label": "Name"
    },
    {
      "slot": "row1",
      "claim": "membershipId",
      "label": "Member ID"
    },
    {
      "slot": "row2",
      "claim": "tier",
      "label": "Tier"
    },
    {
      "slot": "row3",
      "claim": "expiryDate",
      "label": "Valid Until"
    }
  ]
}

---

Template Examples

Below are examples of supported card template layouts.

---

Layout

The layout property defines the structural arrangement of the card.

Layouts determine how slots are arranged visually.

Supported layouts may include:

Layout	Description
photo_hero	Photo with a large highlighted value
photo_list	Photo with stacked data fields
list_highlight	Data rows with highlighted field
simple_list	Text-only card layout

The wallet rendering engine implements these layouts.

---

Branding

The branding section defines the visual appearance of the card.

Branding may include:

Property	Description
logoUrl	Issuer logo displayed on the card
backgroundColor	Card background color
backgroundImage	Optional background image
textColor	Primary text color
accentColor	Highlight color

Example:

"branding": {
  "logoUrl": "https://example.com/assets/logo.png",
  "backgroundColor": "#1E3A8A",
  "textColor": "#FFFFFF",
  "accentColor": "#FBBF24"
}

---

Field Mapping

The fields section maps credential claims to UI slots in the template.

Each field object contains:

Property	Required	Description
slot	yes	UI position within the layout
claim	yes	Claim name in the credential
label	no	Display label shown in the wallet

Example:

{
  "slot": "row1",
  "claim": "membershipId",
  "label": "Member ID"
}

The wallet retrieves the claim value from the credential and renders it in the specified slot.

---

Supported Slots

Templates use predefined UI slots supported by the wallet renderer.

Slot	Description
photo	Cardholder image
logo	Issuer
Title	Card title
row1	First data row
row2	Second data row
row3	Third data row
row4	Fourth data row
footer	Footer information

Available slots may vary depending on the selected layout.

---

Template Versioning

Templates are versioned using the vct.

Example:

com.platform.customerA.membership.v1
com.platform.customerA.membership.v2

Versioning allows:

• design updates
• layout changes
• new fields
• backwards compatibility for previously issued credentials

When making major layout changes, create a new template version.

---

Best Practices

Keep credentials as the source of truth

Templates should only control presentation, not credential data.

Use consistent claim names

Use consistent claim names across credentials to simplify field mapping.

Version templates carefully

Avoid modifying the layout of an existing template version used by issued credentials.

Keep layouts simple

Limit layouts to supported structures to ensure consistent rendering across wallets.

---

Summary

Templates allow issuers to control how credentials appear in wallets without modifying the wallet application.

Key principles:

• Credentials contain verifiable data
• Templates define visual presentation
• Wallets render cards using template metadata