DocsOpen IDOP Cloud
Preview

Working Draft — not for conformance claims, and may change. The reference core already validates it.

Markdown

IDOP Format Specification 1.1 — Working Draft
Status Working Draft — not for implementation claims; may change without notice
Date 2026-10-04
Base IDOP 1.0 (Candidate Recommendation)
Editor IDOP LABS
Feedback spec@idoplabs.com
License Text: CC BY 4.0

Abstract

This draft lists the changes IDOP 1.1 makes to IDOP 1.0. Everything not mentioned here is unchanged and is defined by the 1.0 text. As 1.0 §15 requires of a minor version, every change is additive: no 1.0 package becomes invalid, no member changes meaning, and a 1.0 Reader that meets a 1.1 package using only the additions below can open it (it ignores _idop/thumbnail.png, as 1.0 §4.3 already tells it to).

The one addition so far is a thumbnail: a picture of the document, for file managers, galleries, cloud listings and share previews, that can be shown without opening the document — and so without running any of its code.

1. Conformance

The conformance language of 1.0 §1 applies. “1.1 Reader” and “1.1 Producer” mean a Reader or Producer that implements this draft in addition to 1.0.

2. formatVersion

A package MAY declare "formatVersion": "1.1". A package that contains any entry defined in this draft MUST declare 1.1 (a 1.0 Producer MUST NOT write reserved _idop/ names, 1.0 §4.3, and that rule is not relaxed for packages that still declare 1.0).

A 1.1 package keeps everything else 1.0 fixes for the container: the format identifier, the mimetype value application/vnd.idop+zip, and "runtimeApiVersion": "1.0" (this draft does not change the Runtime API).

A 1.1 Reader MUST accept 1.0 and 1.1. A 1.0 Reader follows 1.0 §15.

A package that declares 1.0 and nevertheless contains _idop/thumbnail.png is processed as 1.0 §4.3 says: the entry is ignored. A validator SHOULD report it as a warning (IDOP-THUMB-002).

3. Thumbnail — _idop/thumbnail.png

3.1 The entry

The reserved name _idop/thumbnail.png (1.0 §4.3) is defined as follows.

  1. It is OPTIONAL. At most one thumbnail exists, at exactly this path.
  2. It MUST be a PNG image [PNG]: the 8-byte PNG signature, then a valid IHDR chunk.
  3. Its width and height MUST each be between 16 and 1024 pixels, and its size MUST NOT exceed 256 KiB (262 144 bytes, uncompressed entry size). It counts towards the limits of 1.0 §6 like any other entry.
  4. It SHOULD be 4:3 landscape — 640 × 480 is RECOMMENDED — and SHOULD show the document’s first screen as it looks with its current saved state. There is one size only; a Reader that needs a smaller picture scales this one down.
  5. It MUST NOT be animated (no acTL chunk) and SHOULD NOT carry text chunks (tEXt, zTXt, iTXt) or eXIf; see §5.
  6. It is passive: it is not under code/**, it is never loaded into the document’s context, and the Runtime API does not expose it.

application.icon (1.0 §7.3) is unchanged and is a different thing: an icon identifies the application and is the same for every document made with it; a thumbnail shows this document.

3.2 Readers

  1. A 1.1 Reader MAY display the thumbnail wherever it lists or previews a package without opening it.
  2. A Reader MUST decode the thumbnail only as a PNG image, through an image decoder, and MUST NOT interpret its bytes in any other way.
  3. A thumbnail that does not meet §3.1 items 2–3, or whose decoding fails, MUST be ignored: the Reader shows no thumbnail, and the package is otherwise processed as if the entry were absent. A bad thumbnail is never a reason to refuse a package. A validator SHOULD report it as a warning (IDOP-THUMB-001).
  4. Like application metadata (1.0 §7.3), a thumbnail is self-declared. It can show anything, including content the document does not contain or a picture designed to look like a Reader’s own interface. A Reader MUST NOT present it as a verified rendering of the document, and MUST NOT draw it where it could be mistaken for the Reader’s own controls (for example, full-bleed over a permission prompt).
  5. Showing a thumbnail MUST NOT cause any of the document’s code to run and MUST NOT cause any network request.

3.3 Producers and Save

  1. A Producer MAY write a thumbnail when it packs a document.
  2. On Save (1.0 §10.3) a Reader that writes a new revision MUST do one of: keep the existing thumbnail unchanged; replace it with a new rendering; or remove it. A Reader SHOULD NOT keep a thumbnail it has reason to believe no longer matches the saved state, and SHOULD remove rather than keep one it cannot refresh when the change is substantial.
  3. A Reader that renders a thumbnail itself MUST do so from the sandboxed document only (1.0 §9.3), MUST NOT include any of the Reader’s own interface, credentials, environment values or other documents in the picture, and MUST NOT weaken the document’s isolation to take it.
  4. A thumbnail is part of the package’s bytes: it is covered by the same Save, export and container rules as any other entry. It is not part of the code/** digest used for consent (1.0 §12.4), so changing it does not re-prompt for capabilities.

4. Error codes

Code Meaning
IDOP-THUMB-001 _idop/thumbnail.png is present but not a PNG within the limits of §3.1; it is ignored. A warning for validators, never a refusal.
IDOP-THUMB-002 _idop/thumbnail.png is present in a package that does not declare 1.1; it is ignored (§2). A warning, never a refusal.

5. Security and privacy considerations

  • Spoofing. A thumbnail is an arbitrary picture chosen by whoever produced the file. §3.2 item 4 keeps it out of the places where a picture could pass for the Reader’s own interface.
  • Decoder attack surface. Image decoders have had memory-safety bugs. The limits in §3.1 bound the work, PNG is the only allowed format, and Readers SHOULD decode in the same isolation they use for other untrusted images.
  • Disclosure. A thumbnail shows the document’s content to anyone who can list the file — in a shared folder, a cloud listing, a link preview — without opening it. Someone who sends a document sends its thumbnail. Producers SHOULD let the user turn thumbnails off, and SHOULD NOT render one for documents that declare credential or environment bindings unless the user asks. Text and EXIF chunks (§3.1 item 5) are discouraged because they carry data nobody sees in the picture.
  • Staleness. A thumbnail may show an earlier state than the one saved; §3.3 item 2 limits how stale a Reader lets it get, but a recipient cannot rely on it.

6. Resolved questions

Earlier versions of this draft left three questions open. They are settled as follows; comments are still welcome.

  1. One size or two? One. A second, smaller image (for example 128 × 96) would double what a Producer must keep up to date and what a validator must check, for a saving a Reader gets anyway by scaling the one image down. §3.1 item 4 says so.
  2. MUST a Reader remove a thumbnail it cannot refresh? No; it stays a SHOULD (§3.3 item 2). Only the Reader knows whether a change is large enough to make the picture misleading, and a MUST that depends on that judgement could not be tested. §3.2 item 4 and §5 already tell recipients not to trust a thumbnail as a rendering.
  3. WebP or AVIF as well as PNG? No. Every additional format is one more decoder, with its own history of memory-safety bugs, run on untrusted input before the user has opened anything. PNG within the §3.1 limits is small enough; a later minor version can add a format if real packages show otherwise.

Comments to spec@idoplabs.com.

References

  • [PNG] W3C, Portable Network Graphics (PNG) Specification (Third Edition).
  • [IDOP 1.0] IDOP LABS, IDOP Format Specification 1.0.