Schema locking

Schema locking controls what fileAI does with a document that matches none of your file types. With locking off, fileAI proposes a new file type for it. With locking on, fileAI must classify it into one of your existing, approved schemas (Verify in the app), so your set of file types stays fixed. See Concepts for file types and schemas.

When to use it

Turn locking on when	Keep locking off when
You process a known, fixed set of document types.	You are still discovering which document types you receive.
Downstream systems expect consistent schema names.	Your document mix changes often and you want new types detected.
Several people upload and you want consistent classification.	You prefer to review and approve new schemas as they appear.
Compliance rules allow only certain document categories.

How it works

Say your project has three schemas: Invoice, Bank Statement and Job Contract. You upload a parking ticket.

With locking on, a document unlike any of your schemas is still forced into the closest one. Clean up your schemas before you lock, and review classifications periodically.

Turn it on in the app

Edit the AI Schema

Open a processed file and adjust its AI Schema if needed. See AI Schemas.

Verify the AI Schema

At the upper right of the file, open the Verify AI Schema dropdown and confirm. You can also rename the schema here.

Check your verified schemas

Go to File Intelligence → Extraction Schema to see every schema you have verified.

Lock

In the Extraction Schema tab, turn on the Schema Locked toggle at the upper right. From now on, uploaded files are classified only into these schemas.

New projects start with locking off.

Set it per upload

Over the API, schema locking is a per-upload boolean, schemaLocking. Send it when you request the upload:

curl -X POST "$FILEAI_BASE_URL/files/upload" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "ticket.pdf", "fileType": "application/pdf", "schemaLocking": true }'

Every upload route accepts it, per file or in batch defaults; see Upload options. A value other than true or false is rejected. There is no project-wide API setting: PATCH /v1/project/setting does not accept schemaLocking, so the project toggle is app-only.

To skip classification entirely for an upload, pass a blueprintId instead. fileAI then uses that file type for every document in the file. See Uploads.

Best practices

Start unlocked. Let fileAI discover your document types, and approve the ones you want.
Lock once your core types are stable. Clean up duplicate or unused schemas first.
Unlock temporarily when you know new document types are coming, then lock again.
Write down your approved schemas so your team knows which types exist and when locking may be lifted.

AI Schemas

File types, schemas and the API to manage them.

Uploads

All upload options, including schemaLocking and blueprintId.

Get started

Products

Build

Go live

When to use it

How it works

Turn it on in the app

Set it per upload

Best practices

AI Schemas

Uploads

​When to use it

​How it works

​Turn it on in the app

​Set it per upload

​Best practices

​Related

AI Schemas

Uploads

When to use it

How it works

Turn it on in the app

Set it per upload

Best practices

Related