← 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.