> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/tracking/api-reference/readings.md).
# Readings and the field dictionary
Reference for tracking readings: the value model, the reading and its unit rules, and the field dictionary with the queries that expose it.
How a reading is encoded, the reading itself, and the field dictionary that gives each reading its title, unit and nature.
## Queries
### fieldDefinitions
The field dictionary. Needed by any UI that renders readings: without it a client has a name and a number but no title, unit or nature.
Returns an empty list today, whatever `codes` and `includeDeprecated` say: the dictionary is not populated yet. The rest of this description is the contract once it is.
Cacheable, but not immutable. What NTF freezes is an entry's identity — an entry is never renamed — so a cached entry never starts meaning something else. What it does not freeze is the dictionary's composition, and an existing entry can still gain `deprecated` and a `replacedBy`. So a held copy goes stale in one direction only — it can lack an entry, or miss a deprecation, never misdescribe a field it already has. Refetch when a reading arrives whose `code` is not in the cache. The locale is separate: it comes from the request headers rather than an argument here, so a client that switches language re-fetches, and a shared cache is keyed per locale or holds only the locale-independent fields. The headers are not honoured yet (`TrackingFieldDefinition.title`).
```graphql
fieldDefinitions(
codes: [Code!]
includeDeprecated: Boolean = false
): [TrackingFieldDefinition!]!
```
**Arguments**
| Name | Type | Description |
| ------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| `codes` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!] | Limit to these field names. All entries when omitted. |
| `includeDeprecated` | `Boolean` | Include entries marked deprecated. |
**Output types:**
TrackingFieldDefinition
A field dictionary entry. Entries are never renamed, retyped or deleted — only deprecated with a pointer to the replacement, because an entry describes every value ever recorded under that name, not just new ones.
| Field | Type | Description |
| -------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | |
| `title` | `String!` | Human-readable name of the field, for a UI that renders readings. Localized by design: the language comes from the request, not from an argument. Those headers are not honoured yet, so today the text does not vary by caller. Once they are, this field is the one part of a dictionary entry that is not stable across callers, and a client caching the dictionary caches it per locale. |
| `description` | `String` | Longer explanation of the field, localized on the same terms as `title`. |
| `valueType` | [TrackingValueType](#trackingvaluetype)! | |
| `unit` | `String` | Reference unit (UCUM): the one the quantity is customarily shown and stored in. Not a default for a value that arrived without one — `TrackingReading.unit` says when it stands in. Null for dimensionless fields. |
| `quantity` | [TrackingQuantity](#trackingquantity) | |
| `nature` | [TrackingFieldNature](#trackingfieldnature)! | |
| `channelled` | `Boolean!` | Whether values of this field can carry a channel number. |
| `computed` | `Boolean!` | Always computed by the platform rather than measured (e.g. `mileage`). |
| `counterScope` | [TrackingCounterScope](#trackingcounterscope) | For COUNTER fields: what the count runs from. |
| `resettable` | `Boolean` | For COUNTER fields: whether the counter can legitimately be reset (vs. wrapping around). |
| `deprecated` | `Boolean!` | |
| `replacedBy` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | |
| `aliases` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!]! | Field names this entry absorbed on the nvx3 → NTF migration. |
***
## Objects
### TrackingBoolValue
| Field | Type | Description |
| ----------- | ---------- | ----------- |
| `boolValue` | `Boolean!` | |
***
### TrackingIntValue
Signed integer of any width (int8…int64).
| Field | Type | Description |
| ---------- | ------------------------------------------------------------------- | ----------- |
| `intValue` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | |
***
### TrackingUIntValue
Unsigned integer of any width (uint8…uint64). Values above 2^63-1 — bitmasks, odometer-style counters, identifiers — do not fit `Long`, so the value rides the kernel's `Decimal` scalar, which already exists with a coercion and a validation path. A bare `String` would push the same parse onto the client with nothing checking it.
| Field | Type | Description |
| ----------- | ------------------------------------------------------------------------- | ----------- |
| `uintValue` | [Decimal](/docs/navixy-graphql-api/core-api-reference/common.md#decimal)! | |
***
### TrackingFloatValue
| Field | Type | Description |
| ------------ | -------- | ----------- |
| `floatValue` | `Float!` | |
***
### TrackingStringValue
| Field | Type | Description |
| ------------- | --------- | ----------- |
| `stringValue` | `String!` | |
***
### TrackingBytesValue
Opaque binary payload (raw CAN frame, RFID key), Base64-encoded.
| Field | Type | Description |
| ------------ | --------- | ----------- |
| `bytesValue` | `String!` | |
***
### TrackingTimestampValue
| Field | Type | Description |
| ---------------- | --------------------------------------------------------------------------- | ----------- |
| `timestampValue` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | |
***
### TrackingDurationValue
A duration. Carried by the kernel's `Duration` scalar, which this module introduces to `nvx4-common.graphql` — see the note at the head of this file. Every duration in this schema uses it, so `"5m"` instead of `PT5M` is rejected by coercion rather than by a resolver that may or may not check.
| Field | Type | Description |
| --------------- | --------------------------------------------------------------------------- | ----------- |
| `durationValue` | [Duration](/docs/navixy-graphql-api/core-api-reference/common.md#duration)! | |
***
### TrackingArrayValue
Homogeneous list (DTC codes, tachograph cards, acceleration vector).
| Field | Type | Description |
| -------- | ------------------------------------ | ----------- |
| `values` | \[[TrackingValue](#trackingvalue)!]! | |
***
### TrackingStructValue
Nested structure whose members are full readings (decoded J1939 frame, tachograph block).
| Field | Type | Description |
| -------- | ---------------------------------------- | ----------- |
| `fields` | \[[TrackingReading](#trackingreading)!]! | |
***
### TrackingClearedValue
The value was explicitly cleared. Its own variant so that "nothing was said" and "this no longer holds" can never be confused.
| Field | Type | Description |
| --------- | ---------- | ----------- |
| `cleared` | `Boolean!` | |
***
### TrackingReading
One named field of a state — a sensor reading, a device state, a counter, an identity. There is exactly one such list per state: NTF v1 has no inputs/states split.
| Field | Type | Description |
| -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | Dictionary name of the field, e.g. `lls_level`, `ignition`, `hw_mileage`. |
| `channel` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | Channel number for multi-channel fields (`lls_level` on tank 2), in `0..4294967295`. Null when the field has none. |
| `value` | [TrackingValue](#trackingvalue)! | |
| `unit` | `String` | Unit of this value (UCUM, e.g. `km`, `Cel`, `L/h`): the unit the message carried. For the four legacy fields the format names — `board_voltage`, `battery_voltage`, `battery_level`, `hw_mileage` — a message without a unit means the dictionary's unit by contract, and this field carries it. For every other field a message without a unit means "unknown", and this field is null: a dictionary `Cel` on `temperature` does not make a number that arrived without a unit degrees Celsius. So null covers both "dimensionless" and "unknown". `definition.unit` tells the two apart when the code is in the dictionary — a dimensionless field has none there. For a code the dictionary does not know, `definition` is null as well and the two cannot be told apart: the value has no unit a client may rely on. `definition.unit` is a reference value — the unit the quantity is customarily shown in — never a default for this one. |
| `declaredType` | [TrackingValueType](#trackingvaluetype) | The type that the sender declared for this value in its own source register. When the sender declared none, the type that the telemetry format fixes for this field name, if it fixes one. Null when it's the type that `value`'s own member already implies, unless the format fixes that same type for this field name. Also null when neither the sender nor the format gives a type. |
| `updatedAt` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | When this value was last received. A field carries no timestamp of its own — this is the event time of the message it last arrived in, which across a last-known state is *not* the same for every reading. |
| `definition` | [TrackingFieldDefinition](#trackingfielddefinition) | Dictionary entry behind `code`: title, nature, quantity, deprecation. Always null today: the field dictionary is not populated yet, so no code has an entry. `TrackingQuery.fieldDefinitions` returns an empty list for the same reason. |
***
### TrackingFieldDefinition
A field dictionary entry. Entries are never renamed, retyped or deleted — only deprecated with a pointer to the replacement, because an entry describes every value ever recorded under that name, not just new ones.
| Field | Type | Description |
| -------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | |
| `title` | `String!` | Human-readable name of the field, for a UI that renders readings. Localized by design: the language comes from the request, not from an argument. Those headers are not honoured yet, so today the text does not vary by caller. Once they are, this field is the one part of a dictionary entry that is not stable across callers, and a client caching the dictionary caches it per locale. |
| `description` | `String` | Longer explanation of the field, localized on the same terms as `title`. |
| `valueType` | [TrackingValueType](#trackingvaluetype)! | |
| `unit` | `String` | Reference unit (UCUM): the one the quantity is customarily shown and stored in. Not a default for a value that arrived without one — `TrackingReading.unit` says when it stands in. Null for dimensionless fields. |
| `quantity` | [TrackingQuantity](#trackingquantity) | |
| `nature` | [TrackingFieldNature](#trackingfieldnature)! | |
| `channelled` | `Boolean!` | Whether values of this field can carry a channel number. |
| `computed` | `Boolean!` | Always computed by the platform rather than measured (e.g. `mileage`). |
| `counterScope` | [TrackingCounterScope](#trackingcounterscope) | For COUNTER fields: what the count runs from. |
| `resettable` | `Boolean` | For COUNTER fields: whether the counter can legitimately be reset (vs. wrapping around). |
| `deprecated` | `Boolean!` | |
| `replacedBy` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | |
| `aliases` | \[[Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)!]! | Field names this entry absorbed on the nvx3 → NTF migration. |
***
## Enums
### TrackingValueType
Declared type of a value in terms of the *source* register. `navixy.telemetry.v1.ValueType`.
**Values:** `BOOL`
***
### TrackingFieldNature
What kind of quantity a field is, which decides how it may be aggregated. Dictionary metadata, not carried by the message.
| Value | Description |
| ------------- | ----------------------------------------------------------------------------------------- |
| `GAUGE` | Instantaneous measurement — averaging and medians are meaningful. |
| `COUNTER` | Monotonic accumulator; see `counterScope` and `resettable`. |
| `DELTA` | Increment since the previous report. |
| `STATE` | Holds until it changes — ignition, doors. Averaging is meaningless. |
| `BITSET` | Raw bitmask as sent by the device; bit layout belongs to the device model, not the field. |
| `IDENTITY` | Identity — VIN, driver card, ICCID. |
| `TEXT` | Free-form text. |
| `SUMMARY_MIN` | Summary over an interval whose bounds the device does not report. |
| `SUMMARY_MAX` | |
| `SUMMARY_AVG` | |
| `SETTING` | Device configuration value. |
***
### TrackingQuantity
Application-level quantity, from the field dictionary. Drives unit conversion and formatting.
***
### TrackingCounterScope
**Values:** `LIFETIME`, `TRIP`, `IGNITION_CYCLE`, `SINCE_RESET`
***
## Unions
### TrackingValue
How a reading is encoded. Mirrors `navixy.telemetry.v1.Value.value` — eight scalar variants, two composite ones, and an explicit clear.
An absent variant means the sender had nothing to say and the previous value stands; `TrackingClearedValue` is the opposite — an assertion that the value no longer holds (driver key pulled, trailer detached).
Each scalar variant names its field after the type — `boolValue`, `intValue`, … — instead of all sharing `value`. A selection set that reads `value` from two members with different scalars fails validation (`FieldsInSetCanMerge`, GraphQL spec §5.3.2), so a client rendering readings would have to alias the occurrences.
**One of:** [TrackingBoolValue](#trackingboolvalue), [TrackingIntValue](#trackingintvalue), [TrackingUIntValue](#trackinguintvalue), [TrackingFloatValue](#trackingfloatvalue), [TrackingStringValue](#trackingstringvalue), [TrackingBytesValue](#trackingbytesvalue), [TrackingTimestampValue](#trackingtimestampvalue), [TrackingDurationValue](#trackingdurationvalue), [TrackingArrayValue](#trackingarrayvalue), [TrackingStructValue](#trackingstructvalue), [TrackingClearedValue](#trackingclearedvalue)
***
## See also
* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.md)
* [Error handling](/docs/navixy-graphql-api/error-handling.md)
* [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md)
* [Limits](/docs/navixy-graphql-api/limits.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://navixy.com/docs/navixy-graphql-api/products/tracking/api-reference/readings.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.