Machine-Readable Manifest¶

Artifact — instantiates Open Reuse Publication Infrastructure

A structured, parseable descriptor shipped with an artifact that exposes its identity, version, license, dependencies, and provenance so tools can resolve and reuse it without a human in the loop.

A human-readable page can orient a person, but a machine can't read a page. Machine-Readable Manifest is the small structured file that travels with an artifact and states, in fields a tool can parse, what the artifact is: its name and version, its license, the formats it ships in, the other artifacts it depends on, checksums, endpoints, and a provenance stanza. Its defining move is to separate the description of a package from the payload itself, so a resolver, installer, or harvester can decide whether and how to use the artifact — resolve its dependencies, check the license, pick the right version — before fetching a single byte of content and without asking a person. It describes the package, not the meaning of what's inside it; that contract lives elsewhere.

Example¶

A city publishes an open transit dataset and wants analytics vendors to consume it automatically. Alongside the data it ships a datapackage.json-style manifest (a real convention: Frictionless Data's Data Package). The manifest declares name: metrocity-transit, version: 2026.3, license: CC-BY-4.0, the three resource files with their formats and per-file SHA-256 checksums, the upstream feeds it is built from, and a provenance block naming the publishing office and build date. A downstream ETL job points at the manifest, reads that the license permits redistribution, sees the version is newer than the copy it holds, resolves the declared dependency on a stops registry, and wires the dataset in — no email to the city's data team, no guessing at the format. When the city cuts version 2026.4, the only thing that has to change for every consumer to notice is one field in the manifest.

How it works¶

The manifest is declarative and fixed-shape: a known set of fields in a format tools already parse (JSON, TOML, YAML, XML). It references the payload rather than containing it, so it stays small and cheap to fetch and index. What makes it more than a metadata dump is that its fields are resolvable — the dependency entries name real, addressable artifacts and version constraints a resolver can walk transitively, and the identity/version/license fields are the exact keys registries, installers, and caches key on. The manifest is the seam where a pile of files becomes a resolvable dependency.

Tuning parameters¶

Field set / richness — a minimal manifest (identity, version, license) versus a rich one (checksums, endpoints, provenance, capabilities). More fields unlock more automation but add authoring burden and more surface to fall out of date.
Vocabulary choice — reuse an established manifest schema (package.json, pyproject.toml, Cargo.toml, Data Package) or define a bespoke one. A standard schema buys instant tooling support; a bespoke one fits an odd artifact at the cost of isolation.
Dependency pinning granularity — exact pinned versions versus permitted ranges. Pinning maximizes reproducibility; ranges let consumers pick up fixes automatically but invite drift.
Embedded vs. referenced — inline small metadata or link out to it. Inlining is self-contained; referencing keeps the manifest lean but adds fetches.
Validation strictness — whether a consumer rejects a manifest that fails schema validation, or accepts partial records.

When it helps, and when it misleads¶

Its strength is that it converts negotiation into parsing: automated dependency resolution, reproducible installs, and bulk indexing all become possible the moment identity, version, and dependencies are machine-legible. It is the field that lets ten thousand consumers upgrade in lockstep off one edit.

Its central failure mode is drift — a hand-maintained manifest that quietly diverges from the artifact. A manifest that declares MIT over code that is actually GPL, or lists a dependency that was swapped out two versions ago, is worse than none, because tools trust it and act on it without a human to catch the mismatch. The tidy structure also invites padding fields to look complete. The discipline that guards against this is to generate manifest fields from the build's source of truth and validate them in CI, treating a manifest-vs-reality mismatch as a build failure — the same instinct behind a software bill of materials, which is only useful if it is derived rather than asserted.^[1]

How it implements the components¶

Machine-Readable Manifest fills the structured-metadata side of the archetype — the components a parseable descriptor can produce, not the ones that verify or host it:

machine_readable_package_schema — it is the manifest: the structured record exposing identity, version, license, formats, checksums, and endpoints in a shape tools parse.
citation_and_dependency_map — its dependency stanza is the resolvable map of what this artifact requires and how it should be referenced, which resolvers and citation tools walk.

It declares provenance and checksum fields but does not verify them — that authenticity check is Integrity Checksum or Signature. It does not describe the meaning of the payload (the schema/API contract belongs to Schema or API Specification Publication), mint the identifier it records (Persistent Identifier Minting), or host the artifact (Public Artifact Registry).

Instantiates: Open Reuse Publication Infrastructure — the manifest is the parseable descriptor the rest of the publication is indexed and resolved by.
Consumes: Persistent Identifier Minting supplies the stable identity the manifest records.
Sibling mechanisms: Integrity Checksum or Signature · Schema or API Specification Publication · Persistent Identifier Minting · Public Artifact Registry · Package Manager Distribution · Open License Declaration · Semantic Versioning or Release Scheme · Changelog and Release Notes · Deprecation Notice Feed · Example Corpus or Test Fixture · Reference Implementation Repository · Metadata Harvesting Endpoint · Community Contribution Guidelines

Notes¶

A manifest is a declaration, not proof: it says what the artifact claims to be. To make those claims trustworthy to a stranger — the right bytes, from the right author — pair it with Integrity Checksum or Signature, which signs the manifest and the payload it points to.

References¶

[1] A software bill of materials (SBOM) is a manifest specialized to enumerate an artifact's dependency tree for supply-chain review. Its value depends entirely on being generated from the build rather than hand-asserted — the same drift risk that makes any manifest untrustworthy when maintained by hand. ↩