Provenance and review
Every value keeps its source, author, time and evidence and is superseded rather than overwritten; declared data is reviewed before it enters a passport, with a second person when the organisation's four-eyes rule is on.
A passport is only as trustworthy as the values in it. BatteryPass therefore records where each value comes from, who entered and approved it, and which documents support it, and it keeps every earlier state.
A value is a revision
Every value is stored as a revision (FieldValue). The API returns these members:
| Member | Meaning |
|---|---|
value, unit | The value as JSON and its unit of measure; value is null when the field was cleared |
revision | 1, 2, 3 … per field and target (model version or unit) |
source | Where the value came from, see below |
recorded_by, recorded_at | Who recorded this revision and when |
responsible | The member responsible for the value |
review_status, reviewed_by, reviewed_at, review_note | The review decision |
evidence[] | The documents this revision rests on (kind, title, tier, revision) |
checks[] | Results of the automatic checks: pass, warn or fail with a message |
measured_at | For condition data: when the value was measured |
superseded_at | When a newer revision replaced this one |
registry_version | The registry version the value was recorded under |
source | Meaning |
|---|---|
manual | A member entered it in the portal |
import | It came from a spreadsheet import |
supplier | A supplier sent it through a request link, or a service partner reported it |
api | An API key reported it (condition data only) |
system | BatteryPass wrote it |
Values are superseded, never overwritten
A change never edits a stored value. It inserts a new revision and marks the previous one as superseded, so the full history stays available, including who changed what and when. A review decision is a revision too: approving inserts a revision with the same value and the reviewer.
| Operation | Returns |
|---|---|
listModelVersionValues, listBatteryValues | The current revision of each field of a model version or unit |
listModelVersionValueHistory, listBatteryValueHistory | Every revision of one field, newest first |
listEvidence, getEvidence, downloadEvidence | The documents, their revisions, where they are used, and the files |
curl -s "$BATTERYPASS_URL/api/v1/model-versions/$VERSION_ID/values/performance.nominal_voltage/history" \
-H "Authorization: Bearer $BATTERYPASS_API_KEY" \
| jq '.items[] | {revision, value, source, review_status, reviewed_at}'Documents are versioned in the same way: a new revision of a document supersedes the old one, and a value that rests on a superseded document is flagged by a failing check.
Review status
review_status | Meaning |
|---|---|
captured | Recorded; an automatic check failed or has not passed yet |
auto_checked | The automatic checks passed; waiting for a reviewer |
approved | A reviewer approved it; only approved values enter a passport version |
rejected | A reviewer rejected it with a note; the responsible member corrects it |
A reviewer (role reviewer, admin or owner) approves in the portal. An approval is refused while
- a check of the value fails,
- the registry requires evidence for the field and no current document supports the value, or
- the reviewer recorded the value themselves and the organisation has the four-eyes rule on (the default).
The values of a spreadsheet import can be approved in one action per import, under the same rules for each value. Values that one of these rules holds back stay open for individual review.
Condition data is the exception: values reported as measurements are accepted without a reviewer and stored
as approved with their measured_at. See Condition data and lifecycle.
Why API keys cannot approve or publish
An API key belongs to the organisation, not to a person. The four-eyes rule compares the author of a value
with its reviewer, and publication needs a reviewer who answers for it. A key that is nobody could not take
part in either without weakening them, so keys never write declared data, approve values, publish or withdraw
passports. They read, and with the condition scope they report measurements and lifecycle events, which
carry source api; the lifecycle event of each report names the key in api_key.
Declared data reaches BatteryPass through the portal, supplier requests or the spreadsheet import, and is approved by members.
With the import scope a key stages a spreadsheet import: upload, mapping, validation. Only members commit it and
approve the imported values in the portal, so data from an ERP becomes declared data only through a member's decision
(ADR-026). See Units from production.
Completeness
getModelVersionCompleteness and
getBatteryCompleteness evaluate the registry for a
model version or unit and give each field a display status:
display | Meaning |
|---|---|
required_missing | Required now, no current approved value; blocks publication |
required_pending_review | A value exists but is not approved; blocks publication |
ok | An approved value is present |
not_applicable | Marked as not applicable, with a stored reason |
later_required | The obligation starts later or is not triggered yet |
optional_missing | Optional and empty |
There is deliberately no percentage. The summary counts the statuses, and summary.blocking is the number
of fields that still block publication.