Specifications

This document outlines the v2 specifications for the core metadata files used by the Zoi package manager to manage registries, repositories, and security advisories.

General Design

All Zoi specification files support a version field to ensure future compatibility. Version "2" is the current standard for Zoi Specification v2. There is no backward compatibility with version "1".

1. Built-in Registry Definition

The official and supported registries are defined as built-in YAML files embedded into the Zoi binary at compile time. Each file is named <handle>.yaml and ships with the tool, so registry resolution never depends on fetching a remote central database at runtime.

When you run zoi sync set <handle> or zoi sync add <handle>, Zoi resolves the handle against these built-in definitions and populates the matching metadata automatically.

Format: YAML

Example (zoidberg.yaml)

version: "2"
handle: "zoidberg"
name: "Zoidberg"
description: "Official Zoi packages repository"
git: "https://gitlab.com/zillowe/zillwen/zusty/zoidberg"
branch: "main"
type: "official"
set: true

Fields

• version (String): Spec version. Defaults to "2".
• handle (String): The short, unique name of the registry (e.g. zoidberg). This is what users reference in @handle/repo/package and zoi sync commands.
• name (String): Full display name of the registry.
• description (String): A short description of the registry's purpose.
• git (String): The Git repository URL where the registry is hosted.
• branch (String): The default branch to clone or fetch from.
• type (String): The trust level of the registry. official for first-party Zoi registries; third-party for all others. Third-party registries trigger a warning when you add them via zoi sync.
• set (Boolean): Marks the single registry used as the default (set) registry. Exactly one built-in registry may set this to true.

2. repo.yaml

The repo.yaml file defines the configuration for a specific package repository within a registry. It configures paths, database locations, PGP keys, and sub-repositories (like main, extra, testing).

Format: YAML

Structure

version: "2"
name: "Zoidberg"
description: "Main repository configuration"
handle: "zoidberg"
advisory_prefix: "ZSA"
git:
  - type: "main"
    url: "https://gitlab.com/zillowe/zillwen/zusty/zoidberg.git"
  - type: "mirror"
    url: "https://github.com/zillowe/zoidberg.git"
pkg:
  - type: "main"
    url: "https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa"
    hash: "https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.hash"
    pgp: "https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.sig"
    size: "https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.size"
    files: "https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.files"
pgp:
  - name: "zillowe-main"
    key: "https://zillowe.pages.dev/keys/zillowe-main.asc"
repos:
  - name: "core"
    type: "official"
    active: true
  - name: "main"
    type: "official"
    active: true

Fields

• version (String): Spec version. Defaults to "2".
• name (String): Repository/Registry display name.
• description (String): Description of the repository collection.
• handle (String): Short identifier used as the registry handle. This is what users see in @handle/repo/package install syntax.
• advisory_prefix (String, Optional): Prefix used for security advisories (e.g. ZSA).
• git (List of Objects): Git mirrors for the repository content.
• pkg (List of Objects): Package download mirrors. Supports placeholders like {repo}, {os}, {arch}, {version}, {id}.
• delta (List of Objects): Delta patch mirrors for bandwidth-efficient upgrades. Supports placeholders like {repo}, {os}, {arch}, {version}, {id}.
• pgp (List of Objects): Trusted PGP keys for signature verification.
• repos (List of Objects): Sub-repositories contained within this registry.
  • name (String): Name of the sub-repo (e.g. main).
  • type (String): Type of the repository (official, community, unofficial, testing, archive).
  • active (Boolean): Whether the sub-repo is active and should be read.

Delta Patches

Zoi supports bandwidth-efficient upgrades using .zdelta patches (bsdiff-based deltas applied to the content-addressed pool). When a previous version of a package is cached and a delta is available from the registry, Zoi will download the delta patch, verify its hash and signature, apply it to the cached archive, and install the rebuilt package.

Delta patches are configured explicitly in the delta section of repo.yaml (not auto-derived from pkg URLs). Each DeltaLink supports the same mirror types as PkgLink (main, mirror).

Required fields for secure delta upgrades:

• url: The delta patch URL template (must contain {version} placeholder for the target version).
• hash: URL to the delta patch's SHA-256 hash file (mandatory for integrity).
• pgp: URL to the delta patch's detached PGP signature (recommended for authenticity).
• size: URL to the delta patch's size file (for progress reporting).

Example delta configuration:

delta:
  - type: main
    url: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta
    pgp: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.sig
    hash: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.hash
    size: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.size
  - type: mirror
    url: https://mirror.example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta
    hash: https://mirror.example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta.hash

When upgrading, Zoi looks up the delta URL using the target version (the version being upgraded to). The delta patch is verified against its hash and signature before application. If no delta is configured, unavailable, or fails verification, Zoi silently falls back to downloading the full archive.

When the cached version is more than one release behind the target, Zoi applies deltas sequentially: each intermediate delta is downloaded, verified, and applied on top of the previously rebuilt archive until the target version is reached. The number of steps is limited by the max_delta_steps user config (default 3); anything beyond that falls back to a full download.

3. advisories.json / *.sec.yaml

These files define the security advisories and vulnerabilities affecting packages. advisories.json is the registry index, whereas files ending in .sec.yaml specify individual Advisory items.

Format: JSON (for advisories.json) or YAML (for .sec.yaml)

Structure (Advisory Registry Index in advisories.json)

{
  "version": "2",
  "last_id": 42,
  "year": 2026,
  "advisories": {
    "ZSA-2026-C0042": "core/curl/ZSA-2026-C0042.sec.yaml"
  }
}

Structure (Individual Advisory)

id: "ZSA-2026-C0042"
package: "curl"
sub_packages: ["libcurl"]
summary: "Buffer overflow in curl"
severity: "high"
cvss: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
affected_range: "<8.4.0"
fixed_in: "8.4.0"
description: "A heap buffer overflow was found in curl when processing HTTP headers..."
references:
  - "https://curl.se/docs/CVE-2023-38545.html"

Fields (Individual Advisory)

• id (String): The unique advisory identifier.
• package (String): The name of the affected package.
• sub_packages (List of Strings, Optional): The specific sub-packages affected.
• summary (String): A short summary of the vulnerability.
• severity (String): The severity level (low, medium, high, critical).
• cvss (String, Optional): The CVSS vector string.
• affected_range (String): SemVer range affected (e.g. <1.2.3).
• fixed_in (String, Optional): The version where the issue was fixed.
• description (String): Detailed description of the vulnerability.
• references (List of Strings, Optional): URLs to external advisories, CVEs, or pull requests.

4. packages.json

The packages.json file is generated by a registry to list all packages it contains. In version 2, it uses @repo/package keys for better identification.

Format: JSON

Structure

{
  "version": "2",
  "packages": {
    "@core/curl": {
      "repo": "core",
      "repo_type": "official",
      "version": "8.4.0",
      "epoch": 0,
      "revision": "1",
      "description": "Command line tool and library for transferring data with URLs",
      "sub_packages": ["libcurl", "headers"],
      "main_sub_packages": ["libcurl"],
      "dependencies": {
        "runtime": ["zoi:openssl", "zoi:zlib"],
        "build": [
          {
            "type": "source",
            "packages": ["zoi:gcc", "zoi:make"]
          }
        ],
        "test": ["zoi:valgrind"]
      },
      "vuln": [
        {
          "id": "ZSA-2026-C0042",
          "severity": "high",
          "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
          "affected_range": "<8.4.0",
          "fixed_in": "8.4.0",
          "summary": "Buffer overflow in curl"
        }
      ]
    }
  }
}

Fields

• version (String): Spec version. Defaults to "2".
• packages (Object): Map of @repo/package identifiers to their metadata.
  • repo (String): The repository tier (e.g. core).
  • repo_type (String): The type of repository (official, community).
  • version (String): The latest stable version (SemVer).
  • epoch (Integer): Forced version precedence.
  • revision (String): Package revision number.
  • description (String, Optional): A short description of the package.
  • sub_packages (List of Strings): All sub-packages provided by this definition.
  • main_sub_packages (List of Strings): Default sub-packages to install.
  • dependencies (Object): Detailed dependencies for v2.
    • runtime (List of Strings): Runtime dependency strings.
    • build (List of Objects): Build dependency groups.
    • test (List of Strings): Test dependency strings.
  • vuln (List of Objects): Known vulnerabilities (Mini-Advisory format).

5. zoi.lock

The zoi.lock file ensures reproducibility by pinning the exact state of a project's dependencies.

Format: JSON

Structure

{
  "version": "2",
  "packages_hash": "sha512-...",
  "registries_hash": "sha512-...",
  "registries": {
    "zoidberg": {
      "url": "https://github.com/zillowe/zoidberg.git",
      "revision": "a1b2c3d4..."
    }
  },
  "installed_packages": {
    "@core/curl": {
      "repo": "core",
      "repo_type": "official",
      "version": "8.4.0",
      "epoch": 0,
      "revision": "1",
      "registry": "zoidberg",
      "why": "direct",
      "description": "...",
      "type": "pre-compiled",
      "install_method": "pre-built",
      "installed_sub_packages": ["libcurl"],
      "platform": "linux-amd64",
      "hash": "sha512-...",
      "dependencies": {
        "runtime": ["zoi:openssl", "zoi:zlib"],
        "build": [],
        "test": []
      }
    }
  }
}

Fields

• version (String): Spec version. Defaults to "2".
• packages_hash (String): SHA-512 hash of the ./.zoi/pkgs/store directory.
• registries_hash (String): SHA-512 hash of the ./.zoi/pkgs/db directory.
• registries (Object): Map of registry handles to their pinned state.
  • url (String): Registry Git URL.
  • revision (String): The exact Git commit hash (SHA-1).
• installed_packages (Object): Map of @repo/package identifiers to installation details.
  • version (String): The exact version installed.
  • epoch (Integer): Forced version precedence.
  • why (String): direct or dependency.
  • hash (String): SHA-512 hash of the specific package's store directory.
  • platform (String): The platform identifier (e.g. linux-amd64).
  • dependencies (Object): The specific dependencies resolved and installed for this package.