Generate Edit Schema

Generate Edit Schema detects the fields in a PDF form and returns an edit schema you can pass straight to /edit or /edit_runs. The returned schema has field positions annotated, so you don’t have to write extend_edit:bbox coordinates by hand. Optionally, supply your own schema and Extend maps it onto the detected fields.

Reach for it when you:

Need a starter schema for a new PDF form.
Want to map an existing schema onto a vendor-specific layout.
Need annotated field locations before running edits at scale.
Want to add conditional form logic on top of detected fields.

This endpoint is synchronous and returns the generated schema directly — there are no schema-generation run objects to poll or delete.

Quick start

We’ll detect the fields in a PDF form. Grab a key from the Developers page and store it as the EXTEND_API_KEY environment variable. If you’re using an SDK, see the installation instructions.

$ export EXTEND_API_KEY="your_api_key_here"

Python

TypeScript

Java

Go

cURL

1 import os
2 from extend_ai import Extend
3 
4 client = Extend(token=os.environ["EXTEND_API_KEY"])
5 
6 result = client.edit_schemas.generate(
7     file={"url": "https://example.com/form.pdf"},
8     config={
9         "instructions": "Detect the form fields and use human-readable field names.",
10         "advancedOptions": {"radioEnumsEnabled": True},
11     },
12 )
13 
14 print(result)

Response

The response contains the generated schema and optional mapping metadata.

Field	Type	Description
`schema`	object	The final generated schema after mapping. If no `inputSchema` was provided, this is the same as `annotatedSchema`. Pass it to `/edit` or `/edit_runs`.
`annotatedSchema`	object \| null	The original schema detected from the file, annotated with field locations.
`mappingResult`	object \| null	Present when you provide an `inputSchema`. Contains `matches`, `unmatchedInputPaths`, and `unusedFormFieldKeys`.

Request configuration

The config object is an edit schema generation config:

Field	Type	Description
`inputSchema`	object	An existing edit schema to map onto the detected form fields. When provided, the response includes a `mappingResult`.
`instructions`	string	Custom instructions for field detection and naming.
`advancedOptions.tableParsingEnabled`	boolean	Parse table regions as arrays of objects. Defaults to `false`.
`advancedOptions.radioEnumsEnabled`	boolean	Model radio fields as enums so only one widget in a group is selected. Defaults to `false`.
`advancedOptions.nativeFieldsOnly`	boolean	Only use native AcroForm fields from the PDF and skip object detection. Defaults to `false`.

A common workflow

The generated schema uses the same format as edit runs, including support for root-level JSON Schema conditionals. A common workflow is:

Generate a base schema from the PDF form.
Add conditional requirements for follow-up fields.
Use the refined schema with /edit or /edit_runs.

For the exact request and response schemas, see the Generate Edit Schema API reference.