A hundred letters in a single file

Say, inside the file itself, where one recipient ends and the next begins, with what the finishing needs.

Summary

A run of a hundred statements is one big file and a hundred different letters. The machine that prints and folds them has to know where to cut: two sheets for this one, one for that one. Usually it is told in a second file, kept apart — and the day the two fall out of step, a hundred envelopes go out wrong. Here the recipient's name, their town and their reference travel with the pages, so one single file goes to the workshop and stands on its own.

Technically

Written at the top level of a request, under "document_parts"

document_parts writes the /DPartRoot hierarchy of PDF 2.0: a tree whose leaves each claim a range of pages, and whose nodes carry the named values a finishing workshop reads. A leaf claims its pages either by naming the first and last number, or by counting on from where the document part before it left off; the two ways mix freely. What a document part states is a list of named values, never an object, because the order it is written in is the order it was given.

Request schema

document_parts — object, optional, absent by default. Absent, the file is one single document.
document_parts.root — object, required. The part every other part hangs from.
document_parts.node_names — array of strings, optional, empty by default. What each level of the hierarchy is called, from the root down. A name a job ticket cannot read is refused.
document_parts.record_level — integer, optional. The level whose parts each stand for one recipient, counting the root as level zero.
A node has children (recursive array, empty by default) or claim, never both, never neither.
claim takes two shapes: {"pages": {"first": n, "last": n}} with two integers ≥ 1, a range ending before it starts being refused; or {"next_pages": n} with an integer ≥ 1, taking up where the document part before it left off. Two ranges that overlap are refused.
data — array, optional, empty by default. The named values the part states, in order.
data[].name — string, required. ASCII letters and digits, _, -, . and :, beginning with a letter, _ or :.
data[].value — required. Seven shapes: {"text": s}, {"date": s} in ISO 8601, {"integer": i}, {"real": f}, {"boolean": b}, {"list": …}, {"fields": …} for nested named values.

Document parts are described by clause 14.12 of ISO 32000-2; the example below states "version": "2.0", which is the version reading software wants to honour them.

A whole request that creates a PDF

{
  "version": "2.0",
  "document_parts": {
    "root": {
      "children": [
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Baker and Sons" } }]
        },
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Westmill Dairy" } }]
        }
      ]
    }
  },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "pages": [1],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Baker and Sons"],
      "font": "sans",
      "font_size": 13
    },
    {
      "type": "text",
      "pages": [2],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Westmill Dairy"],
      "font": "sans",
      "font_size": 13
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The numbers reading software shows What the document says about itself What the document says about itself, said once The notes a program leaves in the file for itself The notes a program leaves on one page The data a program hangs on a run of ink A file still readable decades from now The print standard the document claims The password that opens it, and what may be done with it An invoice a person and a machine both read The address relative links are read against The PDF version the file declares What a picture says about itself, and how it is read The attachments the document carries beside its pages The attachments shown as a portfolio Which attachments a page claims The identity card a single page carries The accessibility standard the document claims The standards the finished document is measured against

Where to go next

Every JSON key of a request, in one page The other forty-one settings of a request

See the prices See the examples