Structured Content

Overview

A Structured Content node embeds a separately-authored document (stored as a YAML or JSON asset) directly inside a REFRACT PDF template. Instead of building long-form text sections (terms and conditions, service agreements, policy clauses) inside the Designer, you write them once as a StructuredDocument asset file and reference it from one or many templates.

When a document is generated, the REFRACT PDF engine pre-fetches the asset before beginning layout composition. The document is then converted to layout blocks and injected in place of the node. All theme colours, TOC integration, and section numbering are applied automatically.

In addition to standard document sections, a structured_content node can host a supplementary_Annex section - a specialised block that appends per-line-item supporting documentation (notes and photo grids) to the end of any REFRACT PDF output.

Node Configuration

Add a structured_content node to your layoutSchema:

{
  "id": "node_terms",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/policies/terms-and-conditions.yaml",
    "library": "assets",
    "conditionContext": {
      "isUK": true,
      "tier": "enterprise"
    }
  }
}

StructuredDocument Format

The asset file (YAML or JSON) must conform to the StructuredDocument shape.

Required Fields

Optional Fields

Minimal YAML Example

documentType: Terms and Conditions
version: "1.0.0"
title: Terms and Conditions

sections:
  - type: heading
    text: Acceptance of Terms
    level: 1

  - type: paragraph
    text: >
      By accessing this service you agree to be bound by these terms.
      Please read them carefully before proceeding.

  - type: heading
    text: Changes to Terms
    level: 1

  - type: paragraph
    text: >
      We reserve the right to modify these terms at any time.
      Continued use of the service constitutes acceptance.

Content Blocks

Every item in sections is a typed block. The type field selects the block renderer. The supplementary_Annex block is documented on its own page. It builds its content from a payload array, and it is not a container for the blocks on this page: only sub_header, repeat_notes, and image_grid can appear in its template. Keep it in its own asset.

image, image_grid and pdf_appendix are also valid top-level block types in sections, for a standalone image or an appended PDF that isn't tied to a payload-driven annex row - see PDF Assets for their full property reference and failure-handling behavior.

heading

Renders a styled section heading. Three depth levels are supported.

- type: heading
  text: "Liability Limitations"
  level: 1

- type: heading
  text: "Indirect Damages"
  level: 2
  includeInToc: false

paragraph

Renders a block of body text.

- type: paragraph
  text: >
    This agreement is governed by the laws of England and Wales.
    Any disputes shall be resolved in the courts of London.

# Literal multi-line (preserves newlines as visible line breaks)
- type: paragraph
  text: |
    Line one.
    Line two indented.
      Further indented line.

list

Renders a bulleted or numbered list. Items have no hanging indent: a wrapped line starts under the bullet, not under the text. Use clause blocks for content that wraps.

- type: list
  style: bullet
  items:
    - "Full\u00A0**24/7**\u00A0support access"
    - Dedicated account manager
    - "_Priority_\u00A0response SLA"

- type: list
  style: ordered
  items:
    - Submit a written notice to the registered address.
    - Allow 30 days for acknowledgement.
    - Escalate to arbitration if unresolved.

note

Renders a styled callout box with an icon, accent stripe, and tinted background. Suitable for warnings, disclaimers, or informational asides.

Variant Reference

- type: note
  variant: warning
  text: >
    Failure to comply with the data retention schedule may result in
    regulatory penalties under applicable data protection law.

- type: note
  variant: info
  label: "Reminder"
  text: "Renew your subscription\u00A0**30 days**\u00A0before expiry to avoid service interruption."

clause

Renders a numbered legal clause with an auto-assigned clause number (section.clause). Clause numbers increment automatically within each level-1 heading section. Only level-1 headings advance the section number, so clauses under a level-2 or level-3 heading repeat the section number (two clauses can both read 1.1). Give anything with numbered clauses a level-1 heading, and use a clause title instead of a level-2 heading.

SubClause shape

- type: heading
  text: Confidentiality
  level: 1

- type: clause
  title: Definition
  text: >
    "Confidential Information" means any information disclosed by one party
    to the other that is designated as confidential or that reasonably should
    be understood to be confidential.

- type: clause
  title: Obligations
  text: >
    Each party agrees to hold the other's Confidential Information
    in strict confidence and not to disclose it to any third party.
  subclauses:
    - text: Not to copy or reproduce Confidential Information without prior consent.
    - text: To use the same degree of care as it uses for its own confidential information.
    - text: To limit access to personnel with a need to know.
      condition: isEnterprise

table

Renders a table of static text: a parties block, a fee schedule, a list of deliverables. Use it for text you write in the YAML. For a table bound to a payload array, use the Table control in the template layout instead.

Both shapes are tagged for Section 508 and PDF/UA, so a screen reader announces each cell together with its header.

• Key-value table. No header, exactly two columns: a label and a value. The label cell is a row header, so a screen reader reads "Provider, Example Services LLC".
• Header table. A header row with any number of columns. The header cells are column headers, and the header row repeats at the top of each page when the table continues onto another page.

Cells accept inline formatting, {{variables}}, and pipe filters. Like every block, a table accepts a condition.

Rules

• No header means exactly two columns. A table with three or more columns and no header fails the render, because a screen reader could not tell the columns apart.
• Every row needs as many cells as the table has columns. A short or long row fails the render and names the row.
• widths and align need one entry per column. A wrong count or an unknown value fails the render.
• Header cells and key-value labels do not wrap. If a fixed-width column is too narrow for its header or label, the renderer logs [table] ... cannot wrap. Widen the column or shorten the text.
• There is no cell merging, no per-cell colour, and no images in cells. Use supplementary_Annex for images.
• A table has no title field. Put a heading or paragraph above it when it needs one.

Example: parties block (key-value)

- type: table
  rows:
    - ["Provider", "Example Services LLC"]
    - ["Client", "Acme Corp"]
    - ["SOW reference", "SOW-2026-001"]
    - ["Effective date", "The date of the last signature"]
    - ["Provider signatory", "Jane Smith, Managing Member"]
    - ["Client signatory", "John Doe, Vice President"]

There is no header and there are two columns, so this is a key-value table. The default widths give the label column 130 points and the value column the rest.

Example: milestone schedule with a total row

- type: table
  header: ["Milestone", "Deliverables", "Due"]
  widths: ["*", 100, 100]
  align: [left, right, left]
  totalRow: true
  rows:
    - ["Kickoff", "2", "At kickoff"]
    - ["Readout and delivery of deliverables", "3", "At readout"]
    - ["Total deliverables", "5", ""]

The first column takes the remaining width, the deliverables and due columns are 100 points each, and the counts are right-aligned. The last row is bold and shaded. The empty "Due" cell is written "".

Example: values from the payload

- type: table
  header: ["Item", "Quantity", "Due date"]
  align: [left, right, left]
  rows:
    - ["{{line1.description}}", "{{line1.qty}}", "{{line1.due|date}}"]
    - ["Kickoff workshop", "1", "{{kickoff_date|date}}"]

Variables are resolved before the markup is parsed, and pipe filters such as |date work as they do in a paragraph. With a payload of line1.due: "2026-10-01" and no dateFormat in the template settings, the cell renders as 10/1/2026. An unresolved variable becomes an empty string, so a missing value leaves the cell blank without an error.

Example: a longer table that may split across pages

- type: table
  header: ["Deliverable", "Owner", "Due"]
  widths: ["*", 110, 90]
  keepTogether: false
  rows:
    - ["Current-state assessment", "Provider", "Week 1"]
    - ["Stakeholder interviews", "Both parties", "Weeks 1 to 2"]
    - ["Architecture options paper", "Provider", "Week 3"]
    - ["Proposal for the build", "Provider", "Week 4"]

keepTogether: false lets the table break across pages. The header row repeats on the new page, and a row is never cut in half.

Example: a conditional table

- type: table
  condition: include_expenses
  header: ["Expense", "Rule"]
  rows:
    - ["Travel", "Agreed in advance, billed at cost"]
    - ["Software licenses", "Purchased separately"]

The table renders only when include_expenses is truthy in the context. Write the key without braces. See Conditional Blocks.

Common mistakes

Three columns without a header fails the render:

# Fails: a table without "header" must have exactly 2 columns (label, value) but has 3.
- type: table
  rows:
    - ["Kickoff", "2", "At kickoff"]

Add header: ["Milestone", "Deliverables", "Due"].

A row with the wrong number of cells fails the render:

# Fails: row 1 has 2 cells but the table has 3 columns.
- type: table
  header: ["Milestone", "Deliverables", "Due"]
  rows:
    - ["Kickoff", "2"]

Write ["Kickoff", "2", ""] for an empty last cell.

signature_block

Renders one or more signature slots in a table layout. Each signatory gets a REFRACT eSign anchor token, [[SIGN_<ROLE>|required]], that binds the signing zone to a signer by role when the document is sent through REFRACT eSign. Use one signature_block per document: signer numbering restarts in each block, and a document with two blocks has not been tested with a real eSign request.

Signatory shape

# Simple auto-generated single slot
- type: signature_block
  title: Authorization
  includeName: true
  includeDate: true

# Multi-signatory with two columns
- type: signature_block
  title: Agreed by both parties
  columns: 2
  signatories:
    - role: Customer Representative
    - role: Refract Logic Account Manager
      name: Jane Smith
      date: "2026-03-28"

checkbox

Renders a checkbox icon followed by a label. Useful for acknowledgement lists and form-like documents.

- type: checkbox
  label: "I have read and understood the\u00A0**Privacy Policy**."
  checked: false

- type: checkbox
  label: "I consent to receiving email communications."
  checked: true

radio

Renders a radio-button icon followed by a label. Use multiple radio blocks with the same group value to represent an option set.

- type: radio
  label: Standard plan
  group: plan
  selected: false

- type: radio
  label: "**Enterprise**\u00A0plan (includes SLA)"
  group: plan
  selected: true

input

Renders a labelled form field. The block is used by portal form steps, and it also prints in the PDF: when the context has a value for fieldKey, the PDF shows that value, and otherwise it shows the field's placeholder.

- type: input
  label: Contact email
  fieldKey: contactEmail
  inputType: email
  placeholder: name@example.com
  validation:
    required: true
    message: Enter a valid email address.

attachment

Renders a file-attachment field. The block is used by portal form steps. In the PDF it shows an [Attachment] placeholder until a file is submitted, then lists the attached file.

- type: attachment
  label: Signed purchase order
  fieldKey: purchaseOrder
  accept: ".pdf"
  maxSizeMb: 10
  required: true

page_break

Inserts a hard page break. Subsequent blocks start at the top of a new page. A step_boundary block renders as a page break too. Do not end a document with a page_break: it adds a blank last page that holds only the header and footer.

- type: page_break

Inline Formatting

All text-bearing blocks (paragraph, heading, list items, clause, note, checkbox, radio) support inline formatting markers.

Markers do not nest. Unmatched open markers are treated as plain text. Markers also match inside words: SOW_REF_2026_001 renders as the italic SOWREF2026001, and a pair of == in prose highlights the text between them. There is no escape syntax, so keep raw underscores and paired == out of identifiers and prose.

Variable Substitution

Use {{varName}} or {{dot.path}} placeholders in any text field. At render time these are replaced with matching values from conditionContext (or the merged context from the payload). An unresolved variable renders as an empty string, and no warning is produced. Supply every variable the document uses, and list them in a comment at the top of the YAML.

- type: paragraph
  text: "This agreement is entered into by\u00A0**{{customerName}}**\u00A0(the \"Customer\") and Refract Logic LLC on {{effectiveDate}}."

- type: clause
  text: >
    The agreed monthly fee is {{pricing.monthlyFee}} per seat,
    billed on the {{billing.dayOfMonth}}th of each month.

Substitution is resolved from the merged context in priority order:

1. Raw payload fields (lowest priority)
2. conditionContext set in node.props
3. conditionContext from payloadData.conditionContext (global override)
4. payloadData.structuredContentOverrides[nodeId].conditionContext (per-node, highest priority)

Field Names with Dots or Spaces

The substitution engine uses greedy longest-match, so field names containing dots (.) or spaces are supported without any escaping:

- type: paragraph
  text: "Order {{Header.No.}} raised on {{Header.Order Date}}."

{{Header.No.}} resolves the literal key "No." on Header, and {{Header.Order Date}} resolves the key "Order Date" - neither requires quoting or encoding in the template.

Pipe Filters

Append a pipe filter to a placeholder to format its value at render time:

- type: paragraph
  text: "Effective {{effectiveDate|date}} - total {{summary.amount|currency}} for {{summary.count|number}} items."

Conditional Blocks

Any block can carry a condition field. The block is skipped entirely when the condition evaluates to falsy.

- type: note
  variant: warning
  condition: isUK
  text: "This section applies exclusively to customers domiciled in the United Kingdom."

- type: clause
  condition: "pricing.monthlyFee > 5000"
  title: Enterprise Discount
  text: "Customers with a monthly fee exceeding £5,000 qualify for the enterprise discount programme."

Condition Forms

Payload-Level Overrides

Without modifying the .rpkg template, you can control individual structured_content nodes from the render payload.

Global context override

Applies to all structured_content nodes in the document:

{
  "templateId": "service-agreement-v2",
  "conditionContext": {
    "isUK": true,
    "tier": "enterprise"
  },
  "customerName": "Acme Corp"
}

Per-node override (by node id)

Targets a specific node and takes highest priority:

{
  "templateId": "service-agreement-v2",
  "structuredContentOverrides": {
    "node_terms": {
      "visible": false
    },
    "node_dpa": {
      "conditionContext": {
        "isGDPR": true
      }
    }
  }
}

TOC Integration

When templateSettings.toc.enabled is true, heading blocks from structured_content nodes are automatically merged into the document-level Table of Contents.

• Flat mode (tocMode: "flat" or default): only level-1 headings appear as TOC entries.
• Nested mode (tocMode: "nested"): level-1 headings are parents; level-2 headings are indented children.

includeInToc: false on an individual heading excludes it regardless of mode.

When a structured_content node hosts a supplementary_Annex section with includeInToc: true, each qualifying line item emits a TOC sub-entry that is merged into the same document TOC at the correct depth. These entries appear as children of the annex title heading and inherit the active sectionNumbering prefix (e.g. 2.1, 2.2).

Section Numbering

When templateSettings.sectionNumbering is true, level-1 headings inside structured_content blocks receive auto-incrementing ordinal prefixes (1., 2., 3.) that are continuous with the rest of the document's section counter.

Pagination

Pagination hints from the surrounding node are respected:

Keeping blocks together

Blocks also control where they may break across pages:

• Clauses, subclauses, and list items stay on one page by default, so a number never sits on one page with its text on the next. A row longer than 2000 characters may still split, so split a very long clause into several.
• A heading stays on the same page as the block after it (a clause, paragraph, list, or note) when that block is at most 2000 characters. Set keepWithNext: false on the heading to let it sit at the foot of a page. A heading before a longer block, a signature block, an input, or anything else can still be left at the foot of a page: put a page_break before it.
• A table or a note stays on one page by default. A table of more than 2000 characters may split, and rows never split.
• keepTogether: true on a clause keeps the clause and all its subclauses on one page, and on a list keeps the whole list on one page. It must fit on a page: a block taller than a page is laid out splittable and a warning is logged, instead of failing the render.
• keepTogether: false lets a clause, list, table, or note split across pages.

A kept-together block that does not fit in the space left on a page moves whole to the next page and leaves a gap. That is intended.

Accessibility

Structured content is tagged for Section 508 and PDF/UA. The structure a screen reader sees follows the block types:

Known Limitations

These are behaviours of the current renderer, not authoring mistakes. Author around them until the renderer changes.

Designer Preview

In the Designer (which has no asset access), the node renders a visible grey placeholder:

[Structured content: Documents/policies/terms-and-conditions.yaml]

If pre-fetching fails inside the Designer, a red error message is shown instead:

[Structured content error: Documents/policies/terms-and-conditions.yaml]
HTTP 404: The specified resource does not exist.

This red inline error is Designer-only. In a real server render, the asset-resolution step runs before layout and re-throws any fetch failure as an error that fails the whole render, rather than rendering the document with an inline placeholder for that node - check the render error for the asset path and HTTP status rather than expecting a partial PDF.

The grey and red placeholders above apply to the whole structured_content node, regardless of what block types it contains - the Designer's browser-side preview (playground-client.js) never runs the asset-resolution step at all, since it has no server-side storage credentials, so it can't distinguish block types within a node it hasn't fetched. This is unrelated to image/image_grid/pdf_appendix block rendering, which is a real server-render concern, not a preview one - see PDF Assets for that rendering behavior.

Full Document Example

A complete master-services-agreement.yaml illustrating all block types:

documentType: Master Services Agreement
version: "3.0.0"
title: Master Services Agreement
region: UK
effectiveDate: "2026-01-01"
tocMode: nested

sections:
  # Section 1
  - type: heading
    text: Definitions
    level: 1

  - type: paragraph
    text: >
      In this Agreement the following terms shall have the meanings set out below.
      All other capitalised terms are defined where they first appear.

  - type: clause
    title: Agreement
    text: >
      Means this Master Services Agreement, including all Schedules and
      Order Forms incorporated by reference.

  - type: clause
    title: Confidential Information
    text: >
      Means any information disclosed in connection with this Agreement that
      is designated confidential or that a reasonable person would consider
      confidential given the circumstances of disclosure.

  # Section 2
  - type: heading
    text: Services
    level: 1

  - type: heading
    text: Scope of Services
    level: 2

  - type: paragraph
    text: >
      Refract Logic LLC shall provide the services set out in each Order Form
      executed under this Agreement (**"Services"**).

  - type: note
    variant: info
    text: >
      Service specifications, SLAs, and pricing are defined in the relevant
      Order Form and Schedule A attached hereto.

  # Section 3 (conditional)
  - type: heading
    text: Data Protection (UK/EU)
    level: 1
    condition: isGDPR

  - type: paragraph
    condition: isGDPR
    text: >
      The parties agree to comply with the UK GDPR and any applicable
      successor legislation in respect of all personal data processed
      under this Agreement.

  - type: note
    variant: warning
    condition: isGDPR
    text: >
      A Data Processing Addendum (**DPA**) must be signed separately before
      any personal data is transferred between the parties.

  # Section 4
  - type: heading
    text: Fees and Payment
    level: 1

  - type: clause
    title: Fees
    text: "The Customer shall pay the fees set out in the applicable Order Form. The monthly fee of\u00A0**{{pricing.monthlyFee}}**\u00A0per seat is invoiced in advance on the first business day of each calendar month."
    subclauses:
      - text: All fees are exclusive of VAT and other applicable taxes.
      - text: "Enterprise customers (>£5,000/month) receive a 5% volume discount."
        condition: "pricing.monthlyFee > 5000"

  # Acknowledgement
  - type: heading
    text: Acceptance
    level: 1

  - type: paragraph
    text: >
      By executing this Agreement the parties confirm they have read,
      understood, and agree to be bound by all terms herein.

  - type: checkbox
    label: "Customer has received and reviewed Schedule A (Service Specifications)."
    checked: false

  - type: checkbox
    label: "Customer has received and reviewed Schedule B (Data Processing Addendum)."
    condition: isGDPR
    checked: false

  - type: page_break

  - type: signature_block
    title: Signatures
    columns: 2
    signatories:
      - role: Customer Representative
      - role: Refract Logic Authorized Signatory

Related Pages

• Supplementary Annex - per-line-item supporting documentation section hosted inside a structured_content node
• Template Settings - toc, sectionNumbering, dateFormat, and locale options that affect structured content rendering
• Hierarchical Table - the main data table whose Notes/Images columns are suppressed when a supplementary annex is active
• Table - the Table control, for tables bound to a payload array. The table block on this page is for static text written in the YAML