Overview

Languages

The following languages are currently supported:

• Go
• Python
• Rust (in progress)
• C# (in progress)
• Java (in progress)

See the SDK Feature Checklist below for current feature support across languages.

Unified Experience

The objective of ORAS is simple as transferring artifacts from one place to another.

In the conventional client-server model, the operation of downloading artifacts from the remote registries is referred to as pull, and the operation of uploading artifacts to the remote registry is referred to as push.

This model can be generalized by abstracting the client and the server as targets so that pull and push can be viewed as copying from one target to another (see Copy API oras-project/oras-go#8). For instances,

• Copy from memory to a remote registry.
• Copy from a remote registry to a local file folder.
• Copy from a remote registry to another remote registry.
• Copy from memory to a local file folder.

Targets

Generally, a target is a content-addressable storage (CAS) with tags. All blobs in a CAS are addressed by their descriptors.

To retrieve a blob,

1. Get a descriptor. Optionally, it can be resolved by a tag.
2. Query the blob with a descriptor.

To store a blob,

1. Store the blob directly in the CAS. A descriptor will be returned.
2. Optionally, associate the returned descriptor with a tag.

It is worth noting that a target is not equal to a registry.

• Blobs can be tagged in a target but not in a registry.
• Tag list is available in a registry but not always available in a target.

Graphs

Besides plain blobs, it is natural to store directed acyclic graphs (DAGs) in a CAS. Precisely, all blobs are leaf nodes and most manifests are non-leaf nodes.

An artifact is a rooted DAG where its root node is an OCI manifest or an OCI Artifact Manifest. Additionally, artifacts can be grouped by an OCI index, which is also a rooted DAG.

Given a node of a DAG in a CAS, it is efficient to find out all its children. Since CASs are usually not enumerable or indexed, it is not possible to find the parent nodes of an arbitrary node. Nevertheless, some CASs choose to implement or partially implement the functionality of parent node finding. For instances, registries with Referrers API support are CASs with partially implementation where parent node finding is only available for manifest nodes.

Extended Copy

With the concepts above, we can formally define that

• Copy is a function to replicate a rooted DAG from one CAS to another.
• Extended Copy is a function to replicate a DAG from one CAS to another.

It is worth noting that extended copy is possible only if the source CAS supports parent node finding. Based on the scenarios, extended copy can have many options such as opting to copy a sub-DAG rooted by a certain node and all its parent nodes of a certain depth with / without their children.

Optionally, node filters or even node modifiers can be attached to a copy process for advanced scenarios.

Related issues:

• Support copy of images and associated references oras-project/oras-go#29
• Copy Artifact Reference Graph oras-project/oras#307

Hint: A polytree is a DAG.

Paradigms

🚧 Note: this section is contingent on oras-project/oras-go#8 and does not represent the current state of the ORAS Go client library.

At a high-level, each client library provides the concept of a Target interface and a Copy method. Copy transfers content from one Target to another.

Target

A Target represents a place to which one can send/push or retrieve/pull artifacts. Anything that implements this interface can be used as a place to send or retrieve artifacts.

Some examples of a Target may include the following:

• An OCI Registry
• An OCI Image Layout
• A local collection of files

Copy

Copy copies a rooted DAG identified by a reference from one Target to another Target.

Method signature

The following is a rough method signature based on the Go version:

func Copy(from Target, fromRef string, to Target, toRef string) Descriptor

ExtendedCopy

Copy copies a DAG reachable from a node identified by a reference from one Target to another Target.

Method signature

The following is a rough method signature based on the Go version:

func ExtendedCopy(from Target, fromRef string, to Target, toRef string) Descriptor

SDK Features

This section defines the shared goals and roadmap for all ORAS SDKs, grouping features into Core, Recommended, and Optional to align implementation priorities and user expectations.

Core Features

Core features are the minimum required for ORAS SDK compliance. An ORAS SDK must provide OCI‑compliant registry interaction and support packaging and extracting arbitrary files as OCI artifacts.

• OCI Registry Client (Remote Artifact Store)
  • Implement the APIs defined in the latest OCI Distribution Spec.
  • Ensure compliance with the latest OCI Image Spec.
  • Provide authentication supporting both Basic and Bearer token flows.
• Artifact Packaging and Extraction
  • Pack arbitrary files from the local file system into OCI artifacts (manifest + config + layers).
  • Extract files from OCI artifacts to the local file system.

Recommended Features

Recommended features enable richer distribution scenarios: copying artifacts (and their referrers), using extended registry APIs, and reading and writing OCI Image Layouts for broader portability.

• Copy Operations
  • Standard copy: Copy artifacts to and from registries.
  • Extended copy: Copy artifacts along with their referrers to and from registries.
• Extended Registry Client
  • Support widely recognized APIs, such as APIs defined in Docker Registry HTTP API V2 which are not part of the OCI Distribution Spec (e.g., repository catalog).
• OCI Image Layout Support (Local Artifact Store)
  • Read artifacts from an OCI Image Layout.
  • Write artifacts to an OCI Image Layout.

Optional Enhancements

Optional features enhance usability and integration with existing Docker credentials.

• Credential Management
  • Leverage Docker config files and Docker credential helpers.

Feature Checklist

The following matrix tracks implementation status across language SDKs.
Update these tables whenever a feature is implemented or documented; leave ❔ where a language hasn’t been evaluated yet.

Symbol	Meaning
✅	Supported
🟡	Partially Implemented
❌	Not Yet Supported
❔	Not Evaluated

Core

Feature	Go	Python	Rust	C#	Java
OCI Distribution Spec Compliance	✅	❔	❔	✅	🟡
OCI Image Spec Compliance	✅	❔	❔	✅	✅
Authentication (Basic and Bearer)	✅	❔	❔	✅	✅
Artifact Packaging and Extraction	✅	❔	❔	❌	✅

Recommended

Feature	Go	Python	Rust	C#	Java
Standard Copy	✅	❔	❔	✅	✅
Extended Copy (with Referrers)	✅	❔	❔	❌	🟡
Extended Registry APIs	✅	❔	❔	✅	✅
OCI Image Layout Support	✅	❔	❔	❌	✅

Optional

Feature	Go	Python	Rust	C#	Java
Docker Credential Integration	✅	❔	❔	❌	🟡