A hundred letters in a single file

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

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. Here, it can be written into the document itself, with the recipient's name, their town, their reference. One single file goes to the workshop, and it stands on its own.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

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

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• 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 carries 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 run ending before it starts being refused; or {"next_pages": n} with an integer ≥ 1, taking up where the part before it left off. Two runs 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 a reader wants to honour them.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "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