Data Injection Overview

Data injection lets you build reusable document templates with placeholder references that are resolved at generation time. Instead of hardcoding values into your document definition, you use $data references that get replaced with actual data when the PDF is generated.

How it works

1. Author a template with $data.path.to.value references in your document definition.
2. Provide a data object alongside the template when generating a PDF.
3. DocPayload resolves all $data references, replacing them with values from your data object.
4. The PDF is rendered with the resolved content.

Scalar references

The most basic form of data injection is a scalar reference -- a $data path that points to a single value in your data object.

Template

{
  "document": {
    "styles": {
      "title": { "fontSize": 18, "bold": true },
      "highlight": { "fontColor": "#E94560", "bold": true }
    },
    "content": [
      { "p": "Invoice for $data.client.companyName", "style": "title" },
      { "p": "Invoice Number: $data.invoice.number" },
      { "p": "Prepared by: $data.user.name" },
      { "p": "Contact: $data.user.email" },
      { "p": "Amount Due: [b]$data.invoice.totalAmount[/b]", "style": "highlight" }
    ]
  }
}

Data

{
  "client": {
    "companyName": "GlobalTech Industries"
  },
  "user": {
    "name": "Laura Bennett",
    "email": "laura.bennett@shipforge.io"
  },
  "invoice": {
    "number": "INV-2026-0317",
    "totalAmount": "$24,500"
  }
}

Result

The resolved paragraphs become:

• "Invoice for GlobalTech Industries"
• "Invoice Number: INV-2026-0317"
• "Prepared by: Laura Bennett"
• "Contact: laura.bennett@shipforge.io"
• "Amount Due: $24,500"

Path syntax

References use dot-separated paths to traverse nested objects in your data.

Reference	Data path
$data.name	Top-level name property
$data.client.companyName	companyName inside client object
$data.client.address.city	city inside address inside client

Array indexing

Use bracket notation to access specific elements in arrays:

Reference	Description
$data.items[0].name	First element's name property
$data.company.bills[3].amount	Fourth bill's amount inside company
$data.matrix[0][1]	Chained indexes — row 0, column 1
$item.addresses[0].city	Array indexing inside $item context

{ "p": "Primary contact: $data.contacts[0].name — $data.contacts[0].email" }

With data:

{
  "contacts": [
    { "name": "Alice Chen", "email": "alice@acme.com" },
    { "name": "Bob Park", "email": "bob@acme.com" }
  ]
}

This renders: "Primary contact: Alice Chen — alice@acme.com"

Array indexing works everywhere $data references work, including inside $item paths when iterating table/list data. If the index is out of bounds or the value is not an array, the reference is preserved as-is.

Where references work

$data references are supported in:

• Paragraph text -- { "p": "Hello $data.user.name" }
• Inside inline formatting tags -- { "p": "[b]$data.invoice.total[/b]" }
• Form field default values -- [textfield, name, '$data.applicant.name', 200|20]
• Header and footer content -- references are resolved in repeating content too
• Columns layout content -- references work inside multi-column layouts

Unresolved references

If a $data reference points to a path that does not exist in the provided data object, the reference text is preserved as-is in the output. This means $data.missing.key will appear literally as "$data.missing.key" in the PDF.

{ "p": "Unresolved ref stays: $data.missing.key" }

This behavior ensures that missing data does not cause generation failures, while making it easy to spot missing values in the output.

References inside inline formatting

$data references work inside any inline formatting tag. The reference is resolved first, then the formatting is applied.

{ "p": "[b]Client:[/b] $data.client.companyName - [fontcolor, #CC0000]$data.client.address.city[/fontcolor]" }

With data { "client": { "companyName": "Meridian Logistics", "address": { "city": "Denver" } } }, this renders as:

Client: Meridian Logistics - Denver

Beyond scalar references

DocPayload supports two additional data injection mechanisms for populating collections:

• Data Provider -- Populate table rows from arrays of objects and list items from string arrays.
• Templates -- Store document definitions as reusable templates and generate PDFs by passing data at request time.
• Globals -- Built-in $global.* tokens for date, time, page numbers, and document metadata, no data object required.

Quick comparison

Feature	Syntax	Use case
Scalar ref	$data.path.to.value	Replace individual values in text
Array index	$data.items[0].name	Access a specific array element by position
Table source	"source": "$data.items"	Generate table rows from an array
List source	"source": "$data.notes"	Generate list items from an array
Global token	$global.NAME	Built-in values: date, page numbers, metadata