← All posts

API

Schemas are the contract

You describe the fields once in JSON Schema. Tolva returns exactly those fields, typed, or tells you which ones it couldn’t fill.

·

5 min read

Extraction APIs often return whatever they found and leave the shape to you. We went the other way: you send a JSON Schema with the request, and the response is valid against it, or the request fails and names the fields that couldn’t be filled.

Types are kept

A number comes back as a number, a date as an ISO 8601 string, an enum as one of its values. Your code reads the response without parsing strings or guessing formats, and a schema change is a diff you can review.

Missing is not empty

A field the document doesn’t contain comes back as null with a reason, never as an empty string. That keeps a blank invoice line distinct from a line we failed to read.

Versioning the schema

Send a schema id instead of the full schema once it is stable. Old ids keep working, so a new field never breaks a client that doesn’t know about it yet.