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 is frozen is an entry's identity — its type, unit and nature never change, and an entry is never renamed — so a cached entry never starts meaning something else. What is not frozen is the dictionary's composition: it changes by design, 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).
fieldDefinitions(
codes: [Code!]
includeDeprecated: Boolean = false
): [TrackingFieldDefinition!]!Arguments
includeDeprecated
Boolean
Include entries marked deprecated.
Output types:
Objects
TrackingBoolValue
boolValue
Boolean!
TrackingIntValue
Signed integer of any width (int8…int64).
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.
TrackingFloatValue
floatValue
Float!
TrackingStringValue
stringValue
String!
TrackingBytesValue
Opaque binary payload (raw CAN frame, RFID key), Base64-encoded.
bytesValue
String!
TrackingTimestampValue
TrackingDurationValue
A duration, carried by the Duration scalar. 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.
TrackingArrayValue
Homogeneous list (DTC codes, tachograph cards, acceleration vector).
TrackingStructValue
Nested structure whose members are full readings (decoded J1939 frame, tachograph block).
TrackingClearedValue
The value was explicitly cleared. Its own variant so that "nothing was said" and "this no longer holds" can never be confused.
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: readings are not split into inputs and states.
channel
Channel number for multi-channel fields (lls_level on tank 2), in 0..4294967295. Null when the field has none.
unit
String
Unit of this value (UCUM, e.g. km, Cel, L/h): the unit the message carried. For four legacy fields — 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
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
When this value was last received. A reading 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
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.
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 — X-Locale or Accept-Language, with English as the fallback. 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.
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.
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).
resettable
Boolean
For COUNTER fields: whether the counter can legitimately be reset (vs. wrapping around).
deprecated
Boolean!
Enums
TrackingValueType
Declared type of a value in terms of the source register.
Values: BOOL
TrackingFieldNature
What kind of quantity a field is, which decides how it may be aggregated. Dictionary metadata, not carried by the message.
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: 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, TrackingIntValue, TrackingUIntValue, TrackingFloatValue, TrackingStringValue, TrackingBytesValue, TrackingTimestampValue, TrackingDurationValue, TrackingArrayValue, TrackingStructValue, TrackingClearedValue
See also
Last updated
Was this helpful?