Parser schemas and OCR

Work in an organizationCopy Anchor Link

Open /<organizationSlug>/parsers. Owners and organization administrators can create and archive parsers, edit schemas, publish versions and clone a version to the draft. Members can read schemas and upload documents. Global administrator access still requires membership in the requested organization.

Parser slugs remain stable when their display name changes. Archived parsers remain readable; editing and new uploads are disabled.

Build and publish a schemaCopy Anchor Link

Use Fields to add, edit and order fields, tables and columns. Configure required values, evidence, repeated fields, examples and validation constraints. Rules accept a validated JSON AST; review policy settings are saved with the schema. Neither rules nor review policy are executed by the current OCR pipeline.

Definition version 2.0 supports string, decimal, integer, boolean, date, currency amount and email. Decimal values use strings to preserve precision:

{
	"total": "1234.56",
	"payment": { "amount": "1234.56", "currency": "USD" },
	"quantity": 3
}

Decimal minimum/maximum constraints also use strings. Old schema types and old data are not imported. Field/table key renames update rule references.

Publish validates the definition and compiled schema, shows changes and stores an immutable version. Publishing an unchanged definition returns the existing version. The full-definition checksum and compiled-schema checksum are distinct. Cloning restores a version into the editable draft.

Concurrent changes produce a conflict. Your unsaved form stays open; reload the draft before retrying. Closing unsaved editors requires confirmation.

Upload and view documentsCopy Anchor Link

The document inbox accepts one PNG or JPEG per upload, up to 20 MiB and 50 million pixels. Uploads use a short-lived signed PUT with immutable object protection. After storage metadata is verified, the server creates durable processing tasks. You can cancel an upload while the file is transferring.

The independent worker verifies file signatures and dimensions, runs OCR, preserves raw output and creates DocumentIR. The inbox polls processing status and shows the private original image and page text when OCR completes. Invalid image content fails processing even when its declared file type is PNG or JPEG.

parsed means OCR/DocumentIR is complete. Field extraction, business validation, review, approval, connector delivery and export are not yet available. Classifiers, integrations, post-processing, reviews and product API keys are explicit read-only previews.

Configure private storage and the workerCopy Anchor Link

Set the following server-only variables for an S3-compatible private bucket:

S3_ENDPOINT="https://your-account.r2.cloudflarestorage.com"
S3_REGION="auto"
S3_ACCESS_KEY_ID="your-access-key"
S3_SECRET_ACCESS_KEY="your-secret-key"
S3_ATTACHMENTS_BUCKET_NAME="attachments"

For browser uploads, allow the SaaS origin in bucket CORS, with PUT/GET/HEAD and Content-Type/If-None-Match headers. Presigned URL authorization does not replace CORS. Keep originals and artifacts private.

The worker starts separately from pnpm dev:

pnpm worker:dev

Development fixture OCR produces test text; storage is still required. For live OCR configure OCR_GATEWAY_BASE_URL and OCR_GATEWAY_API_KEY, set PARSERELAY_OCR_MODE=live, and run the production worker:

NODE_ENV=production pnpm worker:start

The application and worker must share database and storage settings. Production rejects fixture mode. Tasks renew their leases; fencing tokens reject stale results. Cancelled and expired uploads are cleaned from private storage.

Validate an installationCopy Anchor Link

Run the isolated SaaS suite with pnpm --filter saas e2e:ci. It uses a dedicated SQLite database, a local S3 fixture and fixture OCR; it does not clear your local application database.

For an explicitly configured live environment, invoke checks independently:

pnpm verify:integrations --database
pnpm verify:integrations --storage
pnpm verify:integrations --ocr

The storage check creates and removes a unique test object. The OCR check calls the configured real service and requires PARSERELAY_SMOKE_IMAGE_URL. These checks do not replace browser CORS and complete workflow validation.