CaseLeaf

Handbook / What is written into the file

What is written into the file

What CaseLeaf puts into a PDF, and what it deliberately does not.

Marks are standard PDF annotations

Highlights, underlines, strike-throughs, shapes, freehand, text boxes, notes and signatures before they are flattened are all ordinary PDF annotations. They are visible in Preview, in Acrobat and in anything else that reads PDFs. Nothing here is a private format.

The history goes in the document's metadata

The paper trail lives in the PDF's XMP metadata, under a namespace of CaseLeaf's own. It travels with the file rather than living in a database on this machine.

XMP was chosen because it survives. Of the places a marker can be put in a PDF, XMP and the Keywords field are the only two that come through a full rewrite by Preview. Custom entries in the Info dictionary and embedded file attachments are both destroyed, and extended attributes do not survive a copy to a network volume.

Writing it is a PDF incremental update: the original bytes are left exactly as they are, a new version of the metadata is appended, and a small cross-reference section points at it. Nothing is re-rendered and nothing is recompressed. A reader that stops at the first end-of-file marker still sees a valid, older document, so a failed write cannot corrupt anything.

Bookmarks, snapshots, the document's colour scheme and page calibrations are kept in the same place.

Extra information carried by some marks

Some marks carry a little extra in keys other readers ignore:

  • A black-out says it is one, so making the document permanent removes what it covers instead of painting over it. It says so in a standard subject field, which survives a rewrite, and in a private key.
  • The reason a passage was blacked out is kept in a private key on purpose, so it does not travel. A reason is itself a small disclosure: knowing a box holds personal data rather than commercially confidential material narrows what is under it. So it must not appear as a note another application would show.
  • A signature carries a marker saying it is one, in a field the system's PDF library preserves.
  • A reply carries the identity of what it answers, in a key of CaseLeaf's own. Once the document is rebuilt, PDF's own reference is written instead.

What is protected against

Saving goes out of its way not to lose what it did not write. Embedded file attachments, page labels and radio-group flags would otherwise be dropped in a rewrite. CaseLeaf carries them across deliberately.

For example, an underline you draw is saved as a standard /Underline annotation:

/Subtype        = /Underline
/C              = 1 0.552941 0.156863   (the armed colour)
/QuadPoints     = the four corners of the marked line
/T              = Reader, Ada       (whoever signed it)
/M              = 2026-08-22 21:02:39 +0000
/CaseLeafMade   = 1
/CaseLeafMarking = underline

It has standard colour, author and date fields, and CaseLeaf's own extra information in keys another reader ignores. caseleaf marks on the command line lists every mark in a file with its kind and the words it covers.

A copy made by File ▸ Save As… is the original document with your marks appended: every attachment, page label, named destination and bookmark stays exactly where it was, byte for byte. That matters if you send the copy to somebody else.

The XMP packet lives under the namespace https://caseleaf.app/ns/1.0/. It holds log:history, log:bookmarks and log:snapshots, each a small piece of JSON. One history line reads {"event":"reviewed","at":"2026-08-23T01:49:46Z","note":"…"}.

Two exceptions: flattening a document does not carry layers across, nor the tree that maps page content to its structure elements. Both live inside the page content that is redrawn. Page labels, bookmarks and attachments are carried.

See also

Watch: a short video for this page is still to come.

Contents