Skip to content

Metadata: Dependencies

The dependencies array of metadata.json declares the packages a package needs at runtime.

Dependencies

Every dependency identifier is pinned by OCI digest in the published form. The same dependency graph is therefore reproduced on every machine regardless of the current registry state.

See Dependencies for the pin rules and Declare dependencies for the publisher workflow.

Dependency Entry

Field Type Required Description
identifier string Yes Identifier with an explicit registry; one without is rejected at deserialization. In the authoring sidecar the digest is optional, and a tag-only identifier tells ocx package create to resolve it. In the published form the digest is mandatory and must reference a platform manifest, never an image index. The tag is always advisory. E.g. ocx.sh/java:21@sha256:a1b2c3d4e5f6....
name string No Short name used to reference this dependency in ${deps.NAME.installPath} templates, instead of the repository basename. Must match ^[a-z0-9][a-z0-9_-]*$ and be at most 64 characters.
visibility string No Controls how the dependency’s environment variables propagate. Default: sealed. See Visibility.
{
"$schema": "https://ocx.sh/schemas/metadata/v1.json",
"type": "bundle",
"version": 1,
"env": [
{ "key": "PATH", "type": "path", "required": true, "value": "${self.installPath}/bin", "visibility": "public" },
{ "key": "JDK_HOME", "type": "constant", "value": "${deps.java.installPath}", "visibility": "public" }
],
"dependencies": [
{
"identifier": "ocx.sh/java:21@sha256:a1b2c3d4e5f6...",
"visibility": "private"
},
{
"identifier": "ocx.sh/nodejs/node:24@sha256:f6e5d4c3b2a1...",
"name": "node"
}
]
}

Visibility

A dependency’s visibility controls how its environment variables propagate through the dependency chain. It has two boolean axes: private (visible to the package’s own runtime) and interface (propagated to consumers).

Value Private surface (--self) Interface surface (default) Use case
sealed (default) No No Structural dependency: content accessed by path, not env. Most deps.
private Yes No Package’s own shims need the dep’s env; consumers don’t.
public Yes Yes Both the package and consumers need the dep’s env.
interface No Yes Meta-packages that forward env to consumers without using it.
  • A package’s own runtime sees private and public dependencies. Consumers see public and interface ones.
  • The composer uses this split to gate entry emission per surface at exec time.

Transitive Propagation

Along a chain (Root, Dep, Transitive), the effective visibility is sealed when the child’s effective visibility does not export to consumers (private or sealed), and the edge unchanged otherwise.

Edge Child effective Result (from root)
public public / interface public
public private / sealed sealed
private public / interface private
private private / sealed sealed
interface public / interface interface
interface private / sealed sealed
sealed any sealed

Diamond Merge

When two paths reach the same dependency, the most open visibility wins: each axis (own runtime, consumers) is OR-merged independently. It is computed at install time and stored in resolve.json (see Environment composition: edge filter).

Ordering

Array position defines the canonical order for environment composition, and the first entry’s environment is applied first. The dependency graph is walked depth first with dependencies before dependents, and a package reached twice keeps its first position.