AI Schema Generator: Auto-draft a JSON Schema for extraction

Nutrient Data Extraction API’s extract endpoint maps a document onto the JSON Schema supplied in the request, and a field left out of that schema never appears in the response. Writing that schema by hand is the slow part of any extraction project. Every field must be named, typed, and described; repeating structures must be modeled as arrays of objects; and values that may be missing must be distinguished from those that always appear. And the schema has to stay inside a dialect narrower than most developers expect.

The AI Schema Generator in Nutrient Studio writes that first draft. It reads up to five example documents and a plain-language description of what matters, and then scaffolds a working schema, including the field descriptions that do most of the work at extraction time.

The dialect is narrower than standard JSON Schema

Of everything JSON Schema defines, extract accepts seven keywords. It doesn’t support $ref, composition keywords like oneOf, validation ranges, or conditional schemas. The full list of supported keywords and size limits is short enough to read in a minute, but easy to violate out of habit.

Two rules catch even careful authors. The root must be type: "object", and an array root returns a 400 error. And schemas are closed: Every object is processed as though additionalProperties: false were set, so undeclared fields never appear in the response. Setting additionalProperties explicitly, a habit from years of general-purpose JSON Schema, is rejected, not silently ignored.

Asking a general-purpose model for a schema doesn’t avoid this. A model prompted directly for a schema for an invoice reaches for the same keywords a developer would. Examples include $ref for a repeated address block and oneOf for a value that might be a string or a number. That’s what a well-formed JSON Schema looks like everywhere except inside this dialect. The AI Schema Generator only emits schemas the extract endpoint already accepts, so its first draft can be submitted as-is.

Descriptions carry more weight than field names

The extraction model reads the description on each field as an instruction when deciding which value on the page belongs in that field.

This is usually where a working schema and one that produces subtly wrong data differ. A field named total with no description invites ambiguity on an invoice that shows a subtotal, a tax line, a discount, and a grand total. A description that says the final total after discounts and tax makes the intended value explicit. Check the returned value against the invoice before relying on the change.

Effective descriptions do three things: name the field as it appears in the document, state the expected format when it matters, and say which value to take when the document offers several.

This is the part of schema authoring that takes the longest and is most often skipped.

Generating a schema from example documents

The generator lives in Studio under Extract > Playground in the Schema Builder panel. Selecting Generate schema opens a dialog with three inputs.

Example documents — Up to five documents are accepted, and smaller files generate faster. These ground the schema in real layouts, not an idealized description of the document type. The resulting schema should fit other documents of the same class, not just the uploaded samples.

Document type — This names the kind of document, such as an invoice, a contract, or an insurance claim. It anchors the vocabulary the generator uses when naming fields.

Requirements — This input is optional, and it’s the one most worth spending time on. It accepts a freeform description of the fields that matter and the rules that govern them.

That last field accepts more than a list of names. A requirement can express a rule the schema encodes, for example:

Capture both invoice sent date and due date. Calculate the due date from the sent date and payment terms if it isn’t present.

This is a derivation rule. It tells the generator what to model and how the values relate. Without it, that instruction would be written by hand into a field description after the first extraction run returned nulls.

A detailed requirement produces a closer first draft than a bare list of field names. Describe naming preferences and granularity, identify which checkbox groups should become enumerated fields, and say where repeating rows belong.

Reviewing the generated schema

The draft populates the Schema Builder as a list of properties with a type and an optional flag for each, and it can be inspected as raw JSON through the Builder/JSON toggle. Properties can be added, removed, retyped, or reworded from there.

The generated descriptions are the part worth reading closely. They tend to carry the disambiguation and the negative constraints that hand-written first drafts omit. Examples include which party on an invoice counts as the issuer and how to handle a zero balance. Those are the details that determine whether extraction is right on the second document rather than only the first.

Alongside the schema, the Schema Builder exposes an Instructions field for guidance that doesn’t belong to any single property. It might say treat all dates as ISO 8601 or leave a field null when it isn’t present. This maps to the top-level instructions string in the API request and is applied on top of the schema at extraction time.

From draft to extraction

Treat a generated schema as a starting point and review it in four steps:

1. Generate from representative examples, with requirements describing the fields and rules that matter.
2. Read the generated descriptions and correct anything that misreads the document class.
3. Run extraction in the Playground against a document that wasn’t one of the examples.
4. Compare the returned values with the document and inspect their citations.

Citation metadata can include source regions, match labels, and confidence signals. Check whether each citation supports the requested field. A value can match text on the page and still come from the wrong column. Missing source locations need review, and a high confidence score doesn’t establish that an answer is correct.

Test a schema change with evaluation sets

Fixing one invoice can introduce an error on another layout. Nutrient’s evaluation sets compare saved preset versions against the same documents and reviewed answer keys. Use them to check a change before publishing the preset.

Evaluation sets require account access. If Evaluations isn’t available in Studio, follow the evaluation setup guide. Preparing suggested answers and running evaluations use processing credits.

Start with answers checked against the source

The fictional invoice in the PDF-to-JSON tutorial illustrates how to define expected answers. These values come from its printed content, not from an evaluation run:

Add documents with different layouts and missing optional fields. Reserve some documents that weren’t used to generate or tune the schema for a final check. One invoice can verify setup, but it can’t establish production accuracy.

In Studio, open Evaluations, create a set for the saved extract preset, and select Add files. Each set supports up to 25 documents. Studio proposes answers; compare each one with its PDF and correct errors. Check the source regions, select Save corrections, and then Mark as reviewed.

Review every answer key before scoring. Unreviewed items still contribute to the results, so accepting an incorrect suggestion can make a later error appear correct.

Compare two versions of the same preset

1. Select Run and choose the original Preset version explicitly. Studio defaults to the newest version, including drafts.
2. Inspect mismatches between the returned values and the reviewed answers.
3. If a field description is ambiguous, clarify it and save a new draft version of the same preset. Keep the requested fields and other settings unchanged for this comparison.
4. Run the revised version against the same documents and answer keys.
5. Compare individual fields and documents, including those that passed in the first run.

Use a separate test preset for this exercise. In the live test below, the baseline was published within that test preset to preserve v1; saving the edited configuration then created draft v2. Saving changes to an existing draft alone doesn’t preserve two separate versions.

For the sample invoice, an ambiguous total description is a useful field to inspect. If a run returns 160.00, check whether it selected the subtotal. Clarify that the field requires the printed final total including tax. Then rerun both the problem document and the rest of the set. Don’t assume the edit improved extraction until the results show it.

What the sample test returned

In a Studio test on 29 October 2026, both versions processed the same fictional invoice against a reviewed answer key. The only schema change was the description of total_amount:

• v1 — “Total amount.”
• v2 — “Printed final invoice total including tax and discounts. Do not return the subtotal, tax amount, or an individual line amount.”

Both returned the expected invoice number, supplier name, and total of 176. The clearer description produced no measured improvement on this sample. This verifies the version-comparison workflow, not accuracy across other layouts, scans, or missing fields. Those require a broader set of documents, including ones reserved for the final check.

Check values, citations, and failures separately

Value accuracy measures agreement with the answer key. Citation accuracy checks agreement with labeled source regions. Grounding describes the engine’s evidence for a value; it doesn’t determine whether that value matches the answer key. The scoring guide explains these distinctions and the matching rules.

Inspect the counts as well as the percentages. Failed and skipped documents don’t contribute an accuracy score. A higher average with fewer completed documents isn’t enough to accept a change.

Keep the documents and answer keys fixed while comparing versions. If an answer key is wrong, correct it and rerun both versions. Historical scores retain their original answer-key snapshots. For missing information, distinguish an expected JSON null from a missing key: The evaluator scores them differently.

Record which fields improved, which regressed, and which still require review. Then check the revised preset on the reserved documents. Keep the previous version available if the change fails the acceptance criteria for the workflow. The evaluation API guide covers running these checks from code or continuous integration.

FAQ

Related reading

• Define a schema — Supported keywords, closed-schema behavior, and size limits
• Citations and confidence — Grounding extracted values back to source locations
• Extract invoice data with a schema — A worked example
• Evaluation sets — Compare preset versions against reviewed answers
• What should a document extraction confidence score actually tell you? — How to read the confidence signals returned alongside extracted values
• PDF data extraction developer guide — Parse modes, schema design, and where generated schemas fit the wider pipeline