Form Structured Output
Form structured output returns each form region in a document as a tree you can walk in code. Our form and form-controls models work together to pair every printed label with its answer, find each input, checkbox, and signature line (including fields left blank), and locate every one of them on the page. Turn it on with one option. The markdown content of each block doesn’t change; every key_value block gains a details.form tree alongside it.
Use it when you need label/value pairs, checkbox states, or per-field coordinates, for example to map tax or intake forms into your own data model, feed an LLM typed fields instead of markdown, or draw highlights over individual answers.
Requires parse_performance >= 2.0.0. Structured output applies to regions detected as key_value blocks; a box grid that the layout model detects as a table keeps its values in that table block’s content.
Via the API
Enable structured output
Set config.blockOptions.keyValue.structuredOutputEnabled to true. It works on the synchronous parse call shown here and on async parse runs.
Python
TypeScript
Java
Go
cURL
Read the form tree
Each key_value block carries details.form, a list of nodes in reading order. To turn the tree into flat key-value pairs, walk it and join the labels on the way down: every key adds its content to the path, selection_group and table nodes pass through, and every other node is an answer for the current path.
Python
TypeScript
Java
Go
For the patient intake form below, this prints:
Via Extend Studio
In the Parse playground, open the configuration panel and turn on Structured key-value output in the key-value block options. Hover a key-value line in the output to see the boxes for its label and answer. Use View code to copy the matching config JSON.
Node reference
Every node has the same six fields, so you can branch on type without checking which keys are present.
How the tree is shaped:
- Answers nest under their label. A value is a
text_fieldchild of itskey. Labels nest too: a section heading or question is akeywhose children are the field labels under it (Date of birth > Month > 04). - Options are labels with a mark. Each printed option is a
key(the option text) whose first child is itsselection(the mark). The options for one question sit together in aselection_group. A “check here” box with no printed option text is a bareselectionin the group. Multi-select questions have the same shape, with more than oneselected: true. - Tables are row > column > cell. A
tablenode’scontentholds the HTML; itschildrenare row-headerkey> column-headerkey>text_fieldorempty_field. A column header that’s printed once is repeated under each row, with the same box. - Coordinates match the block. Boxes use the same units as the block’s
boundingBoxandmetadata.page.width/height; divide by those for page fractions. See Bounding box coordinates.
Examples
The examples below are trimmed from real runs; ids are omitted for brevity.
Patient intake form
Values, nested labels, and blanks. The date of birth’s Month, Day, and Year captions are keys under Date of birth, each with its own value. The unfilled email line is an empty_field with the box of the empty input.
A Yes/No question. Each option label is a key with its mark as the first child; the selection box is the checkbox itself, not the label.
A signature. The signature has no printed name, so content is ""; its box covers the handwritten mark above the caption.
Tax form: Schedule K-1 (Form 1065)
One of several options checked, and a lone “check here” box. Item G’s two options share one selection_group under the G key. Item I2 has no printed option text, so its selection sits directly in the group.
A table inside the form. Item J’s grid is a table node. Its children are row > column > cell, so each percentage flattens to a path like J … > Profit > Beginning = 25.0000 %. The Loss and Capital rows (trimmed here) have the same shape.
Empty cells keep their printed units. Item K1’s unfilled liability amounts come back as { "type": "empty_field", "content": "$ <blank />" } under their row and column keys.
Reference
- Create Parse Run and Parse File (sync):
config.blockOptions.keyValue.structuredOutputEnabledand theKeyValueFormNodeschema blockOptions.keyValue.structuredOutputEnabledin the configuration reference- Response Format: blocks,
details, and bounding box coordinates