Preparing a JSON File for Import

Preparing a JSON File for Import

JSON (JavaScript Object Notation) is a lightweight, human-readable format ideal for structured data. Unlike CSV files, all JSON files must go through a Data Transformation step before they can be processed by the Import Module. While the structure described below is a strong recommendation for predictable results, it is not a strict technical requirement as long as your transformation can handle your specific JSON format.

How JSON is Converted to XML for Transformation

Before your data can be mapped, the system automatically converts your JSON file into a standardized XML format. This is why a Data Transformation is always required for JSON files—you must write a transform to convert this intermediate XML into the final format the importer expects.

During this automatic conversion:
  1. The entire JSON file becomes the content of a single <root> root element.
  2. Each JSON value is converted into a string, regardless of its original type (number, boolean, etc.).
For example, a simple JSON object like this:
  1. {
  2.   "StudentID": 2187,
  3.   "IsActive": true
  4. }
Is converted into this XML structure before your transformation is applied:
  1. <root>
  2.     <StudentID>2187</StudentID>
  3.     <IsActive>true</IsActive>
  4. </root>
Your transformation stylesheet will then need to process this XML.
To ensure a consistent and predictable XML output for your transformation, we strongly recommend that the root of your JSON file be a single array ( [...] ). Each element within that array should be a JSON object ( {...} ), where each object represents a person or record to be imported.

Inside each object, the keys represent the column headers, and the values represent the data.

Example: Simple JSON File
  1. [
  2.   {
  3.     "StudentID": 2187,
  4.     "IEP_MeetingDate": "2025-09-15",
  5.     "CaseManager": "Ms. Garcia"
  6.   },
  7.   {
  8.     "StudentID": 3451,
  9.     "IEP_MeetingDate": "2025-10-02",
  10.     "CaseManager": "Mr. Chen"
  11.   }
  12. ]

Advanced Structure: Handling Repeaters

To import data into a repeater on your form, you can use a nested array of objects. Create a key in your main object whose value is an array. Each object inside this nested array will correspond to one instance of the repeater.

Example: JSON with Repeater Data
  1. [
  2.   {
  3.     "StudentID": 4876,
  4.     "PrimaryContact": "Maria Garcia",
  5.     "EmergencyContacts": [
  6.       {
  7.         "ContactName": "Maria Garcia",
  8.         "ContactPhone": "555-0101"
  9.       },
  10.       {
  11.         "ContactName": "Luis Garcia",
  12.         "ContactPhone": "555-0102"
  13.       }
  14.     ]
  15.   }
  16. ]
In your Data Transformation, you will write the logic to loop through the EmergencyContacts XML elements and format them correctly for import into the repeater fields.

Next Steps

Now that you understand the recommended structure for a JSON file and how it's converted for transformation, you're ready to learn about the main interface for managing all your import configurations.

Next Article: Understanding the Import Dashboard

    • Related Articles

    • Preparing an XML File for Import

      XML (Extensible Markup Language) is a powerful format for handling complex or hierarchical data. Because XML files can have virtually any structure, they must go through a Data Transformation step to be processed by the Import Module. While any valid ...

    • Quick Start Guide: Your First Import

      This guide provides a step-by-step walkthrough to help you complete your first basic import. We'll use a sample CSV file containing basic IEP information and a manual import to demonstrate the core workflow from start to finish. Before You Begin For ...

    • Import Error Code Reference

      When an import fails, the system will log an error code to help you diagnose the problem. This guide explains what each error code means and provides step-by-step instructions on how to resolve the issue. E0001: Cannot Read File Problem The system ...

    • Import Module Terminology

      The Import Module allows you to bring data into your forms from external files. Understanding the terminology is crucial for configuring imports, preparing data, and troubleshooting effectively. This guide defines the key concepts you'll encounter. ...

    • Preparing a CSV or TSV File for Import

      A correctly formatted CSV (Comma-Separated Values) or TSV (Tab-Separated Values) file is essential for a successful import. While these are standard formats, your file must adhere to specific rules to ensure data is processed accurately. Basic File ...