- docs
- Look things up
- Reference
- Look things up
- Reference
- Metadata
- Metadata: Dependencies
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.
- Limit: a package declares at most 256 dependencies, and a longer array is rejected when the file is read (
too many dependencies, exit 65) - The platform a bundle targets is not part of this file. On the wire it lives in the image index. Between
ocx package createandocx package pushorocx package testit lives in a build receipt, readable withocx package receipt. - Authoring sidecar versus published form: the digest is optional while authoring and mandatory once published. The published form is a strict subset of the authoring form, so an already-published
metadata.jsonis a valid sidecar forocx package createandocx package pushand needs no migration.
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
privateandpublicdependencies. Consumers seepublicandinterfaceones. - 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.