Open Reference Board Format

Open Reference Board Format (ORBF) is a proposed interchange format for visual reference-board applications such as ArtDeck, PureRef, BeeRef, VizRef and FrameRef. It carries common board data between applications and keeps standalone packages readable without a dedicated viewer. A standalone file is a ZIP containing a JSON descriptor and the referenced source media.

.oref is the recommended extension for a standalone ORBF package, not a validity requirement. ZIP-based native formats may carry the same portable descriptor while keeping their own filename extension, media type, manifest, and files.

Applications can support either path or both: include an ORBF projection in their primary ZIP-based board format while retaining its native extension, or provide an Export as ORBF action that writes a standalone .oref package. In both cases, other programs can read the portable board basics without implementing the native format.

Status: Proposal 0.1. The format is experimental. Each 0.x version is a separate proposal and may be incompatible with another 0.x version. Stable compatibility guarantees begin at 1.0. No application support has been confirmed.

Disclosure. The ORBF editor maintains ArtDeck, one of the applications named above. ORBF is a vendor-neutral proposal: ArtDeck holds no privileged status in the core, its vendor-specific behavior belongs in a namespaced extension like any other application's, and the 1.0 gate below requires evidence independent of it. See GOVERNANCE.md.

Portable core

Proposal 0.1 covers:

• image, animated-image, video, text, URL, shape, drawing, and group items;
• position, size, scale, rotation, opacity, visibility, and locking;
• crop, flip, fit, video poster, and playback hints;
• nested groups and deterministic back-to-front stacking;
• embedded assets with media type, byte length, and SHA-256 digest;
• an optional non-authoritative standalone preview at the fixed path previews/thumbnail.png;
• optional namespaced extensions and explicit degradation reporting.

It does not standardize application UI, editing history, selection state, or every vendor-native feature.

Format design

Standalone packages and native carriers

ORBF uses one fixed root descriptor, oref-manifest.json, in two package profiles. An application may implement either profile or both:

• A standalone package owns the ZIP container. Its first entry is the exact, uncompressed ORBF mimetype, its second is oref-manifest.json, and every other payload entry is declared, except the optional undeclared preview at previews/thumbnail.png. Writers SHOULD use .oref.
• An embedded native carrier is an existing ZIP-based app format, such as a hypothetical .example package. The host keeps its own extension, MIME identity, native manifest, member order, and unrelated files. Adding exactly one root oref-manifest.json exposes a portable ORBF projection. Declared ORBF assets may point to safe existing entries anywhere in the same ZIP, so media need not be duplicated under an assets/ directory.

For example, both manifests can refer to the one physical media entry below:

study.example/
|-- mimetype                    # native application identity
|-- native/board.json           # native representation
|-- native/media/reference.jpg  # stored once
`-- oref-manifest.json          # asset.path = native/media/reference.jpg

Readers identify ZIPs by content, then use the exact ORBF mimetype to select the standalone profile or the root oref-manifest.json marker to select the embedded profile. Filename extensions and registry entries help file pickers discover candidates. Readers establish validity from the descriptor's format, version, structure, and referenced bytes.

An embedded ORBF layer is a portable import snapshot. A generic ORBF reader imports it and saves to standalone ORBF or its own native format; it does not rewrite an unknown proprietary carrier in place. A native application must update its native data and the ORBF projection together.

RO-Crate also uses a fixed descriptor within ZIP-based packages, including the ELN file format. The ORBF media type remains unregistered.

Ordered scene-graph tree

Groups and items form an ordered scene-graph tree. Every transform is local to the item's immediate parent; root-local coordinates are board coordinates. Readers derive world transforms by composing the ordered ancestor chain:

world = parentWorld × local

Sibling arrays are the portable z-order authority, stored back-to-front. Applications may translate their own integer, fractional, or object-based stacking model during import and export.

Shared source assets

Assets are declared and stored once. Multiple compatible items may reference one still-image, animated-image, or video asset. Item transforms, crop, opacity, visibility, and playback remain independent. Posters and URL previews may reuse a still-image asset.

ORBF distinguishes still images, animated images, and video with explicit image, animatedImage, and video item and asset kinds. An animated-image asset always declares its frame count and duration; frameCount may be 1, so one-frame GIFs are supported without making frame count an implicit type switch. ORBF does not mandate an image format, video container, or codec. An asset's mediaType identifies its stored encoding for decoder selection, but encoding support does not create another ORBF profile.

Portable drawing ink

A drawing is an item with the same centered local canvas and ancestor-composed transform as every other leaf item. It contains ordered, renderer-neutral strokes: local points, a color, a base width, and optional resolved per-point widths. The core stores visible geometry rather than raw pressure or instructions for a particular application's brush engine. Textured brushes, stamp streams, tilt, timing, and other native data belong in namespaced extensions; a drawing may also carry an image fallback for readers that cannot reproduce its strokes.

The geometry, rendering rules, and rationale are in §8.7 of the proposal. A separate ArtDeck drawing note records one non-normative native mapping without treating procedural brush texture size as canvas size.

Small core, namespaced extensions

Vendor-specific data belongs in reverse-domain extension namespaces. An importer may drop an unknown optional extension only after reporting degradation. An application claiming round-trip support must preserve it. Unknown required extensions make the package unsupported for a full semantic import, but do not make a structurally valid package invalid; a reader may offer a clearly labeled partial import. Extensions cannot redefine core fields or relax package safety. Additional app-specific item properties go inside the common item extensions object rather than beside core properties.

Conformance claims

Claims use the named classes Conforming Document, Standalone Reader, Standalone Writer, Embedded Reader, Native Carrier Writer, and Round-trip Processor. Each claim names the exact ORBF version and supported feature groups. Implementations must report dropped or approximated portable behavior rather than use an unqualified "ORBF compliant" label.

No particular image or video encoding is required. Tested still-image, animated-image, or video support means the implementation successfully decodes and applies portable behavior to at least one valid asset in that category; it does not claim support for every codec. See the normative conformance section.

Security and privacy boundary

Readers treat every package, manifest, extension, preview, and media asset as untrusted input. Archive validation and resource limits precede decoding; URL items remain inert during import; asset digests provide integrity, not authorship or trust. The security and privacy considerations collect the applicable requirements.

Versioning and compatibility

The manifest carries a MAJOR.MINOR specVersion. Repository releases may add a patch number, such as v0.1.1, for editorial corrections that do not change which documents are valid or what they mean. The patch number never appears in a manifest.

Before its first tagged release, Proposal 0.1 is an unreleased working draft and may change in place, including changes to accepted documents or behavior. Its specVersion identifies the proposal line rather than an immutable pre-release snapshot. Draft packages carry no compatibility promise, and implementation reports must identify the exact repository commit tested. The first tag freezes the proposal's meaning; later normative changes advance to the next 0.x specVersion. Published specification and schema files remain available at their versioned paths. An application that supports Proposal 0.1 does not claim support for Proposal 0.2 unless it implements that proposal or an explicit migration.

Version 1.0 will establish the first stable compatibility baseline. Backward compatibility means that newer readers accept older minor versions within the same major. Bounded forward compatibility means that an older reader accepts a later minor version from the same major, ignores only optional unknown data, and reports degradation. Every minor-version addition must have a safe fallback. Behavior without one belongs in a required extension or a new major version. Stable readers are not required to accept 0.x files, though applications may provide migrations. Core enum values and item discriminators remain closed within a stable major version; minor versions extend only the explicitly defined property extension points.

The normative rules are in §3.1 of the specification.

To move between versions, an importer reads the exact specVersion and applies that version's contract or a documented migration. An exporter may offer more than one target version, but the complete output must conform to the selected version. Changing the version string alone is not a conversion. Existing 0.x files remain 0.x after 1.0 is released; applications can migrate and re-export them as 1.0.

Goal for 1.0

Proposal 0.1 is the first public design, not a claim that the format is already stable. The 1.0 target is the smallest board contract that has been shown to work between independent implementations. It is not a promise to represent every feature of every reference-board application.

The project will designate a tagged 0.x proposal as the 1.0 candidate. Promotion changes the version and publication metadata, not the candidate's data model or behavior. If implementation work exposes a normative problem, the project publishes a new 0.x candidate and retests the affected contract instead of changing 1.0 during promotion.

The 1.0 release gate requires:

• a defined core scope, with unresolved or untested features deferred to an extension or later version;
• two separately maintained implementations each demonstrating Standalone Reader and Standalone Writer behavior by importing a candidate package written by the other, with at least one maintained independently of the ORBF editor;
• review of the candidate mapping by at least one maintainer of a reference-board application other than ArtDeck;
• cross-implementation evidence for every retained core item type and portable behavior, including transforms, ordering, groups, shared assets, and degradation;
• if the embedded profile remains normative, evidence from a Native Carrier Writer whose ORBF layer is imported by another implementation's Embedded Reader;
• passing schemas, valid and invalid fixtures, package-safety checks, examples, and a public implementation report;
• no open 1.0-blocking specification or security issue after at least 30 days of public candidate review; and
• migration guidance from the final 0.x candidate, even though stable conformance does not require readers to support draft files.

Proposal files

• Normative Proposal 0.1
• JSON Schema Draft 2020-12
• Extension authoring rules
• Implementation registry
• Optional JSON Canvas conversion note

Use the normative prose for semantics and JSON Schema for JSON structure. The Python fixture checker covers archive order, path safety, hashes, recursive IDs, and cross-references that JSON Schema cannot express.

Examples

• examples/minimal.oref is the smallest valid empty-board package.
• examples/simple.oref is a practical starter with one image and one text item.
• examples/comprehensive.oref covers every core item type, two distinct still-image sources, a cube-wireframe drawing, a rectangle and arrow, a grouped video and related link, and normal/flipped placements of one animated GIF.
• examples/comprehensive/expected-world-transforms.json records expected ancestor-transform results.
• examples/ASSETS.md records CC0 authors, sources, modifications, and checksums for the real example media.

Each standalone example also has a generated sidecar named <archive-stem>-<specVersion>-preview.png. The corresponding package contains the same bytes at previews/thumbnail.png. Generate both from the manifest and packaged assets with:

python3 scripts/generate-preview.py examples/comprehensive.oref

generate-preview.py --version reports both the generator version and the ORBF version it implements and rejects unsupported versions. Before opening media, it runs the repository package checker to apply archive, manifest, digest, and resource safety rules. It auto-fits visible content and renders the board background, opacity, transparent text boxes, and rotated edges with 2x supersampling. Previews are non-authoritative; importers reconstruct the board from oref-manifest.json and its assets. Embedded readers ignore a native carrier's file at the standalone preview path.

Rebuild and validate everything with:

./scripts/check.sh

This command requires Python 3, the packages in requirements.txt, Node.js with npx, and the standard zip utility. The check uses AJV for JSON Schema validation, rebuilds the archives and previews, checks package integrity, verifies invalid fixtures, compares each package's logical members with its source tree, checks same-toolchain deterministic rebuilding, verifies the full example's intended coverage, and calculates its world transforms.

Optional JSON Canvas conversion

JSON Canvas and ORBF overlap on basic two-dimensional nodes, but target different use cases. JSON Canvas support is not required for ORBF. The conversion note describes a lossy mapping for converter authors.

Proposing changes through issues

Issues are the primary design process. Application maintainers can use an app-format report to document their native model and conversion losses. Use the core/schema proposal template for portable changes, the extension template for app-specific meaning, and implementation reports for tested support claims.

The draft asks implementers about text layout and mapping richer native drawing brushes to portable ink. The normative draft lists both.

Proposal 0.1 remains a draft, and registry entries stay unconfirmed until evidence is available. The 1.0 release gate defines the review and independent implementation evidence required for a stable release.

Contributions begin with a concrete interoperability problem or fixture. See CONTRIBUTING.md, GOVERNANCE.md, and SECURITY.md.

Design influences and related formats

The design draws on JSON Canvas, glTF scene hierarchy, OCI Image Specification, OpenRaster, W3C InkML, SVG 2 painting, and JSON Schema 2020-12.

"Open Board Format", .obf, and .obz are already used by the OpenAAC communication-board format, so ORBF uses a different name and extension.

License

Specification prose, schemas, scripts, manifests, and documentation are available under the MIT License. Example media are verified CC0 1.0 works and documented derivatives.