Form Template JSON Structure

When you request form templates from the Oplix API, you’ll get back a JSON object containing all the forms associated with your application. Let’s walk through exactly what that structure looks like and how to work with it.

Understanding the Response

The API returns a top-level object with a templates array. Each template in this array represents a different form you’ve created in the Oplix dashboard - maybe one for bug reports, another for feature requests, and so on.

✨ Multiple Templates

If you get multiple templates back, you’ll want to present your players with a way to choose which type of feedback they’re submitting. A dropdown menu using the formDescription as the label works great for this.

Basic Structure

Here’s what the overall JSON looks like:

{
  "templates": [
    {
      "formDescription": "General Bug Report",
      "templateType": "Bug Report",
      "rows": [
        // Your form fields go here
      ]
    },
    {
      "formDescription": "Performance Issue Report",
      "templateType": "Bug Report",
      "rows": [
        // Different form fields here
      ]
    }
  ]
}

Complete Example

Let’s look at a real-world example with actual form fields. This shows a bug report form with different question types:

{
  "templates": [
    {
      "formDescription": "General Bug Report",
      "templateType": "Bug Report",
      "rows": [
        {
          "id": 1725461889949,
          "columns": [
            {
              "id": 1725461889949,
              "width": 50,
              "exclude": false,
              "question": "Tell us about your issue",
              "required": false,
              "inputType": "text"
            },
            {
              "id": 1725461898332,
              "width": 50,
              "exclude": false,
              "question": "Where is this happening",
              "required": false,
              "inputType": "dropdown",
              "options": {
                "type": "dropdown",
                "options": [
                  { "label": "Main Menu", "value": "Main Menu" },
                  { "label": "In Game", "value": "In Game" }
                ]
              }
            }
          ]
        },
        {
          "id": 1725461917836,
          "columns": [
            {
              "id": 1725461917836,
              "width": 100,
              "exclude": false,
              "question": "How does it impact your game out of 10?",
              "inputType": "rating",
              "ratingScale": {
                "max": 10,
                "type": "numeric",
                "labels": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]
              }
            }
          ]
        },
        {
          "id": 1725461943474,
          "columns": [
            {
              "id": 1725461943474,
              "width": 33,
              "exclude": false,
              "question": "Have you searched our help forums?",
              "inputType": "switch",
              "labels": {
                "type": "toggle",
                "options": {
                  "on": "Yes",
                  "off": "No"
                }
              }
            },
            {
              "id": 1725462018905,
              "width": 67,
              "exclude": false,
              "question": "Explain the steps to reproduce",
              "required": false,
              "inputType": "paragraph"
            }
          ]
        },
        {
          "id": 1725462036166,
          "columns": [
            {
              "id": 1725462036166,
              "width": 100,
              "exclude": true,
              "question": "Your email address",
              "required": false,
              "inputType": "text"
            }
          ]
        }
      ]
    }
  ]
}

Breaking Down the Structure

Templates Array

The templates array is your top-level container. Each object inside represents a complete form with all its questions and settings.

Form Properties

Each template has a few key properties:

formDescription - This is the human-readable name you’ll show to players when they’re choosing what type of feedback to submit. Something like “Bug Report” or “Network Issue”.

templateType - This tells Oplix how to process the form. You’ll see values like Bug Report or Player Feedback. This is set in the Oplix dashboard and the engine needs it to handle submissions correctly.

rows - This array contains the actual form layout. Think of rows as horizontal sections of your form.

Rows and Columns

Forms are built using a row and column system, kind of like a grid layout. Each row contains one or more columns, and each column is a form field.

Here’s a single row with two columns side by side:

{
  "id": 1725461889949,
  "columns": [
    {
      "id": 1725461889949,
      "width": 50,
      "exclude": false,
      "question": "Tell us about your issue",
      "required": false,
      "inputType": "text"
    },
    {
      "id": 1725461898332,
      "width": 50,
      "exclude": false,
      "question": "Where is this happening",
      "required": false,
      "inputType": "dropdown",
      "options": {
        "type": "dropdown",
        "options": [
          { "label": "Main Menu", "value": "Main Menu" },
          { "label": "In Game", "value": "In Game" }
        ]
      }
    }
  ]
}

Each row has a unique id for tracking purposes, and inside it you’ll find the columns array with your form fields.

Column Properties

Every form field (column) has several properties that control how it works:

Form Field Properties

Field Name	Type	Required	Notes
`id`	number	Required	A unique identifier for this field. You'll use this to keep track of which question is which when processing responses.
`width`	number (0-100)	Required	How much horizontal space this field takes up. A width of 50 means it takes up half the row. Two fields with width 50 will sit side by side, while a field with width 100 spans the full width.
`question`	string	Required	The actual text your players will see. This is the label or prompt for the input field.
`inputType`	string	Required	What kind of input field this is. Supported types: text, paragraph, dropdown, multiselect, rating, switch.
`required`	boolean	Optional	Whether players must fill this out before submitting. If true, they can't skip it.
`exclude`	boolean	Optional	When set to true, the field won't be processed by Oplix's AI engine. Use this for sensitive information like email addresses or personal data. The data still gets stored for your review, it just won't be included in automatic analysis.

Field Types

Let’s go through each type of form field you might encounter and how to render them.

Text Input

The simplest field type - just a single-line text box where users can type a short response.

{
  "id": 1725461889949,
  "width": 50,
  "exclude": false,
  "question": "Tell us about your issue",
  "required": false,
  "inputType": "text"
}

Render this as a standard text input field with the question as the label.

Paragraph Input

Similar to text, but for longer responses. This should be a multi-line text area.

{
  "id": 1725462018905,
  "width": 67,
  "exclude": false,
  "question": "Explain the steps to reproduce",
  "required": false,
  "inputType": "paragraph"
}

Think of this as a textarea element - give users plenty of room to write detailed descriptions.

A dropdown menu where users select one option from a list. The options object contains an array of choices.

{
  "id": 1725461898332,
  "width": 50,
  "exclude": false,
  "question": "Where is this happening",
  "required": false,
  "inputType": "dropdown",
  "options": {
    "type": "dropdown",
    "options": [
      { "label": "Main Menu", "value": "Main Menu" },
      { "label": "In Game", "value": "In Game" }
    ]
  }
}

Each option has a label (what the user sees) and a value (what gets submitted). In most cases these are the same, but you can use them differently if needed.

Multiselect

Similar to dropdown, but users can choose multiple options. You’ll want to render this as a multi-select component or a list of checkboxes.

{
  "id": 1725462036166,
  "width": 100,
  "exclude": false,
  "question": "Which platforms are affected?",
  "inputType": "multiselect",
  "options": {
    "type": "multiselect",
    "options": [
      { "label": "Windows", "value": "Windows" },
      { "label": "Mac", "value": "Mac" },
      { "label": "Linux", "value": "Linux" }
    ]
  }
}

When submitting, send back an array of all selected values.

Rating

A rating scale where users pick a number to indicate severity, satisfaction, or impact. The ratingScale object defines how many options there are and what they look like.

{
  "id": 1725461917836,
  "width": 100,
  "exclude": false,
  "question": "How does it impact your game out of 10?",
  "inputType": "rating",
  "ratingScale": {
    "max": 10,
    "type": "numeric",
    "labels": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]
  }
}

The max value tells you how many options there are, type indicates if it’s numeric or custom labels, and labels provides the text for each option. Render this as a horizontal row of selectable buttons or a slider.

Switch (Toggle)

A simple on/off toggle, typically used for yes/no questions. The labels object defines what text appears for each state.

{
  "id": 1725461943474,
  "width": 33,
  "exclude": false,
  "question": "Have you searched our help forums?",
  "inputType": "switch",
  "labels": {
    "type": "toggle",
    "options": {
      "on": "Yes",
      "off": "No"
    }
  }
}

Render this as a toggle switch or radio buttons with the provided labels. When submitting, send back either the on or off value depending on what the user selected.

Important: The Exclude Flag

Pay special attention to the exclude property. This flag determines whether the Oplix AI engine processes a field’s data.

When exclude is false, the field gets included in AI analysis, duplicate detection, and automatic categorization. This is what you want for most questions.

⚠️ Understanding the Exclude Flag

When exclude is true, the field data is stored but skipped during AI processing. Use this for:

Email addresses
Player names or usernames
Any personal or sensitive information
System information you need to store but don’t want analyzed

You still need to render and submit this field normally - the exclusion only affects backend processing.

Here’s an example of an excluded field:

{
  "id": 1725462036166,
  "width": 100,
  "exclude": true,
  "question": "Your email address",
  "required": false,
  "inputType": "text"
}

Rendering Your Form

When you’re building the form UI in your game or app, here’s the general approach:

First, if you have multiple templates, show a selection menu using each template’s formDescription. Once the user picks one, render that template’s form.

Loop through the rows array. For each row, create a horizontal container.

Inside each row, loop through the columns array. Use the width property to set how much space each column takes. Render the appropriate input type based on inputType.

Display the question as the field label, and if required is true, add a visual indicator like an asterisk or “required” badge.

Validate that all required fields are filled before allowing submission.

Submitting Form Data

When the user submits the form, you’ll send all the field data back to the Oplix API’s submit endpoint.

💡 What to Include in Your Submission

Make sure to include:

All fields, even those marked with exclude: true
The field IDs so Oplix knows which answer goes with which question
The template type so Oplix can route it correctly

The submit endpoint expects the data in a specific format - check the Submit Form API documentation for the exact structure.

Handling Multiple Templates

If you receive multiple templates in the templates array, your UI flow should look something like this:

First, show a category selection screen with buttons or a dropdown. Use the formDescription as the label for each option - “Bug Report”, “Feature Request”, “Performance Issue”, etc.

Once they select a category, load that template’s rows and columns and render the full form.

After submission, you might want to give users the option to submit another report, which would take them back to the category selection.

Here’s a simple example of handling multiple templates:

{
  "templates": [
    {
      "formDescription": "General Bug Report",
      "templateType": "Bug Report",
      "rows": [/* ... */]
    },
    {
      "formDescription": "Performance Issue",
      "templateType": "Bug Report", 
      "rows": [/* ... */]
    },
    {
      "formDescription": "Feature Request",
      "templateType": "Player Feedback",
      "rows": [/* ... */]
    }
  ]
}

Notice how the first two have the same templateType but different descriptions - they’re both bug reports but with different questions tailored to the type of issue.

Layout Tips

The width property gives you a lot of flexibility in how forms look. Here are some common patterns:

Full-width fields (width: 100) work well for text paragraphs and long questions.

Half-width fields (width: 50) are great for putting two related questions side by side, like “First Name” and “Last Name”.

One-third width (width: 33) lets you fit three small fields in a row, useful for things like “Yes/No/Maybe” toggles.

The width values in each row should ideally add up to 100, though you can go under if you want spacing. Going over 100 will cause fields to wrap to the next line, which might not look great depending on your UI framework.

What’s Next?

Now that you understand the form JSON structure, you’re ready to build your form UI. Check out the Submit Form API documentation to see how to send the completed form data back to Oplix.

If you’re working with Unreal Engine or Unity, we have dedicated integration guides that show you how to implement form rendering using native UI components.

Got questions about a specific field type or need help parsing the JSON? Reach out to support through the help menu in your Oplix dashboard.

Form Template JSON Structure

Understanding the Response

Basic Structure

Complete Example

Breaking Down the Structure

Templates Array

Form Properties

Rows and Columns

Column Properties

Form Field Properties

Field Types

Text Input

Paragraph Input

Dropdown

Multiselect

Rating

Switch (Toggle)

Important: The Exclude Flag

Rendering Your Form

Submitting Form Data

Handling Multiple Templates

Layout Tips

What’s Next?