OMI-SPEC-330 — Container Architecture
Status
Draft
Version: 0.1.0
Legacy identifier: OMI-SPEC-012
Depends on: OMI-SPEC-320 (File Format)
Purpose
The Container Architecture defines the portable package structure used to exchange and preserve an OMI manuscript together with its metadata, history, annotations, citations, assets, profiles, and extensions.
The container complements the File Format: OMI-SPEC-320 defines the logical manuscript representation, while this specification defines how the related files are assembled into one package.
Choosing between .omi and .omi.json
For ordinary saving, sharing, transfer, or backup of a complete manuscript, use the .omi package. It is designed to keep the manuscript together with associated resources such as media assets, metadata, history, profiles, and package integrity information. For most users, one .omi file is sufficient; exporting both formats is not a normal production requirement.
Use .omi.json when a workflow specifically needs the logical manuscript as directly readable JSON, such as inspection, automation, or a software integration. It is not the ZIP container and does not necessarily include related media files. If you are unsure which format to choose, use .omi.
Recommended Container Layout
The following directory structure is the current recommended layout. It remains provisional while this specification is in Draft status.
paper.omi
├── META-INF/
│ ├── manifest.json
│ ├── mimetype
│ ├── checksums.json
│ └── signatures.json
├── manuscript/
│ ├── document.json
│ ├── metadata.json
│ ├── history.json
│ └── review.json
├── annotations.json
├── citations.json
├── anchors.json
├── provenance.json
├── media/
│ ├── images/
│ ├── figures/
│ ├── assets/
│ └── datasets/
├── profiles/
└── plugins/
Package Principles
An OMI container should be:
- self-describing;
- platform independent;
- inspectable with standard archive tools;
- suitable for validation;
- safe for long-term preservation;
- capable of preserving unknown extensions;
- independent of one editor or publishing system.
META-INF
The META-INF directory contains package-level control information.
manifest.json
The manifest identifies package members, their media types, logical roles, versions, and optional dependencies.
mimetype
The mimetype file identifies the package media type. Its exact value and placement requirements will be fixed before Review Candidate status.
checksums.json
Checksums allow implementations to detect accidental modification or corruption.
signatures.json
Digital signatures are optional in the Draft architecture. A future integrity profile will define signature algorithms, canonicalization, trust, and verification requirements.
Manuscript Components
The manuscript directory stores the principal structured representations:
document.json— manuscript structure and content;metadata.json— descriptive, administrative, and preservation metadata;history.json— version and change history;review.json— review objects included in the package.
A publication or preservation profile may restrict which components are permitted or required.
Relationship Files
The package may store relationship collections separately:
annotations.json;citations.json;anchors.json;provenance.json.
Separating these collections supports independent processing while preserving stable identifiers between them.
Media and Assets
Binary and externally authored resources belong under media.
Implementations must prevent unsafe paths, executable-content confusion, archive traversal, and uncontrolled remote-resource resolution.
Every packaged asset should be referenced by a manifest entry and checksum.
Profiles and Plugins
The profiles directory may contain declared publication, discipline, validation, or preservation profiles.
The plugins directory may preserve extension data required to interpret plugin-defined objects. Packaging extension data does not imply that every consumer must execute plugin code.
A conforming preservation processor should retain unknown extension resources when it can do so safely.
Compression and Serialization
The physical archive format, compression method, entry ordering, filename encoding, and canonical byte representation will be defined before this specification reaches Implementation Candidate.
A container must not depend on operating-system-specific path syntax.
Validation
Container validation should include:
- required control files;
- manifest completeness;
- unique and safe paths;
- checksum integrity;
- declared media types;
- referenced-file existence;
- identifier consistency;
- unsupported or unknown extensions;
- maximum resource and expansion limits.
Security Considerations
Implementations must treat containers as untrusted input.
Processors should defend against:
- path traversal;
- archive bombs;
- duplicate or ambiguous paths;
- malicious active content;
- unsafe symbolic links;
- misleading media types;
- signature spoofing;
- unbounded decompression or parsing.
Opening a container must not automatically execute packaged code.
Non-normative Studio implementation profile — 2026-11-01
Proposed implementation: Studio #816, pending merge/CI. The Studio Draft writer declares serializationProfile: urn:omi:studio:container:asset-previews:1 in META-INF/manifest.json. This is a bounded Studio implementation profile, not promotion of OMI-SPEC-330 or a new canonical file-format generation. The container remains 0.1.0-alpha.1; absent profile is the existing experimental reader path. Unknown explicitly declared profiles must not become silently editable/overwritable packages.
The profile uses STORE ZIP, manifested paths, raw-byte SHA-256 and the existing separate 0.3 Draft core-snapshot document/history parts. It recursively resolves current asset-backed image references in embedded section and block trees, verifies retained as well as referenced binary assets, and replaces current-document preview src with an empty string. Missing/corrupt payloads prohibit a purported complete export. Duplicate, case/NFC-ambiguous, traversal, drive-root and control-character paths are invalid.
Historical snapshot states are preserved exactly, including legacy image previews, identifiers, events and existing digest declarations. The earlier proposal to strip all historical previews is superseded: the existing omi-manuscript-state-json-v1 implementation did not exclude previews within embedded section children. Removing those bytes can change old digest/signature subjects. Never repair this by silently changing v1 canonicalization or overwriting an existing digest. A future history normalization needs an explicitly versioned, evidence-preserving contract. Current output quotas remain; preserving history may keep redundant preview bytes in the history part.
The shared synthetic golden fixture is copied byte-for-byte to Studio tests/fixtures/container-profile-v1.json. Frozen archive SHA-256: e27470ca7de4c5e0c02f8b2f3942ebb8bfe1db207e5156a2090097947ae45ee3. Studio tests exercise the actual reader and historical state digests; OMI uses Python's independent ZIP/CRC/SHA-256 processing for this fixture. This is cross-repository package evidence, not complete independent semantic conformance or schema freeze.
Change history
- 0.1.0 — Migrated from provisional
OMI-SPEC-012to canonicalOMI-SPEC-330; repaired the malformed Markdown structure and expanded the initial package requirements.
Summary
The OMI Container Architecture packages a semantic manuscript and its related resources into a portable, inspectable, and preservable unit.
It defines organization and integrity at the package level while leaving manuscript semantics to the OMI File Format and related model specifications.