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 (
.passdesignbundles). -
Apple Property List XML documents (
.plistor.xml). -
Unsigned or signed Apple Wallet packages (
.pkpasszip 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
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 / Extension | Description | Contents Extracted |
|---|---|---|
.passdesign | Apple Pass Designer bundle folder or compressed archive. | Complete pass geometry, visual field layouts, colors, and all retina PNG assets. |
.plist / .xml | Apple Property List XML format. | Field structures, label/value pairs, transit types, barcodes, and relevancy rules. |
.pkpass | Standard 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.json | Canonical 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
XXE Protection (Zero External Entity Resolution): The parser completely ignores
<!DOCTYPE>declarations, external entity definitions (SYSTEMorPUBLIC), and XML schema references. This eliminates XML External Entity (XXE) injection and Server-Side Request Forgery (SSRF) vulnerabilities. -
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
Zip Bomb Prevention: When unpacking
.passdesignor.pkpasszip files, the engine limits the total entries toMAX_ZIP_ENTRIES = 250and the uncompressed size per file toMAX_ZIP_ENTRY_BYTES = 1 MB(1048576bytes). -
4
Prototype Pollution Protection: Property keys matching
__proto__,constructor, orprototypeare 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 Type | Passinstance Model Equivalent | Normalization Behavior |
|---|---|---|
<dict> | JavaScript Object | Maps to field groups, color objects, or location dictionaries. |
<array> | JavaScript Array | Maps to field arrays (headerFields, primaryFields, etc.). |
<string> | string | Cleans up whitespace and unescapes XML entities (&, <, >). |
<integer> / <real> | number | Converted to floating point or integer numbers. |
<true/> / <false/> | boolean | Converted to standard JavaScript boolean primitives. |
<date> | ISO 8601 string | Normalized to UTC ISO-8601 timestamps (YYYY-MM-DDTHH:MM:SSZ). |
<data> | Base64 string | Base64-decoded into binary asset buffers for images. |
Pass Style to Pass Kind Normalization
| Apple Pass Style | Passinstance PassKind | Layout & Field Invariants |
|---|---|---|
storeCard | storeCard | Front layout with strip image; up to 4 secondary/auxiliary fields. |
coupon | coupon | Front layout with strip image; auxiliary fields redirected to secondary. |
eventTicket | eventTicket | Supports background texture, strip image, and iOS 18 venue companion blocks. |
boardingPass | boardingPass | Parses transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) and primary departure/arrival fields. |
generic | generic | Standard multi-purpose card layout with optional thumbnail. |
Importing via the Dashboard (Step-by-Step)
-
1
Navigate to Templates in the Passinstance Dashboard and click + New Template.
-
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.
-
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.
-
4
Continue through Step 2 (Pass Type) and Step 3 (Wallet Apps) to review or enable Google Wallet support.
-
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)
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)
{
"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 / Error | Root Cause | Resolution |
|---|---|---|
Unsupported file format | File extension does not match supported list. | Ensure your file ends in .passdesign, .plist, .xml, .pkpass, .zip, or .json. |
Missing required icon asset | The 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 exceeded | An image asset inside the archive exceeded 1 MB. | Optimize raster images using PNG crush tools or upload assets separately after template creation. |
Unsigned package notice | The 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.
