GrandPerspective XML File Format Specification

Overview

GrandPerspective is a macOS disk usage visualization tool that saves scan data in a compressed XML format. This specification documents the XML schema and file format used by GrandPerspective for storing and loading disk scan data.

File Format

• File Extensions: .xml, .gpscan
• Encoding: UTF-8
• Compression: gzip compressed
• Format Version: 7 (current)

XML Schema Structure

Root Element

<GrandPerspectiveScanDump appVersion="[app_version]" formatVersion="7">
  <!-- Scan information and data -->
</GrandPerspectiveScanDump>

Attributes:

• appVersion: Application version string (e.g., "3.4.0")
• formatVersion: XML format version (currently "7")

Scan Information Element

<ScanInfo volumePath="[volume_path]" 
          volumeSize="[volume_size]" 
          freeSpace="[free_space]" 
          scanTime="[scan_time]" 
          fileSizeMeasure="[size_measure]">
  <!-- Comments, filters, and folder structure -->
</ScanInfo>

Attributes:

• volumePath: Root path of the scanned volume (string)
• volumeSize: Total volume size in bytes (64-bit unsigned integer)
• freeSpace: Available free space in bytes (64-bit unsigned integer)
• scanTime: Scan timestamp in RFC 3339 format (e.g., "2023-12-01T10:30:00Z")
• fileSizeMeasure: Size measurement method ("logical", "physical", or "tally")

Comments Element (Optional)

<ScanComments>[comment_text]</ScanComments>

Contains user-provided comments about the scan. Character data is XML-escaped.

Filter Set Element (Optional)

<FilterSet packagesAsFiles="[true|false]">
  <Filter name="[filter_name]">
    <FilterTest name="[test_name]" inverted="[true|false]" />
    <!-- Additional filter tests -->
  </Filter>
  <!-- Additional filters -->
</FilterSet>

FilterSet Attributes:

• packagesAsFiles: Whether packages are treated as files (boolean)

Filter Attributes:

• name: Filter name (string)

FilterTest Attributes:

• name: Test name (string)
• inverted: Whether the test is inverted (boolean)

Folder Element

<Folder name="[folder_name]" 
        flags="[flags]" 
        created="[creation_time]" 
        modified="[modification_time]" 
        accessed="[access_time]">
  <!-- Files and subfolders -->
</Folder>

Attributes:

• name: Folder name (string, XML-escaped)
• flags: File system flags (integer, optional)
• created: Creation timestamp in RFC 3339 format (optional)
• modified: Modification timestamp in RFC 3339 format (optional)
• accessed: Access timestamp in RFC 3339 format (optional)

File Element

<File name="[file_name]" 
      size="[file_size]" 
      flags="[flags]" 
      created="[creation_time]" 
      modified="[modification_time]" 
      accessed="[access_time]" />

Attributes:

• name: File name (string, XML-escaped)
• size: File size in bytes (64-bit unsigned integer)
• flags: File system flags (integer, optional)
• created: Creation timestamp in RFC 3339 format (optional)
• modified: Modification timestamp in RFC 3339 format (optional)
• accessed: Access timestamp in RFC 3339 format (optional)

Data Types

Integers

• 64-bit unsigned integers: Used for file sizes and volume information
• 32-bit signed integers: Used for flags and other numeric attributes
• Boolean values: "true"/"false" or "1"/"0"

Timestamps

• Format: RFC 3339 (ISO 8601) format: yyyy-MM-ddTHH:mm:ssZ
• Timezone: UTC (Z suffix)
• Example: "2023-12-01T15:30:45Z"

Strings

• Encoding: UTF-8
• Escaping: XML character escaping applied to:
  • & → &
  • < → <
  • " → " (in attributes)
  • Non-printing characters → ?
  • Whitespace characters may be normalized to spaces

Element Ordering Rules

Within Folders

1. File elements are always output before Folder elements
2. Within the same element type (files or folders), order is not guaranteed
3. Hierarchical structure is preserved accurately

Processing Order

• Elements are processed in document order during parsing
• Internal data structures may reorder items for performance optimization
• Final order depends on tree balancing algorithms (typically size-based)

File Size Measures

The fileSizeMeasure attribute can have these values:

• "logical": Logical file size (standard file size)
• "physical": Physical disk space used (including block allocation)
• "tally": Simple count-based measurement

Format Version History

• Version 6: Introduced system path components for file names
• Version 7: Added packagesAsFiles attribute to FilterSet (current)

Implementation Notes

Compression

• XML data is compressed using gzip
• Compression is applied to the entire XML document
• Decompression is required before XML parsing

Performance Considerations

• Tree structures are balanced for optimal access performance
• Large directory trees may be reorganized during processing
• Memory usage is optimized through autorelease pool management

Compatibility

• Readers should handle missing optional attributes gracefully
• Forward compatibility: ignore unknown elements and attributes
• Backward compatibility: support older format versions

Example Structure

<?xml version="1.0" encoding="UTF-8"?>
<GrandPerspectiveScanDump appVersion="3.4.0" formatVersion="7">
  <ScanInfo volumePath="/Users" 
            volumeSize="1000000000000" 
            freeSpace="500000000000" 
            scanTime="2023-12-01T15:30:45Z" 
            fileSizeMeasure="logical">
    <ScanComments>Weekly disk usage scan</ScanComments>
    <FilterSet packagesAsFiles="true">
      <Filter name="Documents">
        <FilterTest name="extension" inverted="false" />
      </Filter>
    </FilterSet>
    <Folder name="Documents" created="2023-01-01T00:00:00Z">
      <File name="document.pdf" 
            size="1048576" 
            created="2023-11-15T10:30:00Z" 
            modified="2023-11-15T10:35:00Z" />
      <Folder name="Images">
        <File name="photo.jpg" size="2097152" />
      </Folder>
    </Folder>
  </ScanInfo>
</GrandPerspectiveScanDump>

Validation Rules

1. Root element must be GrandPerspectiveScanDump
2. Must contain exactly one ScanInfo element
3. File sizes must be non-negative integers
4. Timestamps must be valid RFC 3339 format
5. Folder hierarchy must be properly nested
6. Required attributes must be present

Error Handling

• Invalid XML structure should result in parse errors
• Missing required attributes should be reported
• Invalid data types should be handled gracefully
• Corrupted or incomplete files should be rejected

---

This specification is based on analysis of GrandPerspective source code (version 3.x) and is intended for implementing compatible tools and parsers.