new

Document Version Usage Guide

Through the

Good Implementation Practice

s for

document_version

guide , the aim is to standardize how technical teams manage document versions within integrations with the ROOK SDK and APIs.

This guide helps ensure reliable communication between client systems and ROOK integration, reducing synchronization errors, incompatibilities, and the use of outdated data during integration processes.

Standardization

The initiative aims to prevent common errors stemming from improper version control, such as synchronization failures, incompatibilities between environments, and the transmission of outdated data. With proper implementation of

document_version

, developers can maintain more stable integrations, reduce production issues, and optimize the traceability of collected data.

Technical context

The

document_version

acts as a key identifier within ROOK's data structures. Each submitted data structure includes this version, which allows for validation of the delivered JSON version by referencing an update to a previously extracted and delivered data structure.

{
  "client_uuid" : "demoClientUUID" ,
  "user_id" : "demoUserId" ,
  "version" : 2 ,
  "document_version" : 1 ,
  "data_structure" : "physical_summary" ,
  "physical_health" : {
    "summary" : {}
  }
}

To avoid these scenarios, ROOK recommends that teams proactively validate and update health data with each new delivery of data structures according to their version.

Principles of good practice

The following recommendations should be followed when integrating ROOK and using datasets:

Keep the
document_version
updated and synchronized.
Record and track changes to the data before and after each dataset delivery.
Avoid using outdated versions.

These recommendations aim to strengthen the reliability of the integration ecosystem and significantly reduce the risk of operational errors.

General guidelines

document_version
identifies the most recent state of a user's synchronized data.
Whenever the user's data changes (for example, new measurements or updates from the source), the version also changes.
ROOK uses this value to determine what information has already been delivered and what still needs to be synchronized.
Customers must correctly store, update, and forward the latest
document_version
received in each communication.

Synchronization and storage

Always save the latest synchronized
document_version
.
Never manually generate this value; versions are managed exclusively by ROOK.
Avoid deleting or resetting previously stored versions.
Maintain sequential synchronization to ensure data consistency.

Logs and traceability

It is recommended to record the following in the internal logs:

The previous and new value of
document_version
in each synchronization.
Compatibility or misalignment errors detected.

This facilitates monitoring, debugging, and historical control of changes between versions, allowing for a faster response to incidents or inconsistencies.

Recommended implementation flows

First time you receive a dataset

It will arrive with
document_version: 1
.
Validate the day or time window of the dataset using the
datetime
field .
Save the entire dataset.
Use that version as your initial reference for synchronization and display.

An updated dataset arrives

ROOK will send a
document_version
greater (for example, 2).
Validate the datetime of the dataset, as updates from previous days may arrive.
If the dataset corresponds to the same time window, it completely replaces the previous dataset.
Save the new
document_version
like the current version.
From that moment on, all interaction must be synchronized using that version.

If you receive a minor version

Example: You have version 2 and you receive version 1.
Validates the
datetime
of the dataset.
Sometimes updates from previous days arrive, but the correct match should always be based on the combination:
document_version
+
datetime
.
If the
document_version
is lower, ignore the dataset.
Log the event as misalignment.

Using datetime

It is not enough to use only
document_version
, you must also consider the datetime of the dataset.
This is key because ROOK can send updates from previous days, and if only the version is compared, errors such as the following can occur:
Example 1: Current day: 20/11/2025, you receive
document_version = 5
.

- Then comes a `document_version = 6 `, but from 11/18/2025.

- `datetime` is not validated: You could incorrectly replace the data from the 20th with old data from the 18th.

Example 2: You have
document_version = 5
from 11/20/2025.

- Then comes `document_version = 3` from 11/19/2025`.

- With the correct logic: That dataset should be ignored, as its version is smaller and corresponds to a previous day.

Validations and testing

To ensure a stable and consistent

document_version

implementation, it's necessary to validate the integration's behavior under various scenarios. These tests help detect misalignments, update errors, and synchronization issues before going into production.

Validate receipt of the first dataset or initial version: confirm that the user correctly receives the initial version.
Validate update with new version: ensure that data is replaced correctly when a major version is released.
Validate misalignment (minor version): prevent old data from overwriting current information.
Validate loss of synchronization: verify that the client can recover the correct state if they lose the saved version.
Validate logging: ensure useful traceability for support and debugging.

Implementation Checklist

Correct use of document_version:

The client always stores the latest
document_version
received. Validate that each received dataset includes
document_version
.

1. major version → replace entire dataset

2. minor version → ignore and log in

Do not manually edit the
document_version
value.
It does not mix datasets with different versions.
Ensure that the updated dataset replaces the previous one

Technical FAQ

What happens if I don't update the document_version?

If you don't update it, your integration may display outdated or inconsistent data. This often leads to logic errors and problems with the end-user experience.

What do I do if I receive a dataset with a lower document_version?

Ignore it completely. That indicates a misalignment or a resending of old data. The correct thing to do is:

Do not replace the current dataset.
Record the event in logs.

How do I know if I should replace the dataset?

Very simple:

Major version: replaces the entire previous dataset.
Same version: You shouldn't receive it, but if it happens, ignore it.
Minor version: ignore it and log in as misalignment.

Can I generate the document_version myself?

No. The version is generated solely by ROOK to ensure consistency and traceability. Your integration should only receive, store, and forward it.

What happens if I mix datasets from different versions?

You will generate corrupt or inconsistent data for the end user.

Each dataset represents a complete snapshot of the user's state: they are not mixed, they are replaced.

How do I prove that my implementation is correct?

You must validate:

First dataset → version 1 received and stored.
Update → major version replaces all data.
Misalignment → minor version is ignored.
Logging → before/after each version.
Recovery → validate behavior if your client “loses” the version.

Why does ROOK use document_version?

For:

Ensure that the client always displays the user's latest correct photo.
Avoid inconsistencies if old data is resubmitted.
Ensure stable synchronization in integrations with many users and sources.