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. registries.json

The registries.json file is the central database of all official and supported registries. It maps registry handles (short identifiers) to their corresponding Git repository details.

Source of Truth: The official central database is hosted at https://zillowe.pages.dev/zoi/registries.json. This can be overridden for testing or private mirrors via the ZOI_PURL_DB_URL environment variable.

Format: JSON

Structure

{
  "version": "2",
  "zoidberg": {
    "name": "Zoidberg Official Registry",
    "description": "The primary official registry for Zoi packages.",
    "git": "https://github.com/zillowe/zoidberg",
    "branch": "main"
  }
}

Fields

• version (String): Spec version. Defaults to "2".
• [registry-handle] (Object): The short name of the registry (e.g. zoidberg).
  • 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.

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"
advisory_prefix: "ZSA"
git:
  - url: "https://github.com/zillowe/zoidberg.git"
    branch: "main"
pkg:
  - url: "https://zillowe.pages.dev/pkgs/{repo}/{os}/{arch}/{version}"
pgp:
  - id: "842293159C4B03357C8328D3A75793A3E674252E"
    url: "https://zillowe.pages.dev/keys/zillowez.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 name.
• description (String): Description of the repository collection.
• 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}.
• 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.

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",
      "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"]
          }
        ]
      },
      "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).
  • 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.
  • 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",
      "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": []
      }
    }
  }
}

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.
  • 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.