Version 1
Original manifest
Original report
Original record + photograph
A practical introduction
Understand the package, the infrastructure around it, and the work it makes possible. The principles are generic; the examples make them concrete.
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 registriesWhat each piece is
Its size
Its exact fingerprint
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.
Original manifest
Original report
Original record + photograph
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.
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.
Separate the place information lives, the code that moves it, and the code that uses it.
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 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.
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.
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.
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.
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.
“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.
These interfaces exist today. The proposed OCI handoffs still need implementation, subscription/permission checks, and compatibility testing.
| Software | Existing interface | Your work |
|---|---|---|
| Revit / Autodesk Docs | APS file versions and Automation engines.Autodesk Data Management API · Autodesk file and version concepts · Autodesk Automation APIs | Select a published version; implement export and result return. |
| Rhino / Grasshopper | rhino3dm file access; Rhino Compute geometry operations.Rhino rhino3dm libraries · Rhino Compute capabilities | Preserve units and IDs; pin definitions and license the engine. |
| SketchUp | Ruby model/export API.SketchUp Model API and export | Build an extension or controlled export; check exporter fidelity. |
| SharePoint / OneDrive | Microsoft Graph file versions.Microsoft Graph file versions | Capture retained versions; map source access and handle expiration. |
| Procore / Business Central | Attachments / purchase invoice resources.Procore attachments and uploads · Business Central purchase invoices API | Map record IDs and fields; keep live transactions in the source. |
| iTwin / Maximo | Synchronization / authorized asset-system access.Bentley iTwin Synchronization API · IBM Maximo API key permissions | Validate alignment or asset mappings; retain original source versions. |
A client can deliver every byte correctly and still misunderstand the information.
Identity, units, relationships, responsibility.
A native file, open model, table, or image.
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.
A checker follows the type relationship and any override, preserving the door’s identity.
A move can change a placement without rewriting the shared shape, if the representation preserves both.
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| Independent choice | What it gives you | Still your responsibility |
|---|---|---|
| Meaning: IFC or another domain standard | Shared object definitions and relationships. | Agree required fields; validate interpretation. |
| Native files, open representations, or both | Authoring fidelity and/or independent consumption. | Conversion loss and licensed engines. File custody alone does not guarantee interpretation. |
| OCI packaging and delivery | Common package references and distribution. | Content profiles, connectors, and workflow. |
| Managed or independently operated storage | An operational and custody choice. | Access, retention, recovery, cost, and exit. |
| Apps, automation, then optional agents | Useful operations on agreed inputs. | Correctness, permissions, maintenance, and acceptance. |
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 release | Door edit | Furniture move | Wall-cost edit |
|---|---|---|---|
| Whole JSON | 38.2 MB | 38.2 MB | 38.3 MB |
| Parquet property families | 9.8 kB | 10.6 MB | 10.6 kB |
| Exact base + change file | 8.5 kB | 11.7 kB | 14.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.
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
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.
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.
A coordinator needs to reopen the same set of discipline models, compare revisions, and keep findings tied to the reviewed set.
A site lead assembles photographs, an inspection record, and a location reference into evidence a reviewer can trace.
A commercial analyst compares an invoice with the delivery evidence and agreed quantities, while the ERP remains responsible for posting.
An asset owner checks a bounded equipment register and its manuals before importing accepted records into the maintenance system.
A design lead searches earlier decisions and outcomes. Retained source versions let the team inspect the evidence behind each answer.
A small application compares two quantity reports. An agent can later choose approved inputs and call the same bounded operation.
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.
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.jsonBoth 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 referrersFor 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.htmlPublish 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.
Start with one complete workflow. Add infrastructure when a measured need justifies it.
One source/export, one agreed profile, one compatible store, one operation, and one result in the current review process. Reuse existing identity and hosting.
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.
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.
| Need | Start here |
|---|---|
| One task entirely inside an existing platform | Its API and current review workflow. OCI may add no useful portability. |
| Store and retrieve files for one consumer | Ordinary object storage and version metadata may be enough. |
| Query or update individual records | A database or transactional API. Keep ERP posting in the ERP. |
| Live collaborative editing | An editing/synchronization engine with conflict handling. |
| Spatial queries or continuous telemetry | A 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.
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.
| Participant | Possible gain | Investment, trade-off, and condition |
|---|---|---|
| Authoring vendors | More destinations for models and paid engines. | Maintain faithful exports/APIs; give up some format lock-in. Worthwhile when engine or service revenue pays. |
| CDE providers | More useful workflows around controlled information. | Maintain access, version APIs, and connectors; lose some exclusivity. Worthwhile when workflow value remains billable. |
| Specialist startups | Reach customers through a narrow useful operation. | Fund adapters and support; face easier substitution. Worthwhile when domain quality differentiates the product. |
| Data-platform startups | Sell reliable integration and operation. | Fund hosting, recovery, and compatibility; lose captive-storage advantage. Worthwhile when service margin sustains operations. |
| Consultants | Reusable methods and clearer deliverables. | Fund mappings, checks, and correction; lose some repeat preparation fees. Worthwhile with paid information scope and reuse rights. |
| Contractors | Less repeated coordination and evidence assembly. | Fund integration and site capture; lose control over some handoff practices. Worthwhile when saved effort exceeds support costs. |
| Owners | More usable handover and supplier choice. | Pay for better information and stewardship; accept ongoing custody. Worthwhile when operational uses and acceptance tests are funded. |
| Internal IT | Common 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.
| Stage | Additional work | Benefit needed |
|---|---|---|
| One workflow | Connector, profile, operation, and review. | A correct result with less effort or justified quality gain. |
| Second application | Consumer adapter and compatibility tests. | Reuse the same input without rebuilding its source connection. |
| Several projects | Mappings, isolation, onboarding, and support. | Reuse saves more than project variation costs. |
| Partner exchange | Trust, access, contracts, and recipient tests. | Both sides fund and accept a more useful handoff. |
| Broader ecosystem | Shared 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.
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.