Guide to Form Data Format (FDF) and XML Form Data Format (XFDF)

Form Data Format (FDF)

Overview of FDF

FDF is a compact text file format used to import and export form data to and from PDF documents. It supports not just form fields, but also annotations and other types of actions, such as commands for submitting data back to a server. One of the primary advantages of FDF is that it only includes data, which makes these files much lighter than full PDF files.

Usage of FDF

FDF files are primarily used for scenarios where form data needs to be captured and reused, such as saving form inputs for archival, transferring data between different systems, or pre-populating forms on behalf of users. FDF helps streamline workflows by separating data from layout, allowing non-technical users to focus on content rather than formatting.

Structure and Components of an FDF File

An FDF file typically consists of three main components:

• Header: Specifies the version of FDF being used, important for ensuring compatibility.
• Body: Contains the actual data of the form. It lists form fields with their respective values and can also contain information about the PDF document that the form data is intended for.
• Footer: Concludes the file with a reference to the root object and an EOF marker, signaling the end of the file.

Example FDF File

%FDF-1.2
%âãÏÓ
1 0 obj
<<
/FDF <<
/Fields [
<< /T (name) /V (John Doe) >>
<< /T (age) /V (30) >>
]
>>
>>
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

Creating an FDF File

An FDF file is a plain text file that contains a list of form fields and their values. Although we’ll show you how to create one by hand, most often FDF files are software generated.

• Start with the Header: Include the version of the FDF specification. For example, '%FDF-1.2' is a common header.
• Define the Body: Use the '/FDF' dictionary to enclose form fields under '/Fields'. Each form field is represented as a dictionary containing '/T' (the field name) and '/V' (the field value).
• Close with the Footer: End the FDF file with a trailer that references the root object and an end-of-file marker '%%EOF'.

These are some of the more common methods to create FDF files:

• Use Adobe Acrobat to export forms data directly to a file.
• Use a Submit Form action in Acrobat’s Field Properties pop-up to export FDF data to a web server.
• Export data from a database and save it as an FDF file, using a script that you create.
• Write a program that will build an FDF file as a plain text file, using a script that you create.
• Use Adobe’s FDF Toolkit, see FDF resources for more information.

The FDF file format

An FDF file has the following format:

• An FDF file must begin with (Percent)FDF and end with (PercentPercent)EOF
  %EOF
• The data is given as name-value pairs, enclosed in double angle brackets: << >>:
  /T indicates form field name
  /V indicates form field value

In this section we’ll use the sample file: samples/testfiles/testfile.fdf as an example. Within it are six name-value pairs. The lines before and after these pairs are identification and formatting information.

%FDF-1.2
%âãÏÓ
1 0 obj
<<
/FDF << /Fields [
<< /T (CheckBox1) /V /Yes>>
<< /T (CheckBox2) /V /Off>>
<< /T (ComboBox) /V (6)>>
<< /T (ListBox) /V (fontsize)>>
<< /T (Basefont) 
/V (This is a Multi-line text box. Note that the text wraps around to the next line!)>>
] >> 
/ID[<B5B9EA85E3E2A7372D233185314E367E><7CA8657022DA815A340A57D516E030DC>
] >> 
>> 
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

Line breaks and new lines in FDF files

When long character strings are used in text fields, you may need to manually insert line breaks, so that the text wraps in the form field the way you would like it to. If you put a line break in a field value, you need to adjust the spaces between words.

Inserting line breaks in FDF files, \r and \n

In order to make a multi-line text field format the way you want it to, you may have to add newline characters, using \r or \n. They both work the same way. A single new line results from any of the following: \r, \n, or \r\n. For example, if your text is:

Among these are time management

and you would like it to look like:

Among these are
time management

enter this into the FDF value for the form field:

Among these are\rtime management

Using the line continuation character \

The value of a name-value pair should be on a single line. If you need to break a value onto the next line, use the \ line continuation character.

Entering the following into the FDF value for the form field:

Among these \
are time man\
agement

Will look like this in the output PDF:

Among these are time management

Using special characters

Special characters can be entered directly into the FDF file, or they can be represented by octal characters. An octal character is represented by a \ followed by a three digit octal code. FDFMerge Lite and FDFMerge use octal codes with PDF encoding. A list of octal codes can be found in Appendix D of the PDF Reference manual on Adobe’s website.

Entering the following into the FDF value for the form field:

\200 Among these are time management

Will look like:

• Among these are time management

FDF resources

For more information about FDF, refer to Adobe for the following resources:

• The FDF Toolkit. Adobe provides this free API (Application Program Interface) for writing a server application that generates FDF data, or to parse FDF data from a form.
• The PDF Reference Manual provides useful FDF documentation.
• Be sure to check the FDFMerge Lite or FDFMerge pages of the Appligent website.

XML Form Data Format (XFDF)

Overview of XFDF

XFDF is the XML counterpart to FDF and serves similar purposes but in a format that adheres to XML standards. XFDF is more versatile for web integration and can be used seamlessly with a variety of internet applications and services. It is particularly valuable in environments where form data needs to be integrated with other XML-based systems.

Structure and Components of an XFDF File

The structure of an XFDF file mirrors that of a typical XML document and includes:

• XML Declaration: Defines the XML version and character encoding used in the file.
• Root Element: Encapsulates all the data within the XFDF file.
• Field Elements: Each form field is represented by a field element, which has attributes and child elements specifying the field name and value.
• Annotations: XFDF can also store information about annotations, which can be necessary for reviewing or auditing forms.

Usage of XFDF

XFDF's alignment with XML standards makes it extremely useful for scenarios involving complex system integrations or when data needs to be processed alongside other XML data streams. It's also preferred when data needs to be viewed or manipulated in web browsers or other XML-capable environments.

Creating an XFDF File

XFDF is an XML version of an FDF file. You can create XFDF files the following ways:

• Use Adobe Acrobat to export forms data directly to a file.
• Export data from a database and save it as an XFDF file, via a script that you create.
• Write a program that will build an XFDF file as a plain text file, via a script that you create.
• Use the Submit Form action in Acrobat’s Field Properties pop-up to export XFDF data to a web server.

You cannot use the FDF Toolkit to create XFDF files.

XML is a structured language that begins with the XML file itself as the topmost object. XFDF files have an element called fields that contain field and value.

Basic XFDF file structure

The table below shows the basic XFDF file structure.

Element	Attribute	Content
<XFDF>		Topmost element
<fields>		All the field values for this template
<field (T)>	name	Field name
<value (V)>	value	Field value

 

Refer to the XML Forms Data Format Specification on the Adobe website for more information about XFDF files. You can go to https://www.immagic.com/eLibrary/ARCHIVES/TECH/ADOBE/A070914X.pdf to download the specification.

An example of an XFDF file which shows this simple structure follows. The sample FDF form data would look like this in XFDF:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
   <fields>
      <field name="CheckBox1">
      <value>A</value>
      </field>
      <field name="CheckBox2">
      <value>Off</value>
      </field>
      <field name="CheckBox3">
      <value>Off</value>
      </field>
      <field name="ComboBox1">
      <value>Option 1</value>
      </field>
      <field name="ListBox1">
      <value>Item2</value>
      </field>
      <field name="MultiLineText1">
      <value>This is a Multi-line text box. Note that the text wraps around to the next line!</value>
      </field>
      <field name="RadioGroup1">
      <value>Yes</value>
      </field>
      <field name="TextBox1">
      <value>Sample Text</value>
      </field>
   </fields>
</xfdf>

Line breaks and new lines in XFDF files

To manually insert a line break in form field text, type a carriage return directly into the value in the XFDF file. You do not need to use /r or /n characters. Make sure to check Multi-line on the Options tab of the Text Field Properties dialog in Acrobat.

Using Unicode

FDFMerge Lite and FDFMerge can use Unicode to place Asian language characters in a text form field. The only place double-byte characters can be used is in the value parameter of a text form field.