Structure JSON Data for Build a Doc

Build a Doc requires structured data to populate template placeholders at runtime. This guide shows you how to structure your JSON data correctly for both the Power Platform connector and the Word Add-in.

---

Prerequisites

• A Build a Doc subscription and API key (see Generate an API Key)
• A Word template with Build a Doc syntax (see Word Template Syntax)
• Familiarity with how templates and data binding work in Build a Doc

---

What is JSON?

JSON (JavaScript Object Notation) is a lightweight text-based data format used to store and exchange structured information. It uses human-readable key-value pairs to represent data.

Basic JSON Structure

JSON has two fundamental structures:

Objects - Enclosed in curly braces {}, containing key-value pairs:

{
  "name": "John Smith",
  "age": 30,
  "city": "London"
}

Arrays - Enclosed in square brackets [], containing ordered lists of values:

["apple", "banana", "orange"]

Key-Value Pairs

A key-value pair consists of:

• Key - A string identifier (must be in double quotes)
• Colon - Separates the key from its value
• Value - Can be a string, number, boolean, object, array, or null

Example:

{
  "productName": "Laptop",
  "price": 1200,
  "inStock": true
}

JSON objects and arrays can be nested to represent complex data structures, making JSON ideal for representing hierarchical data.

---

Understanding the JSON Data Structure

Document generation in Build a Doc requires two components: a template containing Build a Doc templating syntax, and a data source of structured data that populates those placeholders.

When you provide JSON data to a Build a Doc action, the method of supplying the required Name and Data properties differs depending on the Build a Doc feature that you are using. The parameters are:

• Name - The identifier used in the template to reference this data source.
• Data - An object ({...}) containing the actual data that maps to your template placeholders.

Caution

• The Name property must be a string
• The Data property must always be an object (i.e. "Data": {...}). It cannot be a string, number, or bare array at the top level.
• The outer structure must be an array ([...]) containing these objects. Using Build a Doc via a Power Automate action will input your parameters into the correct format automatically.

---

Structuring JSON for the Power Platform Connector

When using the Build a Doc Power Platform connector in Power Automate, the data source fields are provided as action parameters. Each Build a Doc action (such as Convert Word Document) accepts two data source parameters:

Parameter	Type	Description
Data source Name	String	Identifier used in the template to reference this data
Data source Data	Object/List	The actual data (object or array)

In the connector, the Name parameter of the action becomes the name of the data source, and the Data parameter provides the data itself. Together, these supply the data source for the action.

Example: Single Data Source

To populate an invoice template with tags like <<[Invoice.InvoiceNumber]>>, configure the action as follows:

• Data source Name: Invoice
• Data source Data:

{
  "InvoiceNumber": "INV-2025-001",
  "InvoiceDate": "2025-03-15",
  "Customer": {
    "Name": "Roger Woodfield",
    "Email": "roger@example.com"
  },
  "Items": [
    {
      "Description": "Web Development",
      "Quantity": 1,
      "Price": 3500
    }
  ],
  "TotalAmount": 3500
}

The Name value must match the template tags - Invoice in the Data source Name matches <<[Invoice.InvoiceNumber]>> in the template.

Tip

Keep your JSON keys aligned with the properties used in the template. Property names are case-sensitive - "Customer" in your JSON must match Customer in your template expression exactly. See Word Template Syntax for full syntax rules.

Example: Multiple Data Sources

You can pass multiple named data sources to a single action. Each data source has its own Name, Data, and Format:

Name	Data
Company	{ "Name": "Acme Ltd" }
Invoice	{ "Number": "001", "Items": [...] }
Metadata	{ "GeneratedDate": "2025-01-22" }

In your template, reference each by name: <<[Company.Name]>>, <<[Invoice.Number]>>, <<[Metadata.GeneratedDate]>>.

Note

For the complete list of actions and their parameters, see the Actions Reference Guide.

---

Structuring JSON for the Word Add-in

When using the Word Add-in to preview templates, the Name and Data fields must be provided as key-value pairs within the JSON itself. The JSON must be wrapped in array brackets ([]) and must include the Name and Data properties, or it will not match the expected schema and an error message will be displayed.

Example: Single Data Source

[
  {
    "Name": "Invoice",
    "Data": {
      "InvoiceNumber": "INV-2025-001",
      "InvoiceDate": "2025-03-15",
      "Customer": {
        "Name": "Roger Woodfield",
        "Email": "roger@example.com"
      },
      "Items": [
        {
          "Description": "Web Development",
          "Quantity": 1,
          "Price": 3500
        }
      ],
      "TotalAmount": 3500
    }
  }
]

Example: Multiple Data Sources

[
  {
    "Name": "Company",
    "Data": {
      "Name": "Acme Ltd"
    }
  },
  {
    "Name": "Invoice",
    "Data": {
      "Number": "001",
      "Items": [{ "Description": "Consulting", "Quantity": 2, "Price": 500 }]
    }
  },
  {
    "Name": "Metadata",
    "Data": {
      "GeneratedDate": "2025-01-22"
    }
  }
]

Caution

The Add-in requires the array-only format shown above. Do not wrap your data in an outer object. The array format enables proper template validation and preview generation.

For step-by-step instructions on previewing templates, see Preview Templates with Sample Data.

---

Comparison: Connector vs. Add-in JSON Format

Aspect	Power Platform Connector	Word Add-in
Where Name is set	In the action’s Data source Name parameter	As a "Name" key-value pair inside the JSON array
Where Data is set	In the action’s Data source Data parameter	As a "Data" key-value pair inside the JSON array
Outer structure	Data field contains the object directly	Must be wrapped in array brackets [...]
Required properties	Set via action UI fields	"Name" and "Data" must appear in the JSON
Schema validation	Validated by the connector action	Must match the expected schema or an error is shown

---

Types of Data in JSON

Your Data object can contain three types of values that map to different template features:

Simple Fields

Direct key-value pairs for straightforward placeholders:

{
  "InvoiceNumber": "INV-2025-001",
  "InvoiceDate": "2025-03-15"
}

Template: <<[InvoiceNumber]>>

Nested Objects

Grouped data accessed with dot notation:

{
  "Customer": {
    "Name": "Roger Woodfield",
    "Address": {
      "City": "London"
    }
  }
}

Template: <<[Customer.Name]>>, <<[Customer.Address.City]>>

Arrays

Repeating data used with foreach loops:

{
  "Items": [
    { "Description": "Web Development", "Quantity": 1, "Price": 3500 },
    { "Description": "Design", "Quantity": 2, "Price": 1500 }
  ]
}

Template:

<<foreach [item in Items]>>
<<[item.Description]>> - <<[item.Quantity]>> x £<<[item.Price]>>
<</foreach>>

For full syntax documentation including conditionals, loops, variables, and LINQ expressions, see the Word Template Syntax reference.

---

JSON Formatting Rules

Follow these rules to ensure your JSON is valid:

Rule	Correct	Incorrect
Array format	[{ "Name": "John" }]	{ "Name": "John" }
Quotes	"Name": "John"	'Name': 'John'
Case sensitivity	"Customer"	"customer"
Trailing commas	"A": 1, "B": 2	"A": 1, "B": 2,

Tip

JSON requires double quotes around all keys and string values. Single quotes, trailing commas, and unquoted keys are not valid JSON and will cause parsing errors.

---

Validate and Format Your JSON

Before using your JSON data in Build a Doc, validate it to catch syntax errors early.

Use an Online Validator

Use a tool such as JSON Formatter & Validator to:

• Check for syntax errors (missing brackets, trailing commas, incorrect quotes)
• Auto-format and indent your JSON for readability
• Identify the exact location of any errors

Validate in the Word Add-in

The Build a Doc Word Add-in provides built-in JSON validation when you preview a template. It includes:

• JSON syntax validation
• Error highlighting
• Immediate feedback when the JSON does not match the expected schema

Debugging Data Issues

If your template produces unexpected output or errors:

1. Validate your JSON using a validator tool
2. Ensure the structure matches your template expectations
3. Check for special characters that might need escaping
4. Verify that all property paths in your template exist in your JSON (paths are case-sensitive)

For more information on resolving errors, see Debug Template Validation Errors.

---

Handling Null and Missing Values

When a property referenced in your template is missing or null in your JSON data:

• Missing or null values evaluate to null / undefined
• if blocks that reference them will not render
• Standalone placeholders produce no output

Use null checks or a null-coalescing pattern to provide fallback values:

<<if [Customer.Phone]>>Tel: <<[Customer.Phone]>><</if>>
<<[Customer.Phone ?? "N/A"]>>

For more on null handling, see Templates and Data Binding.

---

Next Steps

• Connect a Data Source
• Preview Templates with Sample Data
• Use the Connector in Power Automate
• Templates and Data Binding
• Actions Reference Guide