Skip to content

Metadata

Every OCX package carries a metadata.json that declares how OCX extracts and configures it at install time. OCX stores it in the object store after installation and reads it whenever the package environment is resolved.

Format

The metadata file is a JSON object with a type discriminator. Only the bundle type exists, and OCX rejects an unknown type with an error.

Top-Level Structure

Field Type Required Description
type string Yes Discriminator tag. Must be "bundle".
version integer Yes Format version. Currently 1.
strip_components integer No Leading path components to strip during extraction. See Extraction.
env array No Environment variable declarations.
dependencies array No Package dependencies.
entrypoints object No Named entry points, keyed by command name.
binaries array No Declared executable names the package puts on PATH.
integrations object No Vendor-namespaced configuration blocks for tools OCX does not model.

Minimal Example

A package with no environment variables and no extraction options.

{
"$schema": "https://ocx.sh/schemas/metadata/v1.json",
"type": "bundle",
"version": 1
}

Full Example

A package, here acme/mytool, with environment variables, archive stripping, a dependency, declared executables and named entry points.

{
"$schema": "https://ocx.sh/schemas/metadata/v1.json",
"type": "bundle",
"version": 1,
"strip_components": 1,
"env": [
{
"key": "PATH",
"type": "path",
"required": true,
"value": "${self.installPath}/bin",
"visibility": "public"
},
{
"key": "MYTOOL_HOME",
"type": "constant",
"value": "${self.installPath}",
"visibility": "public"
},
{
"key": "LD_LIBRARY_PATH",
"type": "path",
"required": false,
"value": "${self.installPath}/lib"
}
],
"dependencies": [
{
"identifier": "ghcr.io/acme/runtime:13@sha256:a1b2c3d4e5f6..."
}
],
"binaries": ["mytool", "mytool-format"],
"entrypoints": {
"mytool": {},
"fmt": { "command": "mytool-format" }
}
}

The mytool entry point dispatches to a binary named mytool, and fmt dispatches to mytool-format. binaries declares separately which executables the interface PATH carries, as Executables describes.

Extraction

Extraction options control how OCX unpacks the package layers into the object store.

strip_components

strip_components removes leading path components when the package is assembled, like tar --strip-components. It is the package-wide default for any layer that carries no layout of its own.

Value Effect
omitted / 0 Extract as-is.
1 Remove one leading directory: node-v24.21.0-linux-x64/bin becomes bin.
2 Remove two: a/b/bin becomes bin.

See layer layout for the grammar and the fallback chain.

JSON Schema

The schema is generated from the Rust source types and published at https://ocx.sh/schemas/metadata/v1.json.

  • Editor integration, local generation and validation: see Schemas.

OCI Platform Fields

The OCI platform descriptor, the platform object in an image index entry, is not part of metadata.json. The publisher declares it at push time and OCX consumes it at index resolution time.

See Platforms for the string form (--platform, lock keys, the build receipt’s platform field) and the compatibility relation.

os.features and libc tagging

OCX encodes the libc family requirement of a Linux binary in the os.features array of the platform descriptor. A static binary carries no os.features declaration, and the absent or empty set matches every Linux host.

Value Meaning
libc.glibc Binary links GNU libc (glibc). Requires glibc on the installing host.
libc.musl Binary links musl libc. Requires musl on the installing host.
{
"platform": {
"architecture": "amd64",
"os": "linux",
"os.features": ["libc.glibc"]
}
}
  • Normalization: OCX sorts and deduplicates os_features before serialization, so spec or push order does not affect the wire format.
  • RESERVED features: the OCI v1.1.1 top-level platform.features field is RESERVED. OCX never serializes it and drops any value found in a foreign manifest with a warning.

See libc Differentiation for the publisher workflow.