UR Code Templates & Metadata Minification

Learn more about how UR Code Templates are used to define UR Codes.

UR Code Template System

The UR Code Template System allows Issuing Authorities to specify the type of UR Codes being created. By defining the data structure ahead of time, UR Code Templates minimize the amount of data that needs to be stored within the UR Code itself. Templates also ensure the metadata is inputted and extracted in a consistent manner for an Application's Display Logic. The UR Code Scan+Match Apps and UR Scan+Match Device SDKs rely upon the Templated Format in their own Display Logic to display the metadata in its User Interface.

UR Code Template Files

The UR Code Template System currently includes the following Template Files:

Template Name	Use Cases	Fields
Basic Identification	Identify the Intended Recipient of a Package, Delivery, Ticket, or Service Confirm an Individual's State of Residence, Email, or Phone Number	Full Name, City, County, State, and Phone Number
Passport	Verify that an Individual has a Valid Passport Determine an Individual's Eligibility for a Travel Visa, Federal Grant, or Job Position	Full Name, Passport Number, Nationality, Date of Birth, Place of Birth, Sex/Gender, Issue Date, Expiration Date, and Issuing Authority
Driver's License	Ensure an individual has a Valid Driver's License Verify an Individual's Age or perform a Background Check	Full Name, Date of Birth, Driver's License Number, Height, Weight, Eye Color, Hair Color, Issue Date, Expiration Date, State, Country, and Sex/Gender
Age Validation Card	Verify an Individual's Age	Full Name, State, Country, Age
Business Card	Provide an Individual's Business Information	Full Name, Employer, Title, Email, and Phone Number
Student Identification Card	Verify that an individual is a Student	Institution Name, Student Name, Date of Birth, Expiration Date, and ID Number
Law Enforcement ID Card	Provide an Individual's Law Enforcement Credentials	Full Name, Badge Number, Rank, City, County, State, and Expiration Date
Law Enforcement Training Card	Provide an Individual's Law Enforcement Training Status	Card Type, Full Name, Date of Birth, Position, Status, and Expiration Date
Weapon Carry License	Provide an Individual's Weapon Carry License	License Number, Last Name, Middle Name, First Name, Date of Birth, Issue Date, Expiration Date, Issue County, and Issue State
First Responder ID Card	Provide an Individual's First Responder Credentials	Full Name, Badge Number, Rank, City, County, State, and Expiration Date
Medical ID Card	Provide an Individual's Medical ID Card Information	Full Name, Date of Birth, ID Number, Organization, Issue Date, and Expiration Date
Medical Locator Bracelet	Provide an Individual's Medical Locator Bracelet Information	Full Name, Contact Organization, Contact Organization Phone Number, Additional Information
ACH Payment (Automated Clearing House)	Retrieve an Individual's Payment Information	Account Holder's Name, Routing/ABA Number, Account Number, and Account Type
Credit Card Payment Details	Retrieve Credit Card Payment Information and verify that a Credit Card has not expired	Cardholder's Name, Credit Card Number, Expiration Date, and CVV
Crypto Wallet Address	Provide a Crypto Wallet Address	Wallet Address
Married Couple Details	Confirm a Joint Couple's Tax Filing Information Verify a Secondary User for a Credit Card/Bank Account	Spouse 1's First Name, Last Name, and Date of Birth Spouse 2's First Name, Last Name, and Date of Birth Marriage Date, License Number, and License State
Parent and Child Details	Confirm a Parent's Legal Authorization Confirm a Dependent on a Tax Form	Parent's First Name, Last Name, Age, and Country of Residence Child's First Name, Last Name, and Age
Three-Person Combination Code	Verify Authorization from Both Parents of a Child Confirm a Cosigner and Guarantor for a Rental Lease	Person 1's First Name, Last Name, Date of Birth, and Relationship to Person 2 Person 2's First Name, Last Name, Date of Birth, and Relationship to Person 3 Person 3's First Name, Last Name, and Date of Birth
Brazil National ID (CIN)	Provide an Individual's Taxpayer Identification Number (Brazil Only)	Full Name, CPF (Brazil's Taxpayer Identification Number), and Date of Birth

Template Data Types

Each field in a UR Code Template has a Data Type, which determines the possible values that can be specified. By specifying the Data Types, the UR Code Template System can specify field values with fewer bytes than what is required for a normal Raw String.

Data Type	Description	Examples
Boolean	A value that can either be True or False	"True", "False"
Sex	A Single-Character Representation for Gender/Sex	"M", "F", "O"
ISO Calendar Date	The ISO Calendar Date in the format yyyy-mm-dd	"2021-12-24", "1998-07-15", "2005-11-01"
Integer	An Unsigned Integer Value. Leading Zeroes are not retained (e.g. "0025" is stored as "25")	"5", "63", "147"
Compressed String	A String that is optimized for Data Storage Supports Numbers, Capitalized Letters, Empty Spaces, and ()\|+?,.*$@:~<>=_!#% -	"JOHN SMITH", "CALIFORNIA, USA", "T-SHIRT (BLUE): $74.99"
Raw String	A String without Data Storage Optimizations. Should only be used when one of the above data types is not viable	"John Smith", "Señora", "たなか"

Creating UR Codes with Templates

For Issuing Authorities, UR Code Template Schemas can be used to define the metadata in a UR Code. A UR Code can be created by downloading the appropriate Template Schema and updating the empty field values. The updated schema can then be used in the /create-ur-code-from-2d-image API to create a UR Code with the Templated Metadata.

A script can also be used to create UR Codes from an existing database by creating a Metadata JSON Object and API Request Payload for each Database Document that needs a UR Code. Once the payloads have been generated, the script can then proceed to create a batch of UR Codes. For an example of this, please see node_batch_sample_app.js in the UR Encoder SDK.

Creating Display Logic with Templates

For Relying Parties, UR Code Template Schemas can be used to identify the Metadata Fields in advance. This can be used to define Display Logic that is dependent on specific Template Keys and Field Keys.

The below example shows how Template Keys and Field Keys can be used to determine if a Driver's License has expired.

// A function to determine if a Driver's License has expired.
function isDriversLicenseExpired(metadata) {
  const metadataObj = JSON.parse(metadata);
  const templateKey = metadataObj["templateKey"];
  if (templateKey == "DriversLicense") {
    const fields = metadataObj["fields"][0];
    for (i = 0; i < fields.length; i++) {
      const field = fields[i];
      if (field["fieldKey"] == "ExpirationDate") {
        const expirationDate = new Date(field["value"]);
        const currentDate = new Date();
        if (currentDate >= expirationDate) {
          return "The Driver's License is expired.";
        }
        else {
          return "The Driver's License is still valid.";
        }
      }
    }
  }
  return "This document is not a Driver's License.";
}

Template Schema Example

Below is an example of the UR Code Template Schema for a Driver's License:

{
  # Template Name:            Driver's License
  # Template Description:     A Template for specifying an individual's Driver's License Information in a UR Code.
  # Template System Info:     The UR Code Template System allows Issuing Authorities to specify the type of UR Codes 
  #                           being created. By defining the data structure ahead of time, UR Code Templates minimize 
  #                           the amount of data that needs to be stored within the UR Code itself. Templates also ensure
  #                           the metadata is inputted and extracted in a consistent and organized manner for an 
  #                           Application's Business Logic. The UR Code Scan+Match Apps and UR Code Scan+Match SDKs rely upon 
  #                           the Templated Format in their own Business Logic to display the metadata in its User Interface.
  #                           
  #                           For more information about Templates, please see https://dev.urcodes.com/ur-code-templates-metadata-minification.
  # Data Type Info:           The Data Type required for each field is specified in its Field Header.
  #                           For a table of the available Data Types, please see 
  #                           https://dev.urcodes.com/ur-code-templates-metadata-minification#template-data-types.
  # Using Templates:          For Issuing Authorities, UR Code Template Schemas can be used to define the metadata
  #                           in a UR Code. For more information, please see Creating UR Codes with Templates 
  #                           <https://dev.urcodes.com/ur-code-templates-metadata-minification#creating-ur-codes-with-templates>.
  #                     
  #                           For Relying Parties, UR Code Template Schemas can be used to identify the Metadata Fields
  #                           in advance. This can be used to define Business Logic that is dependent on specific Template Keys 
  #                           and Field Keys. For more information, please see Creating Display Logic with Templates
  #                           <https://dev.urcodes.com/ur-code-templates-metadata-minification#creating-display-logic-with-templates>.
  # Need Additional Fields?   If you need a field that is not specified below or need a new template created, then please visit the 
  #                           https://dev.urcodes.com/request-support to contact support.
  "templateKey": "DriversLicense",
  "numberOfPersons": 1,
  "fields": [
    [
      -----------------BEGIN REQUIRED FIELDS-----------------
      -----------------END REQUIRED FIELDS-------------------

      -----------------BEGIN OPTIONAL FIELDS-----------------
      # Field Name:           Full Name
      # Field Description:    The Full Name on the Driver's License.
      # Data Type:            Compressed String
      # Example Value:        Ex. JOHN SMITH
      {
          "fieldKey": "FullName",
          "value": "",
      },

      # Field Name:           Date of Birth
      # Field Description:    Date of Birth on the Driver's License.
      # Data Type:            ISO Calendar Date
      # Example Value:        Ex. 1985-10-31
      {
          "fieldKey": "DateOfBirth",
          "value": ""
      },

      # Field Name:           Driver's License Number
      # Field Description:    The Driver's License Number.
      # Data Type:            Compressed String
      # Example Value:        A1234567
      {
          "fieldKey": "DriversLicenseNumber",
          "value": ""
      },

      # Field Name:           Height
      # Field Description:    The Height specified on the Driver's License.
      # Data Type:            Raw String
      # Example Value:        67 in
      {
          "fieldKey": "Height",
          "value": ""
      },

      # Field Name:           Weight
      # Field Description:    The Weight specified on the Driver's License.
      # Data Type:            Raw String
      # Example Value:        180 lb
      {
          "fieldKey": "Weight",
          "value": ""
      },

      # Field Name:           Eye Color
      # Field Description:    The Eye Color specified on the Driver's License.
      # Data Type:            Compressed String
      # Example Value:        BLU
      {
          "fieldKey": "EyeColor",
          "value": ""
      },

      # Field Name:           Hair Color
      # Field Description:    The Hair Color specified on the Driver's License.
      # Data Type:            Compressed String
      # Example Value:        BRN
      {
          "fieldKey": "HairColor",
          "value": ""
      },

      # Field Name:           Issue Date
      # Field Description:    The Date that the Driver's License was Issued.
      # Data Type:            ISO Calendar Date
      # Example Value:        Ex. 2022-07-14
      {
          "fieldKey": "IssueDate",
          "value": ""
      },
      
      # Field Name:           Expiration Date
      # Field Description:    The Date that the Driver's License is set to expire.
      # Data Type:            ISO Calendar Date
      # Example Value:        Ex. 2027-10-31
      {
          "fieldKey": "ExpirationDate",
          "value": ""
      },

      # Field Name:           State
      # Field Description:    The State specified on the Driver's License.
      # Data Type:            Compressed String
      # Example Value:        Ex. CA
      {
          "fieldKey": "State",
          "value": ""
      },

      # Field Name:           Country
      # Field Description:    The Country specified on the Driver's License.
      # Data Type:            Compressed String
      # Example Value:        Ex. USA
      {
          "fieldKey": "Country",
          "value": ""
      }

      # Field Name:           Sex/Gender
      # Field Description:    The Sex/Gender specified on the Driver's License.
      # Data Type:            Sex/Gender
      # Example Value:        Ex. M
      {
          "fieldKey": "Sex",
          "value": ""
      }
      -----------------END OPTIONAL FIELDS-------------------
    ]
  ],
  "textBelowURCode": "",
  "textBottomRightInsideURCode": ""
}

Text & Language Customization

The strings in the UR Code Templates can be customized in the UR Scan+Match Device SDKs. To learn how to customize these strings, please see the UR Code Template - Text & Language Customization Guide.

Displaying Text within (or beneath) UR Codes

Each UR Code Template contains the textBelowURCode and textBottomRightInsideURCode properties. The text specified for these properties is either printed below the UR Code (textBelowURCode) or in the bottom-right corner of the UR Code (textBottomRightInsideURCode).

The Printed Text is not encoded into the UR Code itself and is not returned in the metadata when the UR Code is scanned.

Custom Fields & UR Code Templates

FaceTec can add new Fields or create new UR Code Templates to support your Use Case requirements.

If you require specific Fields or want a new UR Code Template created that is not listed in this guide, please Send FaceTec a Support Request to contact support.