Forms Data Structure

State: Forms v3.3.1 - 08.10.2023

This document describes the Object-Structure, that is used within the Forms App and on Forms API v3. It does partially not equal the actual database structure behind.

Data Structures

Form

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the form
hash	16-char String	unique	An instance-wide unique hash
title	String	max. 256 ch.	The form title
description	String	max. 8192 ch.	The Form description
ownerId	String		The nextcloud userId of the form owner
submissionMessage	String	max. 2048 ch.	Optional custom message, with Markdown support, to be shown to users when the form is submitted (default is used if set to null)
created	unix timestamp		When the form has been created
access	Access-Object		Describing access-settings of the form
expires	unix-timestamp		When the form should expire. Timestamp `0` indicates never
isAnonymous	Boolean		If Answers will be stored anonymously
state	Integer	Form state	The state of the form
lockedBy	String		The user ID for who has exclusive edit access at the moment
lockedUntil	unix timestamp		When the form lock will expire
submitMultiple	Boolean		If users are allowed to submit multiple times to the form
allowEditSubmissions	Boolean		If users are allowed to edit or delete their response
showExpiration	Boolean		If the expiration date will be shown on the form
canSubmit	Boolean		If the user can Submit to the form, i.e. calculated information out of `submitMultiple` and existing submissions.
permissions	Array of Permissions	Array of permissions regarding the form
questions	Array of Questions		Array of questions belonging to the form
shares	Array of Shares		Array of shares of the form
submissions	Array of Submissions		Array of submissions belonging to the form
submissionCount	Integer		Number of submissions to the form
submissionMessage	String		Message to show after a submission

{
  "id": 3,
  "hash": "em4djk8B9BpXnkYG",
  "title": "Form 1",
  "description": "Description Text",
  "ownerId": "jonas",
  "created": 1611240961,
  "access": {},
  "expires": 0,
  "isAnonymous": false,
  "submitMultiple": true,
  "allowEditSubmissions": false,
  "showExpiration": false,
  "canSubmit": true,
  "permissions": [
    "edit",
    "results",
    "submit"
  ],
  "questions": [],
  "state": 0,
  "lockedBy": null,
  "lockedUntil": null,
  "shares": []
  "submissions": [],
  "submissionCount": 0,
  "submissionMessage": "string"
}

Form state

The form state is used for additional states, currently following states are defined:

Value	Meaning
0	Form is active and open for new submissions
1	Form is closed and does not allow new submissions
2	Form is archived, it does not allow new submissions and can also not be modified anymore

Question

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the question
formId	Integer		The id of the form, the question belongs to
order	Integer	unique within form; not `0`	The order of the question within that form. Value `0` indicates deleted questions within database (typ. not visible outside)
type	Question-Type		Type of the question
isRequired	Boolean		If the question is required to fill the form
text	String	max. 2048 ch.	The question-text
name	String		Technical identifier of the question, e.g. used as HTML name attribute
options	Array of Options		Array of options belonging to the question. Only relevant for question-type with predefined options.
extraSettings	Extra Settings		Additional settings for the question.

{
  "id": 1,
  "formId": 3,
  "order": 1,
  "type": "dropdown",
  "isRequired": false,
  "text": "Question 1",
  "name": "firstname",
  "options": [],
  "extraSettings": {}
}

Option

Options are predefined answer-possibilities corresponding to questions with appropriate question-type.

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the option
questionId	Integer		The id of the question, the option belongs to
order	Integer		The order of the option
text	String	max. 1024 ch.	The option-text

{
  "id": 1,
  "questionId": 1,
  "order": 1,
  "text": "Option 1"
}

A share-object describes a single share of the form.

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the share
formId	Integer		The id of the form, the share belongs to
shareType	NC-IShareType (Int)	`IShare::TYPE_USER = 0`, `IShare::TYPE_GROUP = 1`, `IShare::TYPE_LINK = 3`	Type of the share. Thus also describes how to interpret shareWith.
shareWith	String		User/Group/Hash - depending on the shareType
displayName	String		Display name of share-target.

Submission

A submission-object describes a single submission by a user to a form.

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the submission
formId	Integer		The id of the form, the submission belongs to
userId	String		The nextcloud userId of the submitting user. If submission is anonymous, this contains `anon-user-<hash>`
timestamp	unix timestamp		When the user submitted
answers	Array of Answers		Array of the actual user answers, belonging to this submission.
userDisplayName	String		Display name of the nextcloud-user, derived from `userId`. Contains `Anonymous user` if submitted anonymously. Not stored in DB.

{
  "id": 5,
  "formId": 3,
  "userId": "jonas",
  "timestamp": 1611274433,
  "answers": [],
  "userDisplayName": "jonas"
}

Answer

The actual answers of users on submission.

Property	Type	Restrictions	Description
id	Integer	unique	An instance-wide unique id of the submission
submissionId	Integer		The id of the submission, the answer belongs to
questionId	Integer		The id of the question, the answer belongs to
questionName	String		The technical name that was assigned to the question
text	String	max. 4096 ch.	The actual answer text, the user submitted

{
	"id": 5,
	"submissionId": 5,
	"questionId": 1,
	"questionName": "preference",
	"text": "Option 2"
}

Permissions

Array of permissions, the user has on the form. Permissions are named by resp. routes on frontend.

Permission	Description
edit	User is allowed to edit the form
results	User is allowed to access the form results
results_delete	User is allowed to delete form submissions
submit	User is allowed to submit to the form
embed	only for `shareType: IShare::TYPE_LINK = 3` (link shares): allow embedding

Access Object

Defines some extended options of sharing / access

Property	Type	Description
permitAllUsers	Boolean	All logged in users of this instance are allowed to submit to the form
showToAllUsers	Boolean	Only active, if permitAllUsers is true - Show the form to all users on appNavigation

{
  "permitAllUsers": false,
  "showToAllUsers": false
}

Question Types

Currently supported Question-Types are:

Type-ID	Description
`multiple`	Typically known as 'Checkboxes'. Using pre-defined options, the user can select one or multiple from. Needs at least one option available.
`multiple_unique`	Typically known as 'Radio Buttons'. Using pre-defined options, the user can select exactly one from. Needs at least one option available.
`dropdown`	Similar to `multiple_unique`, but rendered as dropdown field.
`short`	A short text answer. Single text line
`long`	A long text answer. Multi-line supported
`date`	Showing a dropdown calendar to select a date.
`datetime`	deprecated: No longer available for new questions. Showing a dropdown calendar to select a date and* a time.*
`time`	Showing a dropdown menu to select a time.
`file`	One or multiple files. It is possible to specify which mime types are allowed
`linearscale`	A linear or Likert scale question where you choose an option that best fits your opinion
`color`	A color answer, hex string representation (e. g. `#123456`)
`conditional`	A conditional branching question with a trigger question and multiple branches containing subquestions

Extra Settings

Optional extra settings for some Question Types

Extra Setting	Question Type	Type	Values	Description
`allowOtherAnswer`	`multiple, multiple_unique`	Boolean	`true/false`	Allows the user to specify a custom answer
`shuffleOptions`	`dropdown, multiple, multiple_unique`	Boolean	`true/false`	The list of options should be shuffled
`optionsLimitMax`	`multiple`	Integer	-	Maximum number of options that can be selected
`optionsLimitMin`	`multiple`	Integer	-	Minimum number of options that must be selected
`validationType`	`short`	string	`null, 'phone', 'email', 'regex', 'number'`	Custom validation for checking a submission
`validationRegex`	`short`	string	regular expression	if `validationType` is 'regex' this defines the regular expression to apply
`allowedFileTypes`	`file`	Array of strings	`'image', 'x-office/document'`	Allowed file types for file upload
`allowedFileExtensions`	`file`	Array of strings	`'jpg', 'png'`	Allowed file extensions for file upload
`maxAllowedFilesCount`	`file`	Integer	-	Maximum number of files that can be uploaded, 0 means no limit
`maxFileSize`	`file`	Integer	-	Maximum file size in bytes, 0 means no limit
`dateMax`	`date`	Integer	-	Maximum allowed date to be chosen (as Unix timestamp)
`dateMin`	`date`	Integer	-	Minimum allowed date to be chosen (as Unix timestamp)
`dateRange`	`date`	Boolean	`true/false`	The date picker should query a date range
`timeMax`	`time`	string	-	Maximum allowed time to be chosen (as `HH:mm` string)
`timeMin`	`time`	string	-	Minimum allowed time to be chosen (as `HH:mm` string)
`timeRange`	`time`	Boolean	`true/false`	The time picker should query a time range
`optionsLowest`	`linearscale`	Integer	`0, 1`	Set the lowest value of the scale, default: `1`
`optionsHighest`	`linearscale`	Integer	`2, 3, 4, 5, 6, 7, 8, 9, 10`	Set the highest value of the scale, default: `5`
`optionsLabelLowest`	`linearscale`	string	-	Set the label of the lowest value, default: `'Strongly disagree'`
`optionsLabelHighest`	`linearscale`	string	-	Set the label of the highest value, default: `'Strongly agree'`
`triggerType`	`conditional`	string	See trigger types	The type of trigger question (dropdown, multiple_unique, etc.)
`branches`	`conditional`	Array	Array of Branch objects	The branches with conditions and subquestions

Conditional Questions

Conditional questions enable branching logic in forms. A trigger question determines which branch of subquestions appears based on the respondent's answer.

Question Properties for Subquestions

Subquestions (questions belonging to a conditional question's branch) have additional properties:

Property	Type	Description
parentQuestionId	Integer	The ID of the parent conditional question (null for regular questions)
branchId	String	The ID of the branch this subquestion belongs to

Conditional Trigger Types

Supported trigger types for conditional questions:

Trigger Type	Condition Type	Description
`multiple_unique`	`option_selected`	Radio buttons - single option selection
`dropdown`	`option_selected`	Dropdown - single option selection
`multiple`	`options_combination`	Checkboxes - all specified options must be selected
`short`	`string_equals`, `string_contains`, `regex`	Short text with string/regex matching
`long`	`string_contains`, `regex`	Long text with string/regex matching
`linearscale`	`value_equals`, `value_range`	Linear scale with value matching
`date`	`date_range`	Date with date range matching (YYYY-MM-DD)
`time`	`time_range`	Time with time range matching (HH:mm)
`color`	`value_equals`	Color with exact value matching
`file`	`file_uploaded`	File with upload status matching

Branch Object

A branch defines conditions and subquestions that appear when those conditions are met.

Property	Type	Description
id	String	Unique identifier for the branch
conditions	Array of Conditions	Conditions that must be met to show the branch
subQuestions	Array of Questions	Questions shown when conditions are met

{
  "id": "branch-1705587600000",
  "conditions": [
    { "type": "option_selected", "optionId": 42 }
  ],
  "subQuestions": [
    {
      "id": 101,
      "formId": 3,
      "order": 1,
      "type": "short",
      "text": "Please provide details",
      "parentQuestionId": 100,
      "branchId": "branch-1705587600000"
    }
  ]
}

Condition Object

Conditions determine when a branch is activated. The structure depends on the trigger type.

option_selected (for dropdown, multiple_unique)

{ "type": "option_selected", "optionId": 42 }

options_combination (for multiple/checkboxes)

{ "type": "options_combination", "optionIds": [42, 43] }

All options in optionIds must be selected for the branch to activate (AND logic).

string_equals (for short text)

{ "type": "string_equals", "value": "yes" }

string_contains (for short, long text)

{ "type": "string_contains", "value": "keyword" }

regex (for short, long text)

{ "type": "regex", "value": "^yes.*" }

value_equals (for color)

{ "type": "value_equals", "value": "#ff0000" }

value_range (for linearscale, time)

{ "type": "value_range", "min": 3, "max": 5 }

date_range (for date)

{ "type": "date_range", "min": "2024-01-01", "max": "2024-12-31" }

time_range (for time)

{ "type": "time_range", "min": "09:00", "max": "17:00" }

file_uploaded (for file)

{ "type": "file_uploaded", "fileUploaded": true }

Conditional Question Example

A complete conditional question structure:

{
  "id": 100,
  "formId": 3,
  "order": 1,
  "type": "conditional",
  "isRequired": true,
  "text": "Do you have any dietary restrictions?",
  "options": [
    { "id": 42, "questionId": 100, "order": 1, "text": "Yes" },
    { "id": 43, "questionId": 100, "order": 2, "text": "No" }
  ],
  "extraSettings": {
    "triggerType": "dropdown",
    "branches": [
      {
        "id": "branch-yes",
        "conditions": [{ "type": "option_selected", "optionId": 42 }],
        "subQuestions": [
          {
            "id": 101,
            "formId": 3,
            "order": 1,
            "type": "long",
            "text": "Please describe your dietary restrictions",
            "parentQuestionId": 100,
            "branchId": "branch-yes"
          }
        ]
      }
    ]
  }
}

Conditional Answer Structure

When submitting or storing conditional question answers, the structure differs from regular questions:

{
  "100": {
    "trigger": ["42"],
    "subQuestions": {
      "101": ["Vegetarian, no nuts"]
    }
  }
}

Property	Type	Description
trigger	Array of strings	Answer values for the trigger question
subQuestions	Object (questionId → Array)	Map of subquestion IDs to their answer value arrays

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Forms Data Structure

Data Structures

Form

Form state

Question

Option

Share

Submission

Answer

Permissions

Access Object

Question Types

Extra Settings

Conditional Questions

Question Properties for Subquestions

Conditional Trigger Types

Branch Object

Condition Object

option_selected (for dropdown, multiple_unique)

options_combination (for multiple/checkboxes)

string_equals (for short text)

string_contains (for short, long text)

regex (for short, long text)

value_equals (for color)

value_range (for linearscale, time)

date_range (for date)

time_range (for time)

file_uploaded (for file)

Conditional Question Example

Conditional Answer Structure

FilesExpand file tree

DataStructure.md

Latest commit

History

DataStructure.md

File metadata and controls

Forms Data Structure

Data Structures

Form

Form state

Question

Option

Share

Submission

Answer

Permissions

Access Object

Question Types

Extra Settings

Conditional Questions

Question Properties for Subquestions

Conditional Trigger Types

Branch Object

Condition Object

option_selected (for dropdown, multiple_unique)

options_combination (for multiple/checkboxes)

string_equals (for short text)

string_contains (for short, long text)

regex (for short, long text)

value_equals (for color)

value_range (for linearscale, time)

date_range (for date)

time_range (for time)

file_uploaded (for file)

Conditional Question Example

Conditional Answer Structure