JSON Template

The pass.json file is the core of the Passbook boarding pass. It contains the layout information, the text fields that are displayed on the boarding pass and the fields controlling the updating of the boarding pass in addition to the location and time information for alerts and notifications.

Refer to Apple’s developer documentation for full details of the pass.json file and also the JSON web site (http://www.json.org/) for information on using the JSON script language. Most of the customisation required in this file is to provide or amend keys and values for information fields.

To edit the pass.json file, click on the pass.json Template tab on the Apple Passbook Configuration screen. The following editing window is displayed.

The pass.json file can be modified the same as a normal text file. Ensure that you retain the same script syntax and structure when customising this file.

The information shown on the pass is represented by fields in the pass.json file. Each field has a value and label, a unique key, and optional information about how its value should be formatted. Details of the pass layout is on the Customsing a Template for Apple Passbook page.

The following fields are available in the default pass.json file for customisation.




The background colour is used for the background of the front and back of the pass.

All colour keys can be specified as RGB decimal values, for example, rgb(232,232,232) or RGB hexadecimal value, for example, #0064a7.


The foreground colour is the colour in which the values for the fields on the front of the pass are displayed.


The label colour is the colour in which the labels for the fields on the front of the pass are displayed.


The barcode describes the barcode you want to display. You need to specify the barcode format, the message to be displayed and the encoding used by the message. These The barcode format should be PKBarcodeFormatAztec. You can optionally include a caption key if you want to print text just below the barcode.

"barcode" : { "format" : "PKBarcodeFormatAztec",
      "message" : "${BarcodeData}",
      "messageEncoding" : "utf-8"

Boarding passes can have up to five auxiliary fields. These fields are less prominent than primary and secondary fields.


This fields enables you to add messages which will be used for alert notifications, for example, in cases where a flight number or boarding time is changed.

"boardingPass" : { "auxiliaryFields" : [ { "changeMessage" : "Boarding time changed to %@.",
            "key" : "boardingTime",
            "label" : "BOARDING",
            "value" : "${BRec.boardingHHMM}"

The back of the pass can have as many fields as required and the contents of fields can be much longer than at the front. You can also scroll through content at the back of the boarding pass.

The back fields usually contain general information for passengers, for example, the URL of your website, passenger’s name, booking reference and cabin class.

 {"key": "website",
           "label": "Website",
           "value": "http://www.developer.aero"
          { "key" : "passenger",
            "label" : "PASSENGER",
            "value" : "${BRec.paxName}"
          { "key" : "depDate",
            "label" : "Departure Date",
            "value" : "${BRec.depDDMMM}"
          { "key" : "bookRef",
            "label" : "Booking Reference",
            "value" : "${BRec.bookingRef}"
          { "key" : "class",
            "label" : "CLASS",
            "value" : "${BRec.cabinClassCode}"

Header fields contain important information which are visible when the passes are stacked up in Passbook.

For example, to display a gate change message in the header fields, the following key, label and values are used.

 "headerFields" : [ { "changeMessage" : "Gate changed to %@.",
            "key" : "gate",
            "label" : "GATE",
            "value" : "${BRec.gate}"

Boarding passes can have up to two primary fields. The primary fields contain the most important information such as departure and arrival airports and are shown prominently on the pass.

"primaryFields" : [ { "key" : "depart",
            "label" : "DEPARTURE CITY",
            "value" : "${BRec.deptAirportCode}"
          { "key" : "arrival",
            "label" : "ARRIVAL CITY",
            "value" : "${BRec.arrAirportCode}"

Secondary fields are less important and less prominent than primary fields. These fields may include items such as the passenger name.

 secondaryFields" : [ { "key" : "passenger",
            "label" : "PASSENGER",
            "value" : "${BRec.paxName}"

PKTransitTypeAir. This field denotes a boarding pass.


Enables Apple’s VoiceOver make your pass accessible to blind and low vision users.

Ensure that is description is concise but clearly identifies the functionality of the pass, for example, ‘SITA Airlines Boarding Pass’.


The version of the file format. Value is currently ‘1’ and must not be changed.


This key provides a relevant location, such as an airport location, to determines at what at what distance from this location that the pass appears on the lock screen .Its value includes longitude, latitude, and optional altitude information.

"locations" : [ { "latitude" : ${Dep.latitude},
        "longitude" : ${Dep.longitude}

Passbook determines the appropriate radius around these values to determine when the pass appears on the lock screen. A boarding pass can have up to ten relevant locations. You can also provide a description of why the pass is relevant at a given location, for example, ‘Close to Airport’:

"relevantText" : "Close to Airport”


Identifies who the boarding pass belongs to and is displayed on the lock screen when your pass is required, for example, when you are close to the airport. For example, SITA Airlines.


Refer to the section on Signing Passes on page 18. The default is:



Passbook determines the appropriate duration of time around this value that the pass appears on the lock screen.


The serial number is a string that, combined with the pass type identifier, uniquely identifies the pass. The serial number is opaque to Passbook and can be assigned in whatever way is required by the airline.


Refer to the section on Signing Passes.