The .pdfspace format

A .pdfspace file is a UTF-8 JSON document that holds the original PDF files and every edit made on top of them. Refr's format matches the one PdfSpace writes with System.Text.Json, so a workspace moves between the two apps in either direction.

The model is in crates/refr-core/src/model.rs, and serialization and validation are in crates/refr-core/src/workspace_json.rs.

Conventions

• Property names are PascalCase.
• Enums are numbers.
• Source PDF bytes are base64 (standard alphabet, with padding).
• Identifiers are UUID strings.
• Dates are RFC 3339 / ISO 8601 with an offset, for example 2026-09-27T12:00:00.1234567+00:00.
• Geometry is in PDF points (1/72 inch), in the page's logical coordinate system: origin at the top left, y growing downwards. See Coordinate spaces.
• Colors are ARGB packed in a 32-bit unsigned integer. 4279530470 is 0xFF1473E6, opaque blue.
• When reading, Refr ignores unknown properties, including the computed ones PdfSpace writes (Right, Bottom, Center, IsFinite, VisibleBox, DisplayWidth, DisplayHeight and AnnotationCount). Missing properties get defaults, except where noted.

Example

{
  "FormatVersion": 1,
  "Title": "Report.pdf",
  "Author": "",
  "Sources": [
    { "Id": "6f1c1f57-5d8e-4a57-9d2a-0c1f5c3b6d11", "Name": "Report.pdf", "Bytes": "JVBERi0xLjcK…" }
  ],
  "Pages": [
    {
      "Id": "0b8f3c4e-2c55-4a1e-8f7e-7b0f1b1f2a33",
      "SourceId": "6f1c1f57-5d8e-4a57-9d2a-0c1f5c3b6d11",
      "SourcePage": 1,
      "Width": 595, "Height": 842,
      "Rotation": 90,
      "Crop": null,
      "Bookmark": "Cover",
      "Annotations": [
        {
          "Id": "1d2e3f40-1111-4222-8333-944455556666",
          "Kind": 4,
          "Bounds": { "X": 72, "Y": 120, "Width": 180, "Height": 64 },
          "Points": [],
          "Color": 4279530470,
          "StrokeWidth": 2,
          "FontSize": 14,
          "Text": "",
          "Author": "You",
          "Created": "2026-09-27T12:00:00+00:00",
          "Resolved": false,
          "Replies": []
        }
      ]
    }
  ]
}

Workspace

Source

Sources are immutable. Refr never changes their bytes, and pages only point into them.

Page

The same source page can appear more than once, for example after Duplicate page.

Annotation

Kinds

Rect, Point and Reply

Text layout

Text and stamps wrap using Helvetica's standard (AFM) character widths at FontSize, with a line height of 1.35 × FontSize (crates/refr-core/src/text_layout.rs). Refr lays text out the same way in the viewer and in exported PDFs, so a workspace looks the same in both.

Validation

Refr validates every workspace when it opens it, and every change before it's applied (workspace_json::validate). A workspace that fails any rule isn't opened.

Composition

• Combining (workspace_json::append) gives the incoming sources, pages, annotations and replies new IDs before appending them. You can combine the same workspace with itself.
• Extracting (workspace_json::extract) copies the chosen pages with new IDs and keeps only the sources those pages use.

Security considerations

• A workspace contains complete PDFs. Treat it with the same confidentiality as the original.
• Refr treats workspace contents as untrusted input. The limits above bound memory use, and PDF bytes are only ever parsed by PDFium.