The .cal file format

A portable container for construction review data — drawing sheets, optional 3D geometry, and the issues recorded against them. Designed so the data remains readable without proprietary software.

1. Container

A .cal file is a ZIP archive. It is not a novel binary format — the same approach is used by .docx, .xlsx, .3mf, .usdz, and .epub. That choice provides universal tooling, corruption resistance, streaming, inspectability, and the ability to add parts without breaking existing readers.

1.1 First entry: mimetype

entry 0:  name    = "mimetype"
          method  = STORED (no compression), no extra field
          content = application/vnd.caltior.cal    (ASCII, no trailing newline)

Every ZIP begins PK\x03\x04, so a content sniffer cannot otherwise distinguish a .cal from any other archive. An uncompressed mimetype entry first places the media type at a fixed byte offset (OpenDocument / EPUB convention).

1.2 Layout

mimetype        first entry, stored, as above
manifest.json   REQUIRED — the only file a reader must understand
sheets/         2D page images and placement metadata
model/          optional decimated 3D mesh (glTF)
punch/          issue records, as JSON
export/         optional plain-text conveniences (e.g. punchlist.csv)
links/          optional deep links back to a source model

There is no PDF in this format. Conforming applications neither read nor write PDF. Printing uses the host operating system’s print pipeline; a user who wants a PDF selects the print-to-PDF target their OS already provides.

2. manifest.json — required contract

{
  "calFormat":   1,
  "calMinor":    0,
  "payloadType": "punch",
  "producer":    "Caltior Field HUD 0.1.0",
  "createdUtc":  "2026-07-30T00:00:00Z",
  "title":       "Level 2 electrical — pre-shop review",
  "parts": [
    { "path": "sheets/S001.png", "role": "sheet", "sha256": "…" }
  ]
}

2.1 Version rules

• Refuse, do not partially load. A newer major version must be rejected with a clear message — never opened with unknown fields silently discarded.
• Unknown parts are always ignorable.
• Readers MUST NOT depend on part order beyond entry 0.

2.2 payloadType values

payloadType is an open string. A reader that does not implement a given value MUST refuse the file. Caltior currently documents:

Licences are not a payloadType. Product licence files (for example license.txt) must not be placed inside a .cal archive.

2.3 The .calt extension

.calt denotes a sealed print of a master .cal package: a unique issued artifact whose alteration is detectable. It uses the same media type family and is not a second, incompatible container format. Sealing provides integrity detection; it does not make alteration on a subscriber’s own systems impossible.

3. Interoperability

Because the container is ZIP, a .cal renamed to .zip opens with tools already present on every major operating system and yields usable content with no Caltior software installed.

Caltior’s intent is that a recipient is never dependent on a Caltior application to read data produced on their own project.

4. Security — normative

A .cal file is commonly received from outside the reader’s organisation and must be treated as untrusted input. Conforming readers:

1. MUST reject executable content of any kind. No scripts, macros, formulas, or embedded executables. The format carries images, mesh, and text only.
2. MUST NOT enable type-resolving JSON deserialization (for example Newtonsoft.Json TypeNameHandling). On untrusted input this permits remote code execution.
3. MUST reject archive entry names that are absolute, contain .., or escape the extraction root. Hard failure of the whole file — not a skipped entry.
4. MUST cap total decompressed size and entry count before extraction.
5. MUST treat image and mesh decoding as hostile, with the smallest practical surface.
6. MUST allow-list scheme and host for any entry under links/, rejecting unlisted schemes at parse time. file:, javascript:, vbscript:, and data: are never permitted. Opening a link MUST require deliberate user action.
7. MUST NOT assume confidentiality. A .cal may contain project information confidential to the producer. The format provides integrity but no encryption; confidentiality must come from transport or storage. Producing applications should state, at export, what the file contains and that it can be forwarded.

5. Not in version 1

6. Versioning of this document

This URL, https://caltior.io/spec/cal/1, is stable and describes major version 1. A future incompatible revision will be published at its own address; this document will not be repurposed or removed.