ppkg File Format Specification

Version: 1.0.0

The ppkg (Portable Package) file format is a container format for storing compressed data along with metadata. This specification defines the structure and usage of ppkg files.

File Format Overview

A ppkg file consists of the following components:

Magic Bytes: A 4-byte sequence that serves as a signature to identify the file format. It is always set to "ppkg" in UTF-8-encoded bytes.
Metadata Length: A 4-byte integer indicating the length of the metadata section in bytes. This length is encoded in little-endian format.
Metadata: A JSON-formatted metadata section containing information about the package.
Compressed Data: The compressed data payload of the package.

Metadata Format

The metadata section is a JSON object with the following structure:

{
  "PackageName": "Pixel.Pkg",
  "PackageVersion": "2.0.0",
  "PackageLicense": "MIT",
  "PackageDescription": "C# Implementation of the ppkg file format",
  "AuthorName": "Pixel",
  "AuthorContacts": null,
  "FormatVersion": "1.0.0",
  "Type": null,
  "MetaMeta": null
}

PackageName (string): The name of what's packaged.
PackageVersion (string): The version of what's packaged.
PackageLicense (string): The license of what's packaged.
PackageDescription (string): What's packaged, in more details.
AuthorName (string): The author of the package.
AuthorContacts (string[]): The contact(s) of the author (can also be used for multiple authors.
FormatVersion (string): A version string specifying the format version of the ppkg file.
Type (string): What kind of additional metadata this package contains.
MetaMeta (object): Additional metadata fields included as needed for specific applications or use cases.

Creating a ppkg File

To create a ppkg file, follow these steps:

Create the metadata object as a JSON-formatted string.
Encode the metadata object in UTF-8 to obtain the metadata bytes.
Compress the data that you want to package using the Deflate compression algorithm.
Concatenate the magic bytes, metadata length (encoded in little-endian), metadata bytes, and compressed data.

Reading a ppkg File

To read a ppkg file, follow these steps:

Read the first 4 bytes to verify that they match the magic bytes "ppkg" in UTF-8-encoded bytes.
Read the next 4 bytes as an integer to determine the length of the metadata section.
Read the next metadata_length bytes as the metadata section in UTF-8 format.
Deserialize the metadata JSON to obtain package metadata.
Read the remaining bytes as the compressed data payload.