Note

Looking for resources?

🐍 Get OpenAssetIO from PyPI
📐 Get off to a good start with the Python manager template.
📖 See some examples: Ayon manager plugin, USD Asset Resolver prototype, OTIO media linker
📖 See a Hello World tutorial example, with more tutorial examples to be found in OpenAssetIO-MediaCreation
🛠️ Learn how to build OpenAssetIO
📇 Check out the OpenAssetIO codebase

Warning: The API has a long history. The OpenAssetIO release version is currently in a beta stage and is subject to some refinements over the coming months. See the project tracker for more details.

OpenAssetIO defines a common set of interactions between a host of the API (eg: a Digital Content Creation tool or pipeline script) and an Asset Management System.

It aims to reduce the integration effort and maintenance overhead of modern CGI pipelines, and pioneer new, standardized asset-centric workflows in post-production tooling.

OpenAssetIO enabled tools and asset management systems can freely communicate with each other, without needing to know any specifics of their respective implementations.

The API has no inherent functionality. It exists as a bridge - at the boundary between a process that consumes or produces data (the host), and the systems that provide data coordination and version management functionality.

Scope

The API covers the following areas:

Resolution of asset references (URIs) into a dictionary of data, grouped into one or more traits (providing URLs for access and other asset data).
Publishing data for file-based and non-file-based assets.
Discovery and registration of related assets.

The API, by design, does not:

Define any standardized data structures for the storage or description of assets or asset hierarchies.
Dictate any aspect of how an asset management system operates, organizes, locates or manages asset data and versions.

The Approach

Once we have a common standard, any Asset Management System or host implementing it can be considered to be compatible. This means that neither party needs to pay any particular attention to who it is talking to, unless they specifically desire to do so.

Our hope is that a common baseline level of support for the key operations performed within multi-site production pipelines will greatly simplify integration and allow innovative new workflows to be developed. Bridging tool vendors, asset management system authors and facility pipelines.

What is an Asset Management System

We define an Asset Management System as a system that tracks, and potentially manages, the state and location of digital media. Within the Media and Entertainment sector, these are often known as assets. Within OpenAssetIO, we call anything managed by the system an entity.

Within post-production, entities are often things like project, sequences, shots, clips, image sequences and 3d models that are used to produce final content. In the API, entities are referred to using an Entity Reference.

Note: We use the term "entity" in the API, rather than "asset" to avoid confusion. Asset is a very loaded term. Most systems we have encountered seem to use the term "asset" to refer to a sub-set of the data they manage. For example, a shot may not be considered to be an asset, but is an addressable entity as far as the API is concerned.

What is a Host?

A host is a tool, script or application that either consumes or produces data, that needs to be managed by an asset management system. We call it the "host" as it is responsible for hosting the API and making appropriate calls to one or more asset management systems as part of its operations.

Architecture

Note: This API does not define, specify or implement either the asset management system or the host, rather a set of generalized queries and actions and concepts that have been found to be common across the majority of known workflows and back-end implementations.

Depending on whether you are reading this as a host author, or as an Asset Management System integrator, it is worth understanding the high-level architecture of the system. After this, the documentation (and code base) is separated depending on your focus. The following (potentially confusing) diagram attempts to show a simplified version of the architecture as a UML Class Diagram:

It attempts to show that the API is organized into two main namespaces - the hostApi and managerApi. Within each of these, you will find the components you need depending on whether you are adopting the API in a host or providing support for a manager through a plugin.

The first step in any integration is to write an implementation of one of the two abstract interfaces defined by the API, illustrated in orange above - either the HostInterface or ManagerInterface.

The asset management system implements the ManagerInterface. This is a thread-safe, reentrant interface that is the sole entry point for all interactions with the host.
The HostInterface represents the caller of the API. It allows the asset management system to customize the publishing process if desired and/or query additional information about the host.

The interface implementations are "wrapped" in the Host or Manager classes by the API before being passed to the other side, to provide state management and audit functionality.

See also: Notes for API Host Developers; Notes for Asset System Integrators

The Basic Design for a Host

A design goal of this API was for it to be (relatively) easy to retro-fit into an existing application or tool. In a minimal implementation, the host follows a few simple rules:

Wherever a file path was stored, store an Entity Reference.
Before the stored string is used, resolve it through OpenAssetIO and use the returned value instead.
Involve the manager in creation of data through the publishing workflow.

For this reason, OpenAssetIO has the concept of mapping an entity to one or more traits that contain meaningful data for someone wanting to consume the entity.

Note: The API is by no means limited to just file paths, they form a sensible first step. Any string used in an application, can be asset managed in the same way.

OpenAssetIO also allows arbitrary key/value pairs to be associated with an entity. This means other more complex data structures can be managed by the asset management system. The only prerequisite being that they can be sensibly encoded in a string and/or simple typed key/value pairs.

A renderer for example, could query the correct file format, colorspace and compression options from the manager for the images it is about to create.

The Asset Manager's Commitment

OpenAssetIO was developed to make it possible for an Asset Management System to support any host application without specific knowledge, and vice versa. This is achieved though the use of common specifications that define well-known traits and two simple rules for the manager:

Store and recall the set of traits (and their properties) registered for any given entity.
Allow filtering by these traits when browsing, etc.

If these rules are followed, then arbitrary assets from arbitrary hosts can be round-tripped through an asset manager without specific support. However, there is scope to build more advanced and useful functionality by mapping OpenAssetIO traits to the manager's native asset types and data.