Keep identifiers as identifiers
A field called client could mean an internal ID, a display name or a billing contact. Split those meanings. In a fictional schema, report_id is a string, period_label is approved display text and items is an ordered list. Preserve leading zeros in identifiers. Do not convert a code to a number merely because it contains digits.
Write the mapping beside the template
For each visible element, record its source path, required status, permitted length and missing-value behavior. Example: report.period_label → top-right period box → required → approved month label. A note might permit line breaks but not arbitrary HTML. Mapping decisions are your contract; the presence of a template field does not prove a provider will enforce them.
Test meaning as well as shape
A valid string can still contain the wrong reporting period. Give two fictional reports different IDs and notes, then compare each rendered output with its own source. Test a numeric-looking identifier such as 0042 and text containing an ampersand. Inspect escaping and wrapping rather than assuming the result from the input alone.
Change the contract deliberately
When a field is renamed, identify every template and connector that refers to it. Keep the prior accepted sample and record the effective version. Avoid quietly substituting a new source for an old label. A small change to meaning can be more consequential than a large change to visual styling.
Worked field contract
Use report_id: string, required, preserve exactly; period_label: string, required, approved display text; approved_note: string, optional, hide its heading when absent; items: array, required, empty state explicitly permitted. A required array can still be empty when the contract allows it. Add one negative case that omits items entirely. The omitted array and empty array should not silently become the same accepted business state.
Sources used for this page
These records support the facts and comparisons above. Merchant-controlled records are labelled so you can separate product claims from independent evidence.
- CraftMyPDF: documented template workflow — Merchant documentation · craftmypdf.com · Merchant-controlled · checked 2026-09-30