Skip to main content
Skip table of contents

Importing and Exporting Custom Form Definitions

A custom form definition, also known as, form schema, is stored in XNAT as a JSON. Importing and exporting a custom form definition involves handling the JSON representing the form schema. 

Note that at this point, the following advanced tracking features for custom form importing are not supported:

  • Form versioning

  • Form authoring

  • Restricting editing on an imported form

  • Saving to or importing from a form repository

Importing a form definition

There are two ways to import a form definition, viz. using the XNAT Form Builder or the Custom Form API.

Import using  XNAT Form Builder

  • Login as a user who can create custom forms
  • Create a form with just one component, say a Text Field and save the form
  • Go back to edit the newly created form and click on Edit JSON
  • Copy the JSON of the form you want to import into the form JSON editor and click save. 
  • Note:
    • Copying the JSON as is, will also set the form title to be the same as the one at the source. 

 Import using Custom Form API

While importing a form definition using the API, you will have to make sure that:

  • the datatype that the form applies to, is configured on your XNAT instance
  • the form schema JSON is a valid form definition. XNAT will not validate the JSON against the form schema rules
  • if the form you are importing is a project specific form, the project id(s) exist on your XNAT instance.

Using the API to import a form definition involves providing the meta-data about the form, that is, 

  • the display order of the form
  • whether the form is applicable across the site or applies to specific projects
  • if the form is a specific to a project(s), what are the project ids

A PUT to the endpoint xapi/customforms/save will save the form definition. A response of 201 implies that the form has been saved successfully and the API returns the form UUID assigned to the form.

Curl call to save a form

curl -u XNAT_USER_NAME:PASSWORD -X PUT "YOUR_XNAT_URL_HERE/xapi/customforms/save" -H "Content-Type: application/json;charset=UTF-8" -d FORM_JSON_WITH_METADATA_HERE

The following json with form metadata, is a form that applies to the Subject datatype (lines 6-9), is not a site wide  form (line 10) and applies to the project proj2 (lines 11-16).  Line 19 onwards is the form schema.

Sample Custom Form Definition with form meta-data

  "submission": {
    "data": {
      "zIndex": 10,
      "xnatDatatype": {
        "label": "Subject",
        "value": "xnat:subjectData"
      "isThisASiteWideConfiguration": "no",
      "xnatProject": [
          "label": "proj2",
          "value": "proj2"
  "builder": {
    "display": "form",
    "title": "Imported Form",
    "settings": {},
    "components": [
        "label": "Text Field 01",
        "key": "textField01",
        "type": "textfield",
        "input": true,
        "tableView": true

A curl call to save the above json would look like:

Curl call to save the sample form definition

curl -u XNAT_USER_NAME:PASSWORD -X PUT "YOUR_XNAT_URL_HERE/xapi/customforms/save" -H "Content-Type: application/json;charset=UTF-8" -d "{\"submission\":{\"data\":{\"zIndex\":10,\"xnatDatatype\":{\"label\":\"Subject\",\"value\":\"xnat:subjectData\"},\"isThisASiteWideConfiguration\":\"no\",\"xnatProject\":[{\"label\":\"proj2\",\"value\":\"proj2\"}]}},\"builder\":{\"display\":\"form\",\"title\":\"Imported Form\",\"settings\":{},\"components\":[{\"label\":\"Text Field 01\",\"key\":\"textField01\",\"type\":\"textfield\",\"input\":true,\"tableView\":true}]}}"

Exporting a form definition

Like importing a form definition, exporting a form definition can be done using the XNAT Form Builder  or the Custom Form API. However, using the Custom Form API is a more involved process and we would not recommend to the use the API to export the form.

Export using the XNAT Form Builder

  • Login as a user who can create forms
  • From the form dashboard, click on the form you want to export
  • Click on Edit JSON and copy the form schema JSON
  • Save the copied JSON in a file. 
  • You can share this file with others to import the form into their XNAT instance.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.