- docs
- Look things up
- Reference
- Look things up
- Reference
- Metadata
- Metadata
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. |
- Per-layer override: a
strip/prefixpair in the manifest layer descriptor’s annotations, set with<ref>:strip=N,prefix=Ponocx package push. - There is no
layersfield in this schema. Per-layer layout lives in the manifest, not inmetadata.json.
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_featuresbefore serialization, so spec or push order does not affect the wire format. - RESERVED
features: the OCI v1.1.1 top-levelplatform.featuresfield 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.