Skip to content
Help Center Guide · Pass Templates
5 min readVerified 2026-11-16

Import from Apple Pass Designer

Import .passdesign folders, Property List (.plist) files, and unsigned packages directly into native Passinstance templates.

In This Guide

Overview

Designers and iOS engineers who prototype digital passes using macOS developer tools—such as Apple's official Pass Designer, Xcode, or third-party desktop pass builders—can import their designs directly into Passinstance. You do not need to manually re-enter field coordinates, color values, barcode types, or upload image assets one by one.

Passinstance provides automated ingestion for:

  • Apple Pass Designer archives (.passdesign bundles).
  • Apple Property List XML documents (.plist or .xml).
  • Unsigned or signed Apple Wallet packages (.pkpass zip archives).
  • Raw Apple PassKit metadata files (pass.json).

The import engine extracts image assets (icon.png, logo.png, strip.png, thumbnail.png), parses the structural layout, and normalizes it into a fully editable Passinstance template compatible with both Apple Wallet and Google Wallet.

System Architecture: Apple PassKit & Plist Ingestion Engine

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
APPLE PASS DESIGNER INGESTION ENGINE
STAGE 01 APPLE PASS DESIGNER SOURCE ARTIFACTS
.passdesign bundle (macOS Pass Designer document package)
.plist / .xml (Apple Property List format)
.pkpass / .zip (Signed or unsigned Apple Wallet bundle)
pass.json (Raw Apple PassKit specification dictionary)
STAGE 02 INGESTION & SECURITY PARSER
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Hardened XML Parser: Zero external entity resolution (prevents XXE attacks)
Depth Guard: MAX_PLIST_DEPTH = 32 (prevents recursion overflow)
Zip Safety Limits: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Unsigned Package Mode: isUnsignedPackage: true (bypasses Apple signature req)
STAGE 03 PASSKIT TO PASSINSTANCE SCHEMA NORMALIZER
Apple StylesPassKind (storeCard, coupon, eventTicket, etc.)
Plist TypesJS Types (dictObject, arrayArray, realNumber)
Colors: Normalizes Apple rgb(r, g, b) and converts for Google Wallet hex
Barcodes: Normalizes PKBarcodeFormat* and assigns watchOS fallback
Asset Extraction: Routes @1x, @2x, @3x retina PNGs to S3 storage
STAGE 04 CANONICAL PASSINSTANCE TEMPLATE (Template Entity)
Live interactive preview in Apple Wallet & Google Wallet simulator
Ready for immediate pass issuance, batch CSV import, or PassFlow registration

Supported File Formats & Extensions

The file uploader in Template Creation Wizard accepts the following extensions matching regex /\.(passdesign|plist|xml|pkpass|zip|json)$/i:

Format / ExtensionDescriptionContents Extracted
.passdesignApple Pass Designer bundle folder or compressed archive.Complete pass geometry, visual field layouts, colors, and all retina PNG assets.
.plist / .xmlApple Property List XML format.Field structures, label/value pairs, transit types, barcodes, and relevancy rules.
.pkpassStandard Apple Wallet pass archive (signed or unsigned).pass.json, localization directories (.lproj), and image assets. Digital signature (signature) and manifest (manifest.json) are safely ignored.
pass.jsonCanonical Apple PassKit dictionary.Standard Apple PassKit JSON structure.

XML Security & Entity Safety (parsePlistXmlToObject)

When ingesting Apple .plist or .xml documents, Passinstance uses a hardened internal XML parser (parsePlistXmlToObject in template-import-export.util.ts) with strict security invariants:

  1. 1
    XXE Protection (Zero External Entity Resolution): The parser completely ignores <!DOCTYPE> declarations, external entity definitions (SYSTEM or PUBLIC), and XML schema references. This eliminates XML External Entity (XXE) injection and Server-Side Request Forgery (SSRF) vulnerabilities.
  2. 2
    Recursion & Depth Safeguard: Recursion depth is capped at MAX_PLIST_DEPTH = 32. Nested dictionaries or arrays exceeding this threshold are aborted with a validation exception to prevent stack overflow attacks.
  3. 3
    Zip Bomb Prevention: When unpacking .passdesign or .pkpass zip files, the engine limits the total entries to MAX_ZIP_ENTRIES = 250 and the uncompressed size per file to MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 bytes).
  4. 4
    Prototype Pollution Protection: Property keys matching __proto__, constructor, or prototype are stripped during dictionary construction.

Apple PassKit Type Mapping Reference

The import utility automatically maps Apple Property List types and PassKit structures to Passinstance models:

Apple PassKit / Plist TypePassinstance Model EquivalentNormalization Behavior
<dict>JavaScript ObjectMaps to field groups, color objects, or location dictionaries.
<array>JavaScript ArrayMaps to field arrays (headerFields, primaryFields, etc.).
<string>stringCleans up whitespace and unescapes XML entities (&amp;, &lt;, &gt;).
<integer> / <real>numberConverted to floating point or integer numbers.
<true/> / <false/>booleanConverted to standard JavaScript boolean primitives.
<date>ISO 8601 stringNormalized to UTC ISO-8601 timestamps (YYYY-MM-DDTHH:MM:SSZ).
<data>Base64 stringBase64-decoded into binary asset buffers for images.

Pass Style to Pass Kind Normalization

Apple Pass StylePassinstance PassKindLayout & Field Invariants
storeCardstoreCardFront layout with strip image; up to 4 secondary/auxiliary fields.
couponcouponFront layout with strip image; auxiliary fields redirected to secondary.
eventTicketeventTicketSupports background texture, strip image, and iOS 18 venue companion blocks.
boardingPassboardingPassParses transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) and primary departure/arrival fields.
genericgenericStandard multi-purpose card layout with optional thumbnail.

Importing via the Dashboard (Step-by-Step)

  1. 1
    Navigate to Templates in the Passinstance Dashboard and click + New Template.
  2. 2
    In Step 1 (Details) of the Template Creation Wizard:

- Click Import existing pass or drag and drop your .passdesign, .plist, .pkpass, or pass.json file into the upload zone.

  1. 3
    The wizard parses the file instantly, extracting:

- Template Name & Description: Pre-populated from description or organizationName. - Pass Kind: Auto-detected based on the Apple pass style dictionary. - Colors: Background, foreground, and label colors populated into the color palette. - Images: Retina assets (icon.png, logo.png, strip.png) uploaded to the workspace asset store. - Field Layouts: Header, primary, secondary, auxiliary, and back fields placed in their designated zones.

  1. 4
    Continue through Step 2 (Pass Type) and Step 3 (Wallet Apps) to review or enable Google Wallet support.
  2. 5
    In Step 4 (Completion), assign an Apple Pass Type Certificate to enable cryptographic signing, then click Finish.

Importing via REST API

You can also import Apple Pass Designer packages programmatically via POST /api/v1/templates/import.

HTTP Request (multipart/form-data)

BASH
curl -X POST https://api.passinstance.com/api/v1/templates/import \
  -H "X-API-Key: <API_KEY>" \
  -F "file=@loyalty_pass.passdesign" \
  -F "name=Imported Loyalty Card"

HTTP Response (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01h8x7j6k5m4n3p2q1",
    "name": "Imported Loyalty Card",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "importedFrom": "apple_pass_designer",
    "imagesImported": ["icon", "logo", "strip"],
    "fieldsCount": 8,
    "createdAt": "2026-11-16T20:35:00.000Z"
  },
  "statusCode": 201
}

Troubleshooting Apple Pass Import

Symptom / ErrorRoot CauseResolution
Unsupported file formatFile extension does not match supported list.Ensure your file ends in .passdesign, .plist, .xml, .pkpass, .zip, or .json.
Missing required icon assetThe Apple package did not contain an icon.png or icon@2x.png.Apple PassKit requires an icon for every pass. Add a 76x76 or 114x114 PNG icon file to your package before importing.
Zip entry size exceededAn image asset inside the archive exceeded 1 MB.Optimize raster images using PNG crush tools or upload assets separately after template creation.
Unsigned package noticeThe imported .pkpass did not contain a valid cryptographic signature.Normal for prototyping packages (isUnsignedPackage: true). Passinstance accepts unsigned archives and signs passes using your workspace's Apple certificate upon issuance.

Explore Create a Template from JSON for raw schema imports or Template Design & Configuration to adjust visual styling in the editor.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.