--- title: "JSON schema for PDF form fields" canonical_url: "https://www.nutrient.io/guides/ios/json/schema/form-fields/" md_url: "https://www.nutrient.io/guides/ios/json/schema/form-fields.md" last_updated: "2026-05-14T16:53:43.872Z" description: "Learn to sync and manage PDF form fields with Instant JSON. Explore field types, event triggers, and schema for efficient form development." --- # Effective guidelines for PDF form field types ## Types This section explains how to use type declarations in Instant JSON records. The optional keys are specified as follows: ```js { optionalKey?: value; } ``` To reduce payload size, omit optional keys when their values are undefined. ## Form fields Form field types allow you to sync form fields across different devices. ### Common types There are some data types used by different form field types: ### JSON ```json // Examples of common types of Instant JSON payloads. // Additional action types. formFieldEventTriggerType = "onChange" // Additional action types for input events. // K — Action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box. formFieldInputEventTriggerType = "onInput" // Form field flags. formFieldFlags = ["readOnly", "required"] // Form option. formOption = { "label": "name", "value": "John Appleseed" }; ``` ### JAVASCRIPT ```js // Additional action types. declare type FormFieldEventTriggerType = // V — When the field's value is changed. This action can check the new value for validity. | 'onChange' // C — Action to be performed to recalculate the value of a field. | 'onCalculate'; // Additional actions type for input events. declare type FormFieldInputEventTriggerType = // K — Action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box. | 'onInput' // F — Action to be performed before the field is formatted to display its current value. | 'onFormat'; declare type FormFieldFlags = Array< 'readOnly' | 'required' | 'noExport', >; declare type FormOption = { label: string, value: string, }; ``` ### Base form field shared properties Some properties are common to all form fields and shared among all form field Instant types. The following example shows a payload of this abstract type: ### JSON ```json // Example of a base form field Instant JSON schema: { "type": "pspdfkit/form-field/text", "pdfObjectId": 100, "annotationIds": ["100"], "name": "Email", "label": "Email", // Used to identify the field in the UI or for accessibility. "flags": ["required"] } ``` ### JAVASCRIPT ```js declare type BaseFormField = { type: | 'pspdfkit/form-field/button' | 'pspdfkit/form-field/checkbox' | 'pspdfkit/form-field/combobox' | 'pspdfkit/form-field/listbox' | 'pspdfkit/form-field/radio' | 'pspdfkit/form-field/text' | 'pspdfkit/form-field/signature', pdfObjectId: number, annotationIds: Array, // List of annotation IDs. name: string, // Unique identifiable name (fully qualified name). label: string, // Used to identify the field in the UI or for accessibility. flags?: FormFieldFlags, }; ``` ### Choice form field Here’s an abstract type encompassing list box and combo box form fields: ### JSON ```json // Example of the Instant JSON schema of a choice form field: { "type": "pspdfkit/form-field/listbox", "pdfObjectId": 100, "annotationIds": ["101", "102"], "name": "Subscribe", "label": "Subscribe", "options": [ { "label": "Yes", "value": "Yes" }, { "label": "No", "value": "No" } ], "multiSelect": false, "commitOnChange": false, "defaultValues": ["No"] } ``` ### JAVASCRIPT ```js declare type ChoiceField = BaseFormField & { type: 'pspdfkit/form-field/listbox' | 'pspdfkit/form-field/combobox', options: Array, multiSelect: boolean, commitOnChange: boolean, defaultValues: Array, additionalActions?: { [FormFieldEventTriggerType]: Action }, }; ``` ### List box form field ### JSON ```json // Example of the Instant JSON schema of a list box form field: { "type": "pspdfkit/form-field/listbox", "pdfObjectId": 100, "annotationIds": ["101", "102"], "name": "Subscribe", "label": "Subscribe", "options": [ { "label": "Yes", "value": "Yes" }, { "label": "No", "value": "No" } ], "multiSelect": false, "commitOnChange": false, "defaultValues": ["No"], "additionalActions": { "onInput": { "type": "goTo", "pageIndex": 3 } } } ``` ### JAVASCRIPT ```js declare type ListBoxFormField = ChoiceField & { type: 'pspdfkit/form-field/listbox', additionalActions?: { [ | FormFieldEventTriggerType | FormFieldInputEventTriggerType]: Action, }, }; ``` ### Combo box form field ### JSON ```json // Example of the Instant JSON schema of a combo box form field: { "type": "pspdfkit/form-field/combobox", "pdfObjectId": 100, "annotationIds": ["101", "102"], "name": "Subscribe", "label": "Subscribe", "options": [ { "label": "Yes", "value": "Yes" }, { "label": "No", "value": "No" } ], "multiSelect": false, "commitOnChange": false, "defaultValues": ["No"], "edit": false, "doNotSpellCheck": false } ``` ### JAVASCRIPT ```js declare type ComboBoxFormField = ChoiceField & { type: 'pspdfkit/form-field/combobox', edit: boolean, doNotSpellCheck: boolean, }; ``` ### Checkbox form field ### JSON ```json // Example of the Instant JSON schema of a checkbox form field: { "pdfObjectId": 100, "annotationIds": ["100"], "name": "Accept", "label": "Accept", "flags": ["required"], "options": [ { "label": "Yes", "value": "Yes" }, { "label": "No", "value": "No" } ], "defaultValues": ["No"] } ``` ### JAVASCRIPT ```js declare type CheckBoxFormField = BaseFormField & { type: 'pspdfkit/form-field/checkbox', options: Array, defaultValues: Array, additionalActions?: { [FormFieldEventTriggerType]: Action }, }; ``` ### Radio button form field ### JSON ```json // Example of the Instant JSON schema of a radio button form field: { "type": "pspdfkit/form-field/radio", "pdfObjectId": 100, "annotationIds": ["101", "102"], "name": "Color", "label": "Color", "options": [ { "label": "Blue", "value": "Blue" }, { "label": "Red", "value": "Red" } ], "noToggleToOff": true, "radiosInUnison": false, // Not supported in Web. "defaultValue": "Blue" } ``` ### JAVASCRIPT ```js declare type RadioButtonFormField = BaseFormField & { type: 'pspdfkit/form-field/radio', options: Array, noToggleToOff: boolean, radiosInUnison: boolean, // Not supported in Web. defaultValue: string, }; ``` ### Text form field ### JSON ```json // Example of the Instant JSON schema of a text form field: { "type": "pspdfkit/form-field/text", "pdfObjectId": 100, "annotationIds": ["100"], "name": "Name", "label": "Name", // Used to identify the field in the UI or for accessibility. "password": false, "maxLength": 100, "doNotSpellcheck": true, "doNotScroll": false, "multiLine": false, "comb": false, "defaultValue": "" } ``` ### JAVASCRIPT ```js declare type TextFormField = BaseFormField & { type: 'pspdfkit/form-field/text', password: boolean, maxLength?: number, doNotSpellcheck: boolean, doNotScroll: boolean, multiLine: boolean, comb: boolean, defaultValue: string, additionalActions?: { [ | FormFieldEventTriggerType | FormFieldInputEventTriggerType]: Action, }, }; ``` ### Signature form field ### JSON ```json // Example of the Instant JSON schema of a signature form field: { "type": "pspdfkit/form-field/signature", "pdfObjectId": 100, "annotationIds": ["100"], "name": "Your signature", "label": "Your signature" } ``` ### JAVASCRIPT ```js declare type SignatureFormField = BaseFormField & { type: 'pspdfkit/form-field/signature', }; ``` ### Button form field ### JSON ```json // Example of the Instant JSON schema of a button form field: { "type": "pspdfkit/form-field/button", "pdfObjectId": 100, "annotationIds": ["100"], "name": "A button", "label": "A button" } ``` ### JAVASCRIPT ```js declare type ButtonFormField = BaseFormField & { type: 'pspdfkit/form-field/button', }; ``` --- ## Related pages - [Create and manage PDF bookmarks with Instant JSON](/guides/ios/json/schema/bookmarks.md) - [Instant JSON format for PDF annotations explained](/guides/ios/json/schema/annotations.md) - [Streamline document discussions with Instant Comments](/guides/ios/json/schema/comments.md) - [Sync PDF form field values using Instant JSON](/guides/ios/json/schema/form-field-values.md) - [Understanding Instant JSON attachments and schemas](/guides/ios/json/schema/file-attachments.md) - [Understanding Instant JSON action types](/guides/ios/json/schema/actions.md)