REFERENCE · 08

The payload manifest, field by field.

Every payload is self-describing: an in-image manifest at /__tpkg__/manifest.yaml declares what the payload is, what it provides, and what it requires. The press writes it, the loaders read it, and a versioned JavaScript Object Notation (JSON) schema pins it. This page is that schema, field by field.

The shape.

The manifest carries five top-level sections, with provides arriving by kind: identity and requires always; materialize, library_aliases, and checks when they apply.

identity:
  schema_version: 1
  kind: app            # app | data | toolkit | runtime | language
  name: my-app
  version: 1.2.3
provides:              # shape depends on kind — see below
requires: []

identity.

Field Meaning

Field	Meaning
`schema_version`	The manifest schema generation; readers reject what they cannot parse by name rather than guessing.
`kind`	One of app, data, toolkit, runtime, language. The kind selects the `provides` shape.
`name` / `version`	The payload’s identity. Versions are free-form — semver and datever payloads both exist.
`producer`	This names what built the image: the tool and its version.
`created`	This carries the creation timestamp in RFC 3339 rendering.
`source`	This carries the provenance: the source tree digest, the commit, and the builder.
`digest`	This carries the tree hash and the blob digest — the integrity anchors for the image.
`signing`	The signing state; unsigned is first-class.
`encryption`	The encryption state; none is the default.
`annotations`	These are free-form key-value pairs; unknown keys are preserved on round-trip.

schema_version

The manifest schema generation; readers reject what they cannot parse by name rather than guessing.

kind

One of app, data, toolkit, runtime, language. The kind selects the provides shape.

name / version

The payload’s identity. Versions are free-form — semver and datever payloads both exist.

producer

This names what built the image: the tool and its version.

created

This carries the creation timestamp in RFC 3339 rendering.

source

This carries the provenance: the source tree digest, the commit, and the builder.

digest

This carries the tree hash and the blob digest — the integrity anchors for the image.

signing

The signing state; unsigned is first-class.

encryption

The encryption state; none is the default.

annotations

These are free-form key-value pairs; unknown keys are preserved on round-trip.

provides, by kind.

An app provides commands. Each entrypoint names the command (the shim registers under it), the in-image absolute path, optional default arguments, and an optional runtime requirement; the payload also declares its platforms and capabilities:

provides:
  entrypoints:
    - {name: myapp, path: /bin/myapp, runtime_requirement: {engine: ruby, constraint: ">= 3.3, < 5.0"}}
  platforms: ["aarch64-macos", "x86_64-linux-gnu"]
  capabilities: {exec: true, read: true, host: {default: open}}

A runtime provides an engine: the engine name, its version, the application binary interface (ABI) line, the platform, and the implementation (which Matz’s Ruby Interpreter (MRI)-compatible engine this build is). It also carries the environment the interpreter expects and the spawn surface — the commands this runtime boots as a separate process for a composed payload.

A data payload provides content for consumers: suggested mount semantics (the mount decision always belongs to the consumer’s manifest) and the consumer list.

Capabilities are honest by kind: an app or a runtime may exec: true; a data payload must declare exec: false and read: true. The optional host block is the baked jail policy — a default directive, explicit mounts, and argument-file handling.

requires.

Four requirement forms exist, selected by the kind field of the requirement:

Form	Meaning
engine requirement	The form names an engine and a constraint — the runtime requirement an entrypoint can also carry inline.
platform-scoped dependency	The form carries a kind, a name, a constraint, an optional triplet list, and a mount point — for toolkit dependencies pinned per platform.
plain dependency	The form carries a kind, a name, a constraint, and a mount point.
engine-implementation requirement	The form carries an engine plus a required implementation and constraint, with an expose clause.

Form

Meaning

engine requirement

The form names an engine and a constraint — the runtime requirement an entrypoint can also carry inline.

platform-scoped dependency

The form carries a kind, a name, a constraint, an optional triplet list, and a mount point — for toolkit dependencies pinned per platform.

plain dependency

The form carries a kind, a name, a constraint, and a mount point.

engine-implementation requirement

The form carries an engine plus a required implementation and constraint, with an expose clause.

materialize and library aliases.

materialize lists absolute in-image paths that the loader copies to the host before the run — the answer for a native library that reads through its own file descriptor, below the interposition layer. library_aliases declares windows bare-name aliases so the loader’s closure walk can resolve them.

checks.

The checks: section is the payload’s own acceptance contract. Each check names an entry — an in-image executable path, or the reserved spelling self for kind runtime — with arguments, fixtures, expectations, a timeout, and an optional OS-family filter. A check may add host needs for its own run and declare composition prerequisites; unmet prerequisites skip the check, never fail it. The task walkthrough is the Check a payload guide.

Where the schemas live.

The versioned JSON schemas ship in the product repository under schema/ — the payload manifest, the package manifest block, the compose document, and the bench suite. A manifest that names a schema the reader does not know is rejected by name, never guessed.