Versioning
The API version, document type versions, and the engine and SDK versions.
On this page
Four things carry a version in ReceViz: the API, each document type, the extraction engine, and the SDKs. Each shows up in requests or results, so you can tell which one changed.
The API#
The API is version 1, and the version is part of every path: /api/receviz/v1/…. Webhook envelopes carry "api_version": "v1". The OpenAPI document at GET /v1/openapi.json is generated from the running code, which is where the API reference reads it from.
Several objects are documented as open: an extraction, a field result and processing may carry fields beyond those listed. Write clients that ignore fields they do not know.
Document type versions#
A document type is a series of published versions, 1, 2, 3 and so on. A version never changes once it is published; a draft becomes the next version only when someone publishes it, and a change that could break an integration has to be published deliberately.
| Where | What |
|---|---|
| An extraction | schema_version and schema_id: exactly which version read the document |
| A request | schema_version picks a version; otherwise the application's pinned one, otherwise the latest |
GET /v1/document-types/{key}/versions/{version} | One published version, with its definition, its JSON Schema and what changed from the one before |
GET /v1/schemas/{schema_id} | The same, by schema id |
Each version records its changes from the previous one, each with a kind (such as field_added or type_changed), a path, and whether it is breaking; the version itself says whether it was a breaking release. See Drafts, versions and breaking changes.
The engine#
Every extraction carries processing.engine, such as receviz-engine/1.0.0, and every quality record carries the version of the engine that made the first reading. When a result changes between two runs of the same document and the same schema version, the engine version tells you whether ReceViz's reading changed rather than the document. Quality figures are broken down by engine version for the same reason.
SDKs#
The SDKs identify themselves on every request with X-ReceViz-SDK: <platform>/<version>, for example web/0.1.0, ios/0.1.0 or android/0.1.0. The request log shows it, and usage and quality can be broken down by platform. A client of your own may send the header too: ReceViz recognises the platforms web, ios, android, react-native, flutter, node and python, and records any other as other.
All three SDKs are at version 0.1.0 and not yet published to a package registry; see the Web, iOS and Android pages for the state of each.