This page is the technical reference for BetterZip 6’s format definition. If you want to add support for a new archive format or expose extra options of an existing one, this is the schema. For a more gentle introduction see Custom Format Definitions.

BetterZip Format Definitions

BetterZip uses JSON files to describe archive formats and the interaction between external tools and BetterZip. Built-in formats ship inside the app; you can add your own through the Helpers tab in the Settings window. Each JSON file defines how BetterZip lists, extracts, compresses, and tests a particular archive type.

This document explains every field you can use in a format definition.

Minimal Example

A read-only format that can only be opened (not created):

{
  "class": "xad",
  "format": "sit",
  "name": "StuffIt Archive",
  "tag": 110,
  "extensions": ["sit", "sitx"]
}

Full Example

A format that supports creating, extracting, testing, and splitting:

{
  "class": "tar",
  "format": "tzst",
  "name": "TAR Format, Zstandard compressed (tzst)",
  "tag": 9,
  "builtIn": true,
  "installPath": "$BUNDLE_HELPERS/zstd",
  "canSave": true,
  "canUpdate": false,

  "magicBytes": [
    {
      "start": 0,
      "hex": true,
      "bytes": "28B52FFD"
    }
  ],

  "extensions": ["tzst", "zst"],

  "extract": {
    "weight": 14
  },

  "compress": {
    "factors": [
      {
        "standardTitleTag": 1,
        "position": 1,
        "weight": 5,
        "options": ["-1"]
      },
      {
        "standardTitleTag": 2,
        "position": 2,
        "weight": 6,
        "options": []
      },
      {
        "standardTitleTag": 3,
        "position": 4,
        "weight": 75,
        "options": ["-19"]
      }
    ]
  }
}

Top-Level Fields

Identity

Capabilities

All of these default to false if omitted.

Format Behavior

These fields configure format-specific behavior. All are optional.

Tool Paths

These tell BetterZip which command-line tool to invoke.

Path variables you can use:

If the tool is installed in a standard location you can use an absolute path like /usr/local/bin/lz4.

File Type Detection

BetterZip identifies archive types in two steps: first by checking magic bytes at specific offsets in the file, then by falling back to the filename extension.

magicBytes

An array of byte patterns to check. If any pattern matches, the file is recognized as this format.

"magicBytes": [
  {
    "start": 0,
    "hex": true,
    "bytes": "504B0304"
  }
]

extensions

An array of filename extensions (without the dot) that identify this format:

"extensions": ["zip", "jar", "war", "cbz"]

Operation Dictionaries

Format-specific settings for listing, extracting, compressing, and testing are grouped under four optional top-level keys: list, extract, compress, and test. Only include the ones you need.

extract

"extract": {
  "weight": 17
}

compress

Contains compression levels, encryption options, and an optional label override.

"compress": {
  "compressionTitle": "Compression:",
  "factors": [ ... ],
  "encryptionMethods": [ ... ]
}

list

test

These are reserved for user-defined formats (class "user") that need custom command-line options for testing. See User-Defined Formats.

Compression Factors

Each entry in the factors array represents one compression level shown in the save panel dropdown.

{
  "standardTitleTag": 2,
  "position": 3,
  "weight": 12,
  "options": ["-mx=5"]
}

Standard Compression Tags

These labels are automatically localized into all supported languages.

Encryption Methods

Each entry in the encryptionMethods array represents one encryption option in the save panel.

{
  "standardTitleTag": 2,
  "position": 2,
  "options": ["-mem=AES256", "-p$PASSWORD"]
}

The fields are the same as for compression factors. Use $PASSWORD as a placeholder in options – BetterZip replaces it with the actual password at runtime.

Standard Encryption Tags

Handler Classes

The class field determines which handler processes the format. Each handler has different capabilities.

The classes zip, 7Zip, 7ZipBase, and split all use the same unified handler internally. Behavioral differences (encryption, multi-part handling, etc.) are configured through the JSON fields.

7-Zip Base Defaults (7ZipBase.json)

All formats handled by the 7za tool (zip, 7Zip, 7ZipBase, split) automatically inherit shared defaults from 7ZipBase.json. This base config provides settings that are common to all 7za-based formats:

• installPath – path to the 7za binary
• canTest – all 7za formats support integrity testing
• errors – standard error patterns for password prompts, broken archives, and permission errors

Individual format definitions override any field they specify – the base config only fills in missing values.

You can edit the base config through BetterZip > Settings > Helpers (it appears as “7-Zip Base Defaults”). Changes apply to all 7za-based formats that do not override the changed field. This is especially useful for adding custom error patterns that should apply across all 7za formats.

For most custom formats, use class "tar" (if your format is tar-based with a compressor) or "user" (for anything else).

User-Defined Formats

When using class "user", you have full control over the command-line options for every operation.

Operation Options

The list, extract, compress, and test dictionaries can each contain:

Security and shell safety

options values are passed to the tool as command-line fragments. Use only real flags, values, and the documented placeholders ($THREADS, $FACTOR, $PASSWORD, …). Do not put shell metacharacters – ` $ ; | & < > ( ) " ' \ – into an option value.

The TAR-family handlers (tgz, txz, tzst, tbz, tbr, and tar with a custom compressor) build a shell pipeline. To prevent command injection, any flag/option value that still contains a shell metacharacter after placeholder expansion is rejected at runtime: the operation is aborted and the offending value is logged, rather than executed. Legitimate options (-c9, --threads=4, -mx=9) never trigger this.

Tool paths (installPath) and the file names inside the archive are quoted automatically, so they may safely contain spaces, quotes, and other special characters – you do not need to (and should not) quote them yourself.

Placeholders

Placeholders in option strings are substituted at runtime. Available placeholders depend on the operation.

Common Placeholders (all operations)

Extract Placeholders

Compress Placeholders

Compress-Specific Fields

List-Specific Fields

Example:

"list": {
  "headerLines": 2,
  "footerLines": 0,
  "options": ["-l", "$ARCHIVE"],
  "parser": {
    "regex": "(?:\\[[^\\]]*\\])+\\s*([-dlrwxsStT]{10})\\s+\\S+\\t\\S+\\t(\\d+)\\s+(\\S+)\\t([^\\t]+)\\t(.+)",
    "template": "path=$5\tattr=$1\tunco=$2$3\tcomp=0\ttime=$4"
  }
},
"extract": {
  "weight": 18,
  "options": ["-x", "$ARCHIVE", "-g $FILES"]
},
"compress": {
  "splitOption": "-s $VOLUME_SIZE",
  "options": ["-c", "$ARCHIVE", "$FACTOR", "$ENCRYPTION", "$SPLIT", "-g $FILES"],
  "factors": [ ... ],
  "encryptionMethods": [ ... ]
},
"test": {
  "options": ["-t", "$ARCHIVE"]
}

Error Handling

User-defined formats can include an errors array to map tool output to meaningful error messages. The errors array can appear in two places:

• Top level – applies to all operations (list, extract, test, compress).
• Inside an operation dictionary (list, extract, test, compress) – applies only to that operation.

If both exist, the operation-specific errors array is used exclusively – the two arrays are not combined.

"errors": [
  {
    "recognize": ["Wrong password"],
    "standardError": "password",
  },
  {
    "recognize": ["Sub items Errors", "Headers Error", "ERRORS:"],
    "standardError": "broken"
  },
  {
    "recognize": "ERROR: Operation not permitted",
    "standardError": "permission"
  },
  {
    "recognize": "ERROR: Need more memory",
    "userMessage": "The operation needs more memory to succeed.",
    "continue": false
  }
]

Encryption Detection

The encryptionDetection array tells BetterZip how to detect encryption from 7z listing output. Each entry matches a pattern in the compression method string reported by 7za.

"encryptionDetection": [
  { "pattern": "ZipCrypto", "method": 1 },
  { "pattern": "AES", "method": 2 }
]

For 7z archives with optional header encryption:

"encryptionDetection": [
  { "pattern": "7zAES", "method": 2, "headerEncryptionMethod": 3 }
]

Multi-Volume Naming Schemes

BetterZip automatically detects multi-volume archives using these naming patterns:

When a user opens a later volume, BetterZip automatically redirects to the first volume and scans for all parts.

The numberedParts scheme requires an opt-in flag because name.1.ext patterns are common in non-archive files (e.g. report.1.pdf). Only enable it for formats whose tools actually produce this naming convention.

Tips

• Tag numbers: Pick a tag number that is not already used. Tag numbers below 1000 are reserved. Use numbers above for custom formats.
• Testing your format: After adding a JSON file in BetterZip > Settings > Helpers, your format should be recognized when opening archives and it should appear in the save panel’s and save preset configuration’s format drop-down (if canSave is true).
• Compression factors: You need at least one entry in factors if your format supports saving. If the format has only one compression level, include a single entry.
• Magic bytes: If you do not know the magic bytes for your format, leave the array empty and rely on file extensions only.
• Tool path: Make sure the tool is installed and the path is correct. BetterZip will show the format as unavailable if it cannot find the tool.