Manifest specification

The simplest way to read the spec is to start with a real manifest. The example below is shortened — a production manifest typically contains hundreds of file entries.

{
  "schemaVersion": 1,
  "name": "the-veiled-eclipse",
  "displayName": "The Veiled Eclipse",
  "version": "1.4.2",
  "game": "7d2d",
  "gameVersion": "1.0.0",
  "publisher": "darkrising.gg",
  "publishedAt": "2026-05-10T18:42:00Z",
  "files": [
    {
      "path": "Mods/EclipseLighting/ModInfo.xml",
      "sha256": "9f1ce8a3...ab4e",
      "size": 1842
    },
    {
      "path": "Mods/EclipseLighting/Config/lights.xml",
      "sha256": "5e2a1f88...d091",
      "size": 5310
    }
  ],
  "signature": {
    "algo": "ed25519",
    "publicKeyId": "darkrising.gg/main",
    "value": "f0d3a1...7c81"
  }
}

The signature is computed over a canonical JSON serialization of the manifest with the signature field removed. Canonical means:

• UTF-8 encoding.
• Object keys sorted lexicographically.
• No whitespace between tokens (no indentation, no trailing newlines).
• Integers serialized without a decimal point; floats are not used in the manifest schema.

The PackRelay CLI does this for you. If you implement manifest signing yourself, two manifests that differ only in key order or whitespace MUST produce the same signature input.

The algorithm is Ed25519. The signature is computed over the canonical bytes; value is the lowercase hex encoding of the 64-byte signature.

Each element of the files array.

Pack versions are semver. The launcher considers a version upgrade required when any segment changes — there is no skipping. A player on 1.4.1 joining a server attached to 1.4.2 will sync.

Pre-release suffixes (1.4.2-beta.1) are honored but participating launchers must opt in to pre-release channels via the upcoming public API.

schemaVersionis independent of the pack's version. It bumps only when this specification gets a breaking change to the manifest shape itself.

A launcher MUST reject a manifest if any of the following are true:

• The signature.publicKeyId is not registered on PackRelay.cloud, or has been revoked.
• The Ed25519 verification fails.
• publishedAt is in the future relative to a trusted clock source (allow a small skew).
• Any files[].path escapes the pack root (contains.. segments or absolute prefixes).
• A downloaded file's computed SHA-256 does not match the manifest entry.
• schemaVersion exceeds the version the launcher supports.

Schema version 2 is an additive evolution of v1. It adds optional fields that record where a pack's bytes originally came from (Nexus Mods, GitHub Releases, 7DaysToDieMods, or explicitly self-hosted) so a downloader can verify provenance and inherit any trust signals the upstream source provides (e.g. a malware-scan attestation).

Every v1 manifest is a valid v2 manifest minus the new fields. Conversely, a v2 manifest with no sources array and no sourceRef on any file behaves identically to v1. The differences:

• schemaVersion changes from 1 to 2.
• Optional top-level sources array — a normalized catalog of upstream binaries this pack bundles. Up to 500 entries. Many files can share one source entry (a 50-file mod from a single GitHub Release zip = 1 source, 50 files referencing it).
• Optional sourceRef on each FileEntry — a pointer to a sources[].id. Files without a sourceRef are treated as self-hosted with no recorded upstream.

The signing contract is identical to v1: the signature covers the canonical-JSON serialization of the manifest minus its signature field. New fields just become part of the signed message.

Example

{
  "schemaVersion": 2,
  "name": "the-veiled-eclipse",
  "displayName": "The Veiled Eclipse",
  "version": "1.4.2",
  "game": "7d2d",
  "gameVersion": "1.0.0",
  "publisher": "darkrising.gg",
  "publishedAt": "2026-05-10T18:42:00Z",
  "sources": [
    {
      "id": "eclipse-lighting-v142",
      "source": "github",
      "owner": "darkrising-gg",
      "repo": "EclipseLighting",
      "releaseTag": "v1.4.2",
      "assetName": "EclipseLighting_v1.4.2.zip",
      "sha256": "3c9d0a51...e7f2",
      "discoveredVia": "7dtm",
      "scanAttestation": {
        "scannedAt": "2026-04-29T00:00:00Z",
        "scanner": "Norton 360"
      }
    }
  ],
  "files": [
    {
      "path": "Mods/EclipseLighting/ModInfo.xml",
      "sha256": "9f1ce8a3...ab4e",
      "size": 1842,
      "sourceRef": "eclipse-lighting-v142"
    },
    {
      "path": "Mods/EclipseLighting/Config/lights.xml",
      "sha256": "5e2a1f88...d091",
      "size": 5310,
      "sourceRef": "eclipse-lighting-v142"
    }
  ],
  "signature": {
    "algo": "ed25519",
    "publicKeyId": "darkrising.gg/main",
    "value": "f0d3a1...7c81"
  }
}

FileEntry — added fields in v2

Source — common fields

Every element of the sources array carries these fields. The source discriminator picks which per-variant fields apply (Nexus / GitHub / 7DTM / legacy-blob).

source: "nexus"

The upstream binary lives on Nexus Mods. Publishing requires the publisher's Premium account API key (Nexus only authorizes file downloads via Premium).

source: "github"

The upstream binary is a GitHub Release asset. Public repos work without authentication; private repos need a Personal Access Token on the publisher account.

source: "7dtm"

The upstream binary is cataloged on 7DaysToDieMods. Many 7DTM-cataloged mods actually host their bytes on GitHub; in that case the publisher chooses either source: "github" with discoveredVia: "7dtm" (preferred, records the catalog reference) or source: "7dtm" (treats 7DTM as the primary source).

source: "legacy-blob"

No additional fields. Use when the bytes don't map to any of the recognized upstream sources — the publisher uploaded them directly to PackRelay's blob cache as the original source. Also the implicit behavior for v2 files that omit sourceRef.

ScanAttestation

Optional sub-object on any source variant. Records a malware-scan result from the catalog that hosts the binary. Surfaced in the launcher's pack-detail UI as a trust signal.

Schema version 3 is v2 made game-aware. Its game can be any game PackRelay supports, and the game decides where file paths are rooted, which sources a pack may draw on, and which mod loader it runs on. Paths, sources and sourceRef work exactly as in v2, and the signature is computed the same way.

A launcher that only knows 7 Days to Die never sees a v3 manifest for another game: the API only serves one to a client that names the game (?game=valheim), and a launcher MUST refuse a manifest for a game it doesn't support, like any unknown schemaVersion.

Example

{
  "schemaVersion": 3,
  "name": "longship-crew",
  "displayName": "Longship Crew",
  "version": "2.1.0",
  "game": "valheim",
  "gameVersion": "0.220.5",
  "framework": {
    "id": "bepinexpack-valheim",
    "version": "5.4.2351"
  },
  "publisher": "fjord.example",
  "publishedAt": "2026-09-30T12:00:00Z",
  "sources": [
    {
      "id": "planteverything-1-19-1",
      "source": "thunderstore",
      "community": "valheim",
      "namespace": "Advize",
      "name": "PlantEverything",
      "version": "1.19.1",
      "sha256": "b61f0c2e...94d7"
    }
  ],
  "files": [
    {
      "path": "plugins/Advize-PlantEverything/PlantEverything.dll",
      "sha256": "0d4c7e19...a3b8",
      "size": 88064,
      "sourceRef": "planteverything-1-19-1"
    },
    {
      "path": "config/advize.PlantEverything.cfg",
      "sha256": "71e9b0d2...5c10",
      "size": 4217,
      "sourceRef": "planteverything-1-19-1"
    }
  ],
  "signature": {
    "algo": "ed25519",
    "publicKeyId": "fjord.example/main",
    "value": "9a02c4...e61f"
  }
}

Games

• "7d2d", 7 Days to Die: paths are rooted at Mods/, there is no framework, and sources are nexus, github, 7dtm and legacy-blob. The only game a v1 or v2 manifest can be for.
• "valheim", Valheim: paths are rooted at BepInEx/, the framework is bepinexpack-valheim (BepInExPack), and sources are thunderstore (community valheim), nexus (game valheim), github and legacy-blob. gameVersion is x.y.z, such as 0.220.5.

Root fields: changed and added in v3

A launcher installs the framework from GET /api/v1/frameworks/<id>/<version>, which lists its files by hash; they download from the same file endpoint as pack files, and are verified the same way. For Valheim that is BepInExPack, laid into the game folder.

source: "thunderstore"

The upstream package is on Thunderstore. PackRelay fetches it once and hosts the files itself, so players never download from Thunderstore. The files are laid out as r2modman lays them out: each package's plugins in plugins/<Namespace-Name>/, its config in the shared config/.

• How it works — the protocol from the player flow side.
• For Creators — what publishing through PackRelay looks like end-to-end.
• Public API — read access to manifests and pack metadata (coming with v1).