Template editor — Schema

Not yet checked on the product

This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.

The template editor is where you decide what Vision extracts from a type of document. Its Schema tab holds the template's sample documents on the left and its list of fields on the right: you let the AI propose the fields from a sample (fields definition), adjust names, types and extraction prompts, test a prompt against the sample, and save the result with Save template.

How to get here	Templates › click a template card. Creating a template on the new-template screen also opens it here. The editor opens on the Schema tab.
Who can use it	Every call this screen makes goes to the Vision service, which only answers members of the company whose membership is active and who have access to Vision. A lookup failure is a denial. The screen itself checks no role.
Content status	From source; not observed (vision-fe 0b724a0, vision-be fce7fcc, 2026-10-22)

The editor shell

Before showing any tab, the editor checks that the template exists and belongs to your company.

• While it checks: Loading template...
• If the template does not exist, was deleted, or belongs to another company: the heading Template not found and We couldn't find this template, or it doesn't belong to your account. Return to the templates list to pick another one. No tab is shown.
• Otherwise, three tabs (Template editor tabs):

Tab	What it holds
Schema	This page.
Agent	How the agent runs extraction for this template. See Agent.
Redaction	What this template may redact. See Redaction.

Each tab has its own address (/templates/edit/…/schema, …/agent, …/redaction); opening the editor without a tab goes to Schema.

Header

Element	What it shows or does
Back (arrow)	Returns to the Templates list. Unsaved changes on this tab are lost without a warning.
Breadcrumb	Templates / the template's name (or Templates while the name is unknown).
Document badge	… documents — how many sample documents the template has. Shown when it has at least one.
Save template	Saves the schema. See Save the template.

Two banners can appear under the header:

• A red banner (errors) or a toast (successes) for the messages listed on this page. Most disappear after 4 seconds.
• When the template is already published (status Finished), a permanent note: Editing this template updates it in place. Pending jobs may use the updated schema or fail if the template cannot be resolved. See Published templates and versions.

Document Preview

The left pane, Document Preview — Choose a file and define the schema from the selected sample. — shows the template's sample documents. One is selected at a time; it is the document that fields definition reads and that Run Test tests against.

Buttons and actions

Button	What happens	Who	Reversible?
Add document (in the pane header, and + in the thumbnail bar)	Opens the file picker. You can pick several images (any image type) or PDFs; each is uploaded on its own and appears at once as a thumbnail while it uploads. The first document of an empty template is selected automatically. Document added successfully. when the upload is confirmed.	Any Vision user	Yes — remove the document
Zoom out	Shrinks the preview by 20 %, down to about 40 %.	Any Vision user	Yes
Zoom in	Enlarges the preview by 20 %. Above 100 % you can drag the page (mouse or touch) to move around it.	Any Vision user	Yes
Fit to center	Resets zoom to 100 %, removes the rotation and centres the page. Selecting another document does the same.	Any Vision user	—
Rotate	Turns the preview 90° clockwise. Display only: the stored document is not changed.	Any Vision user	Yes
fields definition	Asks the AI to propose the template's fields from the selected document. See fields definition.	Any Vision user	No — it replaces the field list
Hide thumbnails / Open thumbnails	Switches the thumbnail bar between large tiles (default; a page-1 image of each document) and a compact strip of file names.	Any Vision user	Yes
Thumbnail or file name	Selects that document.	Any Vision user	—
x on a thumbnail	Asks Are you sure you want to delete this document? (Confirm deletion). Delete removes the document from the template and from storage; Cancel or Escape closes the dialog. Not available while the document is still uploading or being removed.	Any Vision user	No

When a stored PDF cannot be rendered, the preview shows Select a document to preview. and its tile shows the first three letters of the file name. With no document at all, the stage shows Select a document to preview. and the compact strip shows No document.

What the service does with documents

• An uploaded document goes through the service's document admission checks and file validation (at most 50 MB per file) and is stored for the template. A rejected file shows Failed to upload document.
• Documents can be added or removed only while the template is not published. On a Finished template the service refuses both, and the screen shows Failed to upload document. or Failed to remove document.
• A removed document is deleted from storage. The success message says Document removed and template is reprocessing., but for a template that is not published nothing is reprocessed.

fields definition

fields definition sends the selected document to the AI and asks it to describe the document's structure — field names, types and extraction prompts, no values.

1. The button is disabled while a definition is already running, while no document is selected, while a document is being removed, and while the template is being saved. Its tooltip says why: Extraction in progress — please wait, Select a ready document to define extraction fields, or fields definition.
2. When it starts, the pane shows Extracting data… with a rotating message every 5 seconds (Still processing, Identifying field structure, Getting document information, Almost there, Just a little more) and the elapsed seconds.
3. When it ends, the proposed fields replace the list: Extraction fields loaded successfully. If it fails or returns no field, the current list stays as it was.

It also runs on its own, once, when the first document finishes uploading and the template has no fields yet — including right after you create a template.

What the service does:

• It reads the stored document and runs the template-discovery instruction with the engine configured for it. The AI is told to use snake_case names, to write short English prompts of the form "extract …", to choose a type among string, number, date, boolean, array and object (tables become array), to mark a field required only when it is evidently always present, and to include only fields it can see.
• On a template that is not published, the proposed schema is saved on the template immediately, before you click Save template. Leaving the editor does not undo it. On a published template it is not saved until you click Save template.
• The call is billable: it consumes credits, is recorded in usage, and is refused when the company's plan has a hard stop and its allowance is exhausted. It is also rate-limited with the other document-processing calls.

Field Settings

The right pane, Field Settings — Edit field names, visibility and output types. — lists the template's fields. Above the list, a summary: … fields (every field, columns of tables included), … tested (fields with a test result) and avg confidence …% (the rounded mean of the test confidences). With no field yet: No fields loaded yet. and Use fields definition after selecting a document.

There are two kinds of row:

• A simple field: type chip, name, the last test confidence (…%) when the field has been tested, the type list, Settings (gear) and Remove field (bin).
• A table (type Table) or an object (type Object): a group with a chevron (Collapse / Expand, shown when it has sub-fields), the name (placeholder Table), a Table or Object badge, the type list, Settings (gear), Add field to table and Remove field. Its columns or sub-fields are listed indented under it, each as a simple field — or as a nested group.

Fields

Field	What it does	Required	Format / values	Default	Validation messages
Name (placeholder Field name, or Table for a table)	The key the field has in the extraction result. Typing a space inserts _; any character other than letters, digits and _ is removed as you type. Changing the name refreshes the field's prompt only while it is still the default prompt of its type (or empty); a prompt you wrote is kept (see Field types).	Yes	Letters a-z A-Z, digits, _; must start with a letter or _	Empty for a new field	Only letters (a-z, A-Z), digits, and underscores. Must start with a letter or underscore. (simple fields; a table name is only outlined in red)
Type list (Field Settings)	What the field holds and how its value is post-processed. Changing the type refreshes the field's prompt to the default prompt of the new type only while the prompt is still a generated default (or empty); a prompt you wrote is kept. Choosing Table opens the group so you can add columns.	Yes	The 14 types in Field types	String for a new field	—
Prompt (in the settings drawer)	The instruction the AI follows to extract this field.	No	Free text	The default prompt of the type, or the prompt proposed by fields definition	Prompt is required to run the test. (only when testing)

A field also carries two properties that this screen keeps but does not let you change: required (set by fields definition when the AI judged the field always present; false for fields you add) and visible (true unless a loaded schema says otherwise). The service code does not act on either; they reach the AI only as part of the schema it is given. A description that fields definition may propose is dropped on save.

Field types

The type list offers 14 types. The default prompt is what the field's prompt becomes when you set its name or type; you can then change it in Settings. The last column applies to every extraction with the template — Playground, synchronous API and extraction jobs; see What happens at extraction time.

Type (key)	What it extracts	Default prompt (for a field named x)	What the service does with the value
String (string)	Any text.	Extract field x	Returned as extracted.
Number (number)	A numeric value.	Extract field x	Rewritten as a plain number: currency symbols and letters removed, thousands separators dropped, decimal separator .. With both . and , present, the last one is the decimal separator; a lone , is decimal only with 1 or 2 digits after it, and a lone . with exactly 3 digits after it is read as a thousands separator. Left unchanged if it cannot be read.
Date (date)	A date.	Extract field x	Rewritten as YYYY-MM-DD (or YYYY-MM for a month and year) when it can be read — numeric formats such as dd/MM/yyyy, yyyy-MM-dd, MM/dd/yyyy, yyyyMMdd, and month names in English or Portuguese. Left unchanged otherwise.
Table (array)	A list of rows — line items, a table. Its columns are the fields you add with Add field to table.	Extract field x	Returned as a list. If the AI returns comma-separated text instead, it is split into a list. Each row's columns are post-processed by their own types. A table without columns is saved as a list of text values.
Signature presence (signature)	Whether a signature is present.	Extract field x. If a signature is present, return true. If no signature is found, return false.	Returned as extracted.
Face presence (face)	Whether a face photo is present (for example on an ID document).	Extract field x. If a face photo is present in the document (e.g. an ID document), return true. If no face photo is found, return false.	Returned as extracted.
Checkbox (checkbox)	Whether a checkbox is ticked.	Extract field x. If the checkbox is checked, return true. If the checkbox is not checked, return false.	Returned as extracted.
Email (email)	An email address, as written.	Extract field x. Find and return the email address exactly as written (e.g. name@example.com). If no email address is found, return null.	Returned as extracted.
Phone number (phone)	A phone number with its country and area codes, as written.	Extract field x. Find and return the phone number, preserving all country and area code digits exactly as written. If no phone number is found, return null.	Returned as extracted.
Barcode (1D) (barcode_1d)	The decoded value of a one-dimensional barcode (Code 128, EAN-13, UPC…).	Extract field x. Locate the 1D barcode (e.g. Code 128, EAN-13, UPC) and return its decoded value. If no 1D barcode is found, return null.	Returned as extracted.
QR code (qr_code)	The text, URL or data embedded in a QR code.	Extract field x. Locate the QR code, decode it, and return the embedded text, URL, or data. If no QR code is found, return null.	Returned as extracted.
Stamp / Seal (stamp)	Whether an official stamp or seal is present.	Extract field x. If an official stamp or seal is present in the document, return true. If no stamp or seal is found, return false.	Returned as extracted.

For the presence, checkbox, email, phone, barcode and QR types, what comes back is decided by the prompt and the AI model; the service applies no type-specific processing to them.

Two more types are in the list:

• Object (object) — a group of fields. It is shown as a group, like a table, and its sub-fields are listed under it; add them with Add field to table. Sub-fields of an object are post-processed by their own types.
• Yes/No (boolean) — a true/false value, returned as extracted.

Older schemas whose types are written in Portuguese (lista, objeto, numero, data) are read as Table, Object, Number and Date; any type the editor does not know is read as String.

Buttons and actions

Button	What happens	Who	Reversible?
Add field	Adds an empty String field at the top of the list. Enables Save template.	Any Vision user	Yes — remove it
Add field to table (on a table or object)	Adds an empty String column or sub-field at the top of the group and opens it.	Any Vision user	Yes — remove it
Collapse / Expand (chevron on a table)	Hides or shows the table's columns.	Any Vision user	Yes
Settings (gear)	Opens the prompt drawer for the field, table or object. See Prompt drawer.	Any Vision user	—
Remove field (bin)	Asks Are you sure you want to remove the field …? (Remove field). Remove deletes the field — a table with all its columns — from the list: Field "…" removed. Cancel or Escape keeps it.	Any Vision user	Only by leaving without saving, or by adding the field again

There is no way to reorder fields, no import or export of the schema, and no undo on this screen. Every change on this tab lives only in the browser until you click Save template — except the schema that fields definition saves on its own (see fields definition).

Prompt drawer

Settings on a field opens a drawer on the right. Its title is the field name (or Field Prompt when the field has none), with the field's type under it. Clicking outside the drawer, Close (×) or Escape closes it and discards an unsaved prompt.

Field	What it does	Required	Format / values	Default	Validation messages
Prompt	The extraction instruction for this field (placeholder Define the extraction prompt).	To run a test	Free text; leading and trailing spaces are removed	The field's current prompt	Prompt is required to run the test.
Result	Read-only. The value the last test returned (placeholder Run test to see result), with Confidence …% next to the heading.	—	Text	Empty	—

Button	What happens	Who	Reversible?
Run Test (Running test... while it runs)	Runs the prompt currently in the box — saved or not — against the selected document and shows the value and its confidence. Field test completed for "…". The result and confidence also appear on the field's row and in the summary.	Any Vision user	—
Save Prompt	Keeps the prompt on the field and closes the drawer: Prompt updated for "…". The template itself is not saved yet.	Any Vision user	Yes — edit it again

What the service does with a test: it runs a single-field instruction with the engine configured for field tests. Only your prompt is sent — not the field's name or type — so the prompt alone must say what to extract and in which format. The AI returns one value (or nothing when the value is absent, illegible or uncertain) and a confidence from 0 to 100, which the service clamps to that range. Like fields definition, a test is billable, recorded in usage, and rate-limited. Test results are not stored with the template.

Tables have no Settings button, so a table's own prompt cannot be edited here: it keeps the prompt from fields definition, or the default Extract field … it got when you named it.

Save the template

Save template builds the schema from the field list and sends it to the service, then returns to the Templates list.

It is disabled — with the tooltip that explains why — while saving (Saving template…), while fields definition runs (Wait for the extraction to finish before saving), and while no field has been defined or added yet (Run "fields definition" first — there is nothing to approve yet). Otherwise its tooltip is Save template.

What is saved, per field:

{
  "invoice_number": { "type": "string", "prompt": "Extract field invoice_number", "required": false, "visible": true },
  "items": {
    "type": "array", "prompt": "Extract field items", "required": false, "visible": true,
    "items": { "type": "object", "properties": { "amount": { "type": "number", "prompt": "Extract field amount", "required": false, "visible": true } } }
  }
}

• Saving is refused, with a message, when a simple field has no name (Every field needs a name before you save.), when a name breaks the naming rule (These field names can't be used: …), or when two fields at the same level share a name (These field names are used more than once at the same level: …). A table with an empty name is still saved as items (then items_2, items_3…).
• A table that was switched to another type loses its columns on save.

What the service does:

Template status	Call	Effect
Not published (draft, queued, processing, error, training)	Finish	Saves the schema. Unless the template is already training, it moves to Processing and its provisioning job is queued; the Templates list follows the status until the template is Finished.
Finished (published)	Update	Saves the schema in place, without provisioning again, and records a new definition version if the schema changed.

The schema is stored encrypted, and each save is written to the audit trail.

Published templates and versions

A template with status Finished is published. On a published template:

• Save template updates the live schema. Each save that changes the schema records a new numbered definition version, starting at 1; saving an unchanged schema records nothing. A version is also recorded the first time an extraction reads a template that has none yet. The version history is kept by the service and is not shown on this tab.
• fields definition still proposes fields, but they are only saved when you click Save template.
• Sample documents cannot be added or removed (see What the service does with documents).

That is what the banner Editing this template updates it in place. Pending jobs may use the updated schema or fail if the template cannot be resolved. warns about: an extraction job that was accepted with a definition version extracts with that version; one accepted without a version reads the live schema when it runs.

What happens at extraction time

When a document is extracted with this template — in the Playground or through the API — the service turns the saved schema into the instruction the AI follows:

1. The schema is loaded for the caller's company and decrypted.
2. It is embedded whole in the prompt — every field with its type, prompt, required and visible, tables with their columns — with the instruction to return only the top-level field names, spelled exactly, not to invent, rename or add fields, and to return an empty value with confidence 0 for a field the document does not have. Any extra instructions of the caller are appended.
3. The AI returns a value and a confidence for every field (a list of rows for a table).
4. Values are post-processed by type: dates and numbers are normalized and tables split into lists, as described in Field types. The other types are returned as extracted. Extraction jobs apply the same step as a direct extraction, so the same document returns the same values either way.
5. A direct extraction records, with its usage, the template and the definition version it ran on.

The two paths differ when the template cannot be used:

Path	Template missing, of another company, not readable, or with no fields	Template not yet Finished
Direct extraction (Playground, synchronous API)	The extraction goes on without the schema, with the caller's own instructions only. The service logs a warning; the result simply has no template.	The live schema is used.
Extraction job (asynchronous)	The job fails with template_unresolved and is not retried.	The job fails with template_unresolved.

A job accepted with a definition version uses that version's schema, even if the template has been edited since; the template must still exist and belong to the company.

Common problems

Message	Cause	What to do
Template not found (heading) / Template not found.	The address names a template that does not exist, was deleted, or belongs to another company.	Go back to Templates and open the template from there.
Template id not provided.	The editor was opened without a template id.	Open the template from Templates.
Failed to load template.	The template could not be read.	Reload the page.
No documents available to extract fields.	The template was just created without any document.	Add a document with Add document.
Template not identified.	A document was picked before the template's id was known.	Reload the editor and add the document again.
Failed to upload document.	The service refused the file (type, size over 50 MB, admission checks) or the template is published.	Check the file; on a published template, samples cannot change.
Could not verify document addition.	The upload answered, but the new document was not in the answer.	Reload the editor to see whether the document was added.
Failed to remove document.	The service refused the removal — the template is published, or the document is no longer there.	Reload the editor.
Please select a ready document to define extraction fields.	fields definition without a selected document.	Select a document.
This document is not ready for extraction yet.	The selected document is still uploading.	Wait for the upload to finish.
Could not obtain extracted fields for this document.	The AI returned no schema.	Try again, or with another sample.
The document took too long to process. Try again, or use a smaller file.	The definition timed out.	Retry, or use a smaller document.
This file format is not supported for extraction. Use a PDF, PNG or JPG.	The service did not accept the file format.	Use a PDF, PNG or JPG.
This file is too large to process. Try a smaller document.	The file is too large for the definition.	Use a smaller document.
The document quality is too low to read reliably. Try a sharper scan.	The service answered with a validation error. This message is shown for any validation error of the call, not only for image quality.	Retry with a sharper scan; if it persists, the cause is another validation error.
Could not extract the fields from this document. Please try again.	Any other failure — including a refused call when the plan's allowance is exhausted.	Try again; check the plan's usage.
Select a field and a ready document before testing.	Run Test with no document selected.	Select a document.
Prompt is required to run the test.	Run Test with an empty prompt.	Write a prompt.
This document is not ready for testing yet.	The selected document is still uploading.	Wait for the upload to finish.
No result was returned for this field.	The AI found no value for the prompt.	Rewrite the prompt, or test on another sample.
Failed to run the selected field test.	The test call failed (including a refused call when the plan's allowance is exhausted).	Try again.
Could not identify the template to finalize.	Save template without a template id.	Reopen the template from Templates.
Failed to finish the template with extracted data.	The save was refused or failed. Nothing changed on the screen; your edits are still there.	Try again.
A custom prompt was replaced by Extract field …	You renamed the field or changed its type after writing the prompt.	Set the name and type first, then write the prompt.
A field is missing after saving	It had no name.	Give every field a name before saving.

Related

• Templates: list and create
• Template editor — Agent
• Template editor — Redaction
• Playground — run an extraction with the template.
• Developers — call extraction through the API.
• Extraction phase — use the template in a workflow.
• Vision overview

---

Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation