The practical OCI guide

A practical introduction

OCI, from files
to working systems.

Understand the package, the infrastructure around it, and the work it makes possible. The principles are generic; the examples make them concrete.

01 / THE GUIDE

Understand the package

OCI gives files a common way to be packaged, identified, and delivered.

OCI means Open Container Initiative. Its standards grew out of software containers. The packaging and distribution specifications also support ordinary data: models, point clouds, images, invoices, or reports. Publishing these files does not require running them as containers.

The Image specification defines package structure; the Distribution specification defines transfer. The separate Runtime specification concerns executing containers.

ORAS is a client that publishes and retrieves OCI artifacts. OCI is the standard; ORAS is one implementation. A compatible registry is the service at the other end.

About the Open Container Initiative · OCI guidance for non-container artifacts · ORAS clients and registries
Example · one inspectionThe artifact is the whole package
MANIFEST

The inventory

What each piece is
Its size
Its exact fingerprint

Inspection recordStored content · a blob
PhotographStored content · a blob
ReportStored content · a blob
A package can hold one file or several. The manifest references the bytes; it does not need to wrap them in a single ZIP file.

Digest = exact content. A fingerprint calculated from bytes. Change a file and its digest changes; the manifest referencing it changes too.

Tag = convenient label. A name such as “current” can point to a different version later. Record digests when a result must be reproducible.

OCI image manifest 1.1.1 · OCI descriptors and content fingerprints · OCI distribution 1.1.1

What happens when the report changes?

current →

Version 1

Original manifest
Original report
Original record + photograph

current →

Version 2

New manifest
New report
Same record + photograph reused

A new version references the new report and the unchanged record and photograph. The “current” tag can move; retained Version 1 is still addressable by its digest.

OCI identifies versions; your service decides what to retain. It does not automatically split large files, merge edits, or approve a release.

Technical detail: addresses, types, and linked results

A repository groups artifacts inside a registry. A tag reference looks like registry.example.org/team/inspections:current; an exact reference uses @sha256:… instead of the tag. These are registry references, not browser download links.

A media type identifies an encoding, such as image/jpeg. An artifact type describes the package kind. A subject points from a result artifact to another artifact; referrer discovery finds those attached results. Multiple inputs need an agreed provenance record listing every exact input.

A digest checks bytes, not authorship or correctness. An approval, trusted signature, retention rule, and access policy each do a different job.

02 / THE GUIDE

Connect the infrastructure

Separate the place information lives, the code that moves it, and the code that uses it.

Select a block to see what it does. These are responsibilities; one small service can combine several.

The original authority

A file service, authoring tool, ERP, or site application owns the live information. Read a specific version or capture a consistent snapshot. Keep the source link and permissions. Live changes and approvals continue through its API.

Examples: Autodesk Docs, SharePoint, Business Central. A file package does not replace invoice posting or a shared editing session.

The bridge to OCI

The connector reads a supported API or accepts an export. Mapping code prepares the content. An OCI client such as ORAS uploads (pushes) or downloads (pulls) the package.

Build this handoff: source-version capture, field mappings, retries, and result return. A manual export can be enough for a first workflow.

The package service

A registry exposes the OCI distribution API. It stores manifests and blobs, often using disk or object storage underneath. Applications use the registry API; an ordinary storage bucket alone is not a registry.

A managed option such as Azure Container Registry or an independently operated Harbor installation can fill this role. Test your artifact types, permissions, referrers, retention, and restore.

The useful operation

A viewer, script, licensed engine, or agent reads a supported package and produces a result. Long jobs can use a queue and worker. Publish the output with its input versions and processing history.

Run this code separately from the registry: on a workstation, VM, container, or suitable hosted service. OCI storage does not execute it; Kubernetes is optional.

The place people work

A small interface lists available information and compatible operations. A catalog or search database indexes permitted metadata. It can be rebuilt from retained publications and source records.

Start with a configured app list. The registry does not provide business search, a universal app launcher, or compatibility between every file and every application.

The services around the workflow

Use organizational sign-in and scoped service identities. Apply access rules at sources, registry, workers, and search. Keep credentials in a secret manager; record activity, failures, and restore procedures.

Sharing a sign-in provider does not automatically copy permissions between systems. Name the service owner and keep the existing business approval route.

Azure Container Registry and OCI artifacts · Harbor OIDC authentication · Harbor project robot accounts

Follow one request through the system

  1. SelectA source file version
  2. PublishConnector + OCI client
  3. ProcessWorker reads the package
  4. ReturnLinked result for review
The registry sits between publication and processing. The worker authenticates, fetches the manifest, checks the content fingerprints, and reads the required files.

“Import from” means a connector reads an authorized source version and maps it into supported content. “Open with” means the interface selects a compatible application, grants scoped access, and passes the exact package reference. These actions require application code.

Real interfaces you can build on

These interfaces exist today. The proposed OCI handoffs still need implementation, subscription/permission checks, and compatibility testing.

SoftwareExisting interfaceYour work
Revit / Autodesk DocsAPS file versions and Automation engines.Autodesk Data Management API · Autodesk file and version concepts · Autodesk Automation APIsSelect a published version; implement export and result return.
Rhino / Grasshopperrhino3dm file access; Rhino Compute geometry operations.Rhino rhino3dm libraries · Rhino Compute capabilitiesPreserve units and IDs; pin definitions and license the engine.
SketchUpRuby model/export API.SketchUp Model API and exportBuild an extension or controlled export; check exporter fidelity.
SharePoint / OneDriveMicrosoft Graph file versions.Microsoft Graph file versionsCapture retained versions; map source access and handle expiration.
Procore / Business CentralAttachments / purchase invoice resources.Procore attachments and uploads · Business Central purchase invoices APIMap record IDs and fields; keep live transactions in the source.
iTwin / MaximoSynchronization / authorized asset-system access.Bentley iTwin Synchronization API · IBM Maximo API key permissionsValidate alignment or asset mappings; retain original source versions.
03 / THE GUIDE

Give the content meaning

A client can deliver every byte correctly and still misunderstand the information.

MEANINGWhat is this thing?

Identity, units, relationships, responsibility.

REPRESENTATIONHow is it written?

A native file, open model, table, or image.

OCIWhich exact package?

A manifest, content fingerprints, and delivery.

Agree a small content profile: required files, their roles, supported encodings, units, identifiers, and source links. This is how two applications know what they can exchange. OCI and a semantic standard such as IFC can be adopted independently.

Example: why model semantics change the work

Door property

Resolve the right value

Door → type
+ instance override

A checker follows the type relationship and any override, preserving the door’s identity.

Chair placement

Reuse the shape

One chair shape
→ many placements

A move can change a placement without rewriting the shared shape, if the representation preserves both.

Wall cost

Process relevant values

Wall quantities
× agreed rates

A rate change can leave geometry reusable. Recalculating every wall may still touch every cost partition.

Object identity tracks the same door through changes; a digest tracks exact bytes. An authoring layer expresses contribution and precedence; a storage chunk is a transfer unit. Neither pair is interchangeable.

IFC object identity · IFC type and occurrence properties · IFC local placement · IFC reusable shape definitions
The five choices you can make independently
Independent choiceWhat it gives youStill your responsibility
Meaning: IFC or another domain standardShared object definitions and relationships.Agree required fields; validate interpretation.
Native files, open representations, or bothAuthoring fidelity and/or independent consumption.Conversion loss and licensed engines. File custody alone does not guarantee interpretation.
OCI packaging and deliveryCommon package references and distribution.Content profiles, connectors, and workflow.
Managed or independently operated storageAn operational and custody choice.Access, retention, recovery, cost, and exit.
Apps, automation, then optional agentsUseful operations on agreed inputs.Correctness, permissions, maintenance, and acceptance.
What the reported IFC5 experiment establishes

On 29 October 2026, helenkwok reported testing four Nordic BIM4LCA permit/as-built Revit pairs exported to IFCX. The author reports exact recomposition in 504 measured releases. These are reported results, not an independently reproduced benchmark.

Largest releaseDoor editFurniture moveWall-cost edit
Whole JSON38.2 MB38.2 MB38.3 MB
Parquet property families9.8 kB10.6 MB10.6 kB
Exact base + change file8.5 kB11.7 kB14.0 kB

Values are reported new bytes including the experiment’s flat JSON manifest, assuming prior content is held. The base-dependent real revision was 0.74 MB.

  • JSON was uncompressed; Parquet used zstd. The single gzip file was 2.37 MB: compression must be normalized before comparing layouts.
  • Fine partitions produced a 2.74 MB manifest; Parquet footers also burden tiny changes. Request costs and two-level manifests were unmeasured.
  • Conflicts and long-chain compaction remain unresolved; the scripted edits omit dependent authoring updates.
  • The exporter baked world-coordinate meshes without placements. Placement-only chair moves were not measured.

The gains belong to representation, partitioning, reproducible exports, and base-reusing change files. They do not establish an OCI-specific speed or cost advantage. Reported IFC5 experiment by helenkwok, 29 October 2026

IFC5 is evolving. Use supported formats for an operational pilot, and validate emerging representations separately. IFC5 development scope and limitations

04 / THE GUIDE

Apply the same pattern

Exact input → useful operation → linked result → existing review.

The examples below are proposed implementations using documented building blocks. They can start inside one organization; a partner does not need to adopt OCI.

Example · Repeatable checks

“Can we reproduce this result?”

An AEC information manager checks a weekly model delivery. A startup can use the same pattern to rerun internal calculation fixtures after an engine update.

  1. Exact inputsModel + rules
  2. OperationRun the checker
  3. Linked resultReport → existing review
What the first implementation takes
Who?
The person repeating a check and the reviewer accepting its result.
Smallest version?
One manual export, one ruleset, one report returned to the current review process. Partners keep their existing software.
Exists today?
IfcTester checks IFC against IDS and produces reports.IfcTester usage and reports
Build?
A worker wrapper, exact-input record, result publication, and review link.
Agree?
Rule meaning, acceptance criteria, responsible reviewer, and ruleset owner.
Risks?
Missing export properties, incorrect requirements, or changed engine behavior.
Measure?
Known defects found; preparation and review minutes; cost per accepted run.
Next?
Automate source retrieval only when manual preparation is a recurring burden.
Example · Federation

“Which combination did we review?”

A coordinator needs to reopen the same set of discipline models, compare revisions, and keep findings tied to the reviewed set.

  1. Exact inputsTwo model versions
  2. OperationAlign + compare
  3. Linked resultFederation record + findings
What the first implementation takes
Who?
The coordinator preparing a recurring multidisciplinary review.
Smallest version?
Two issued exports, their exact references, and agreed alignment in one federation record.
Exists today?
Authoring exporters and coordination tools; iTwin has its own documented synchronization path.Bentley iTwin Synchronization API
Build?
The federation record/profile, viewer adapter, identity mapping, and report return.
Agree?
Units, coordinates, stable object IDs, tolerances, and contribution authority.
Risks?
Misalignment, recreated IDs, missing dependencies. OCI supplies no live merge engine.
Measure?
Exact set reopens; expected changes found; preparation/review effort and conversion cost.
Next?
A second viewer, if it can reuse the same published set and offers a needed operation.
Example · Site evidence

“What evidence belongs to this finding?”

A site lead assembles photographs, an inspection record, and a location reference into evidence a reviewer can trace.

  1. Exact inputsPhotos + inspection
  2. OperationAssemble evidence
  3. Linked resultPackage → site issue
What the first implementation takes
Who?
The site lead closing out recurring inspection findings.
Smallest version?
One finding, its original photographs, and a linked package in the existing issue workflow.
Exists today?
Procore documents resource attachments and uploads.Procore attachments and uploads
Build?
Capture/import, asset/location mapping, package publication, and issue linkage.
Agree?
Evidence required, capture responsibility, access, retention, and acceptance.
Risks?
Offline retries duplicate records; wrong location; restricted photos exposed.
Measure?
Correct evidence attached once; review effort and missing evidence; support/storage cost.
Next?
Offline synchronization after ordinary capture and retry behavior are dependable.
Example · Reconciliation

“Do these records describe the same delivery?”

A commercial analyst compares an invoice with the delivery evidence and agreed quantities, while the ERP remains responsible for posting.

  1. Exact inputsInvoice + delivery
  2. OperationMatch + flag
  3. Linked resultExceptions → ERP review
What the first implementation takes
Who?
The analyst repeatedly reconciling supplier invoices.
Smallest version?
Read one invoice and delivery snapshot; return an exception report without posting.
Exists today?
Business Central exposes purchase invoice resources and actions.Business Central purchase invoices API
Build?
Read connector, code/unit/currency mappings, matching rules, and evidence links.
Agree?
Authoritative quantities, tolerances, taxes, access, and approver.
Risks?
Stale records, wrong supplier/code matches, conflicting updates, double posting.
Measure?
Known discrepancies detected; repeated matching/review effort; operating cost.
Next?
Propose an ERP update only with its concurrency and approval controls.
Example · Handover

“Can the next team use this delivery?”

An asset owner checks a bounded equipment register and its manuals before importing accepted records into the maintenance system.

  1. Exact inputsRegister + manuals
  2. OperationValidate + map
  3. Linked resultAccepted import record
What the first implementation takes
Who?
The facilities information manager accepting equipment information.
Smallest version?
One asset class, required fields, attached manuals, and a reviewed trial import.
Exists today?
Asset systems such as Maximo offer authorized integration interfaces.IBM Maximo API key permissions
Build?
Field mapping, identity resolution, validation, import adapter, and reconciliation.
Agree?
Required information, producer payment, acceptance, correction, and update duties.
Risks?
Duplicate assets, missing manuals, units mismatch, unsupported native content.
Measure?
Correct accepted records; producer/reviewer effort; correction and maintenance cost.
Next?
Another asset class after acceptance and export-back tests pass.
Example · Cross-project reuse

“What can we trust from earlier work?”

A design lead searches earlier decisions and outcomes. Retained source versions let the team inspect the evidence behind each answer.

  1. Exact inputsPermitted reports
  2. OperationIndex + retrieve
  3. Linked resultEvidence with source links
What the first implementation takes
Who?
The lead repeating research at the start of each project.
Smallest version?
One curated collection and ordinary search with source links.
Exists today?
File APIs such as Microsoft Graph, plus search engines and databases.Microsoft Graph file versions
Build?
Curation, metadata mapping, access-filtered indexing, freshness/deletion handling.
Agree?
Reuse rights, comparable definitions, outcome quality, and curator.
Risks?
Stale permissions, misleading comparisons, missing outcomes, restricted snippets.
Measure?
Relevant permitted evidence; search/review time; indexing and curation cost.
Next?
Source-backed synthesis only when retrieval alone leaves a recurring task unsolved.
Example · Apps + agents

“Can we build just the operation we need?”

A small application compares two quantity reports. An agent can later choose approved inputs and call the same bounded operation.

  1. Exact inputsTwo reports
  2. OperationDeterministic comparison
  3. Linked resultChange summary for review
What the first implementation takes
Who?
The analyst repeatedly preparing a change summary.
Smallest version?
A narrow app with fixed input columns, a tested comparison, and a review screen.
Exists today?
Calculation libraries and APIs; MCP can expose tools to agents.MCP tools and user interaction
Build?
Mappings, comparison, interface, provenance, tests, and maintained dependencies.
Agree?
Quantity meaning, units, permitted operations, reviewer, and code owner.
Risks?
Schema changes, generated-code defects, document instructions, excessive permissions.
Measure?
Correct calculations; repeated processing/review time; compute and maintenance cost.
Next?
Agent orchestration when selecting inputs and operations is itself a measured burden.
05 / THE GUIDE

Try the mechanics locally

Publish an inspection, attach a review, then copy both.

This exercise uses ORAS and two local folders in OCI layout format. No cloud account or registry server is needed. It demonstrates packaging and links; authentication and enterprise workflow come later.

  1. PushCreate the package
  2. ResolveGet its exact digest
  3. AttachLink a review
  4. Copy + pullTransfer and recover it
Run the exercise · ORAS 1.3.5 · bash or zsh

Install the pinned ORAS version and run this in a writable directory. It creates a new inspection-lab folder with synthetic data. ORAS installation

set -eu

mkdir inspection-lab
cd inspection-lab

cat > inspection.json <<'JSON'
{
  "asset_id": "door-042",
  "location": "Level 2, east stair",
  "finding": "Closer needs adjustment",
  "status": "open"
}
JSON

oras push --oci-layout source:v1 \
  --artifact-type application/vnd.example.inspection.v1 \
  inspection.json:application/json

inspection_digest="$(oras resolve --oci-layout source:v1)"

cat > review.json <<JSON
{
  "input_digest": "$inspection_digest",
  "decision": "needs-review",
  "next_action": "Assign to the site lead"
}
JSON

oras attach --oci-layout "source@$inspection_digest" \
  --artifact-type application/vnd.example.inspection-review.v1 \
  review.json:application/json

oras discover --oci-layout "source@$inspection_digest"

oras cp --from-oci-layout --to-oci-layout --recursive \
  "source@$inspection_digest" received:v1

oras pull --oci-layout "received@$inspection_digest" \
  --output received-files
oras discover --oci-layout "received@$inspection_digest"
cmp inspection.json received-files/inspection.json

Both discover calls should list the linked review. The final cmp should succeed silently. Pulling the inspection retrieves its files; the review is a separate artifact you can pull by its own digest.

The custom example types are not industry standards. Some ORAS 1.3 options, including recursive copy, are preview: pin and retest the client.

ORAS push · ORAS resolve · ORAS attach · ORAS discover · ORAS copy and referrers
Then replace the synthetic result with a real operation

For a model check, supply an agreed IFC model and IDS ruleset to a pinned IfcTester installation:

python -m ifctester requirements.ids model.ifc -r Html -o report.html

Publish the report with both input versions, tool version, and execution record. Failed requirements are findings; a crashed worker is an execution failure. Keep those outcomes distinct. IfcTester usage and reports

Next, copy a test package into a provisioned registry using its supported sign-in flow. Test a read-only identity, denied access, attached-result retention, and restore. The local exercise cannot establish these properties.

06 / THE GUIDE

Decide what is worth operating

Start with one complete workflow. Add infrastructure when a measured need justifies it.

First deployment

One source/export, one agreed profile, one compatible store, one operation, and one result in the current review process. Reuse existing identity and hosting.

Before relying on it

Name an operator and backup. Test representative good/bad inputs, source changes, denied access, retries, and restore. Budget connector, ruleset, and dependency upkeep.

Price the whole workflow: connector + mapping + interface work, domain review, licenses, hosting, storage/transfer, support, and retained versions. Compare correctness, repeated effort, review time, and cost per accepted result against today’s process.

Enterprise controls and the limits of OCI

Enforce access separately at each service; minimize worker permissions and separate proposed results from authorized writes. Isolate processing of untrusted files, validate outputs, log input/output references, and monitor failures. Container-image scanning alone does not validate arbitrary documents or models.

Test large uploads, referrer discovery, revocation, backup, restore, and export. Keep required attached results through retention and garbage collection. A content fingerprint is neither an access control nor an indefinite preservation guarantee.

OCI packaging and distribution have established infrastructure. Domain content profiles, federation records, application launch contracts, and cross-system permission mappings still need agreement and validation.

When something simpler—or a different service—fits better
NeedStart here
One task entirely inside an existing platformIts API and current review workflow. OCI may add no useful portability.
Store and retrieve files for one consumerOrdinary object storage and version metadata may be enough.
Query or update individual recordsA database or transactional API. Keep ERP posting in the ERP.
Live collaborative editingAn editing/synchronization engine with conflict handling.
Spatial queries or continuous telemetryA spatial database or streaming system; publish selected snapshots/results when useful.

Stop or simplify if inputs cannot be interpreted reliably, permissions cannot be enforced, nobody owns maintenance, or the measured benefit does not cover the burden.

Who pays, who benefits, and why participate?

Better information often costs the producer time while saving someone else work. Open standards do not resolve that mismatch. Fund bounded deliverables, acceptance tests, correction duties, and ongoing updates explicitly.

ParticipantPossible gainInvestment, trade-off, and condition
Authoring vendorsMore destinations for models and paid engines.Maintain faithful exports/APIs; give up some format lock-in. Worthwhile when engine or service revenue pays.
CDE providersMore useful workflows around controlled information.Maintain access, version APIs, and connectors; lose some exclusivity. Worthwhile when workflow value remains billable.
Specialist startupsReach customers through a narrow useful operation.Fund adapters and support; face easier substitution. Worthwhile when domain quality differentiates the product.
Data-platform startupsSell reliable integration and operation.Fund hosting, recovery, and compatibility; lose captive-storage advantage. Worthwhile when service margin sustains operations.
ConsultantsReusable methods and clearer deliverables.Fund mappings, checks, and correction; lose some repeat preparation fees. Worthwhile with paid information scope and reuse rights.
ContractorsLess repeated coordination and evidence assembly.Fund integration and site capture; lose control over some handoff practices. Worthwhile when saved effort exceeds support costs.
OwnersMore usable handover and supplier choice.Pay for better information and stewardship; accept ongoing custody. Worthwhile when operational uses and acceptance tests are funded.
Internal ITCommon delivery tooling and replaceable services.Fund security, operations, and API maintenance; trade some central control for supported app access. Worthwhile with an owner and bounded support scope.

These are possible business cases, not stated vendor commitments.

Earn each next step

StageAdditional workBenefit needed
One workflowConnector, profile, operation, and review.A correct result with less effort or justified quality gain.
Second applicationConsumer adapter and compatibility tests.Reuse the same input without rebuilding its source connection.
Several projectsMappings, isolation, onboarding, and support.Reuse saves more than project variation costs.
Partner exchangeTrust, access, contracts, and recipient tests.Both sides fund and accept a more useful handoff.
Broader ecosystemShared profiles, conformance tests, and stewardship.Independent implementations interoperate sustainably.

At every step: name a real owner and backup, fund maintenance, test representative data, and retain an export or rollback path. A useful internal workflow is already a successful destination.

Sources & further reading
  1. About the Open Container Initiative
  2. OCI guidance for non-container artifacts
  3. ORAS clients and registries
  4. OCI image manifest 1.1.1
  5. OCI descriptors and content fingerprints
  6. OCI distribution 1.1.1
  7. Azure Container Registry and OCI artifacts
  8. Harbor OIDC authentication
  9. Harbor project robot accounts
  10. Autodesk Data Management API
  11. Autodesk file and version concepts
  12. Autodesk Automation APIs
  13. Rhino rhino3dm libraries
  14. Rhino Compute capabilities
  15. SketchUp Model API and export
  16. Microsoft Graph file versions
  17. Procore attachments and uploads
  18. Business Central purchase invoices API
  19. Bentley iTwin Synchronization API
  20. IBM Maximo API key permissions
  21. IFC object identity
  22. IFC type and occurrence properties
  23. IFC local placement
  24. IFC reusable shape definitions
  25. IFC5 development scope and limitations
  26. IfcTester usage and reports
  27. MCP tools and user interaction
  28. ORAS installation
  29. ORAS push
  30. ORAS resolve
  31. ORAS attach
  32. ORAS discover
  33. ORAS copy and referrers

See the research on CDEs, information flow, and AI for the motivation. The development guide shows how to connect an app. The architecture guide explains access and publication.