Value

class tracdap.rt.metadata.Value

A value expressed in the TRAC type system.

A value can express a primitive value, or a composite value such as an array. Arbitrary nesting of composite types is permitted, although most functions will limit the set of acceptable types during validation.

Values include a type descriptor field. For primitive values the type descriptor is optional. For composite types the root value must include a full valid type descriptor, i.e. a descriptor that goes down to the leaf types. Sub-values in a composite type are free to omit the type descriptor, even if there are multiple levels of nesting, however any extra descriptors that are provided must also be full and valid.

TRAC will always provide values with the type descriptors “normalised”. This means that a root value will always have a type descriptor (even if it is a primitive type) and sub-values will never have a type descriptor. It is not necessary or preferred for application code to send values to TRAC with normalised type descriptors, TRAC will always perform normalisation.

See also

TypeDescriptor

arrayValue: ArrayValue | None

An array of Values.

All items in an array must have the same type.

See also

BasicType.ARRAY

booleanValue: bool | None

A boolean value.

Represented natively in both protobuf and JSON.

dateValue: DateValue | None

A date value.

See also

BasicType.DATE, DateValue

datetimeValue: DatetimeValue | None

A date-time value.

Date-times are represented as strings in ISO 8601 format.

Date-time values support nanosecond precision, however in practice the available precision may be less than this. In particular, tag attributes are always stored at microsecond precision. Values passed into models or used in application code will be limited to the precision supported by date-time types in their own coding language.

Time zone offsets are supported as described in ISO 8601. Date-time values should always include a zone offset to guarantee behaviour. If a zone offset is not supplied TRAC will normalized incoming values by applying a zone offset, currently the applied offset will be UTC.

See also

BasicType.DATETIME, DatetimeValue

decimalValue: DecimalValue | None

A decimal value with fixed precision and scale.

See also

BasicType.DECIMAL

floatValue: float | None

A 64-bit signed floating point value.

Represented natively in both protobuf and JSON.

integerValue: int | None

A 64-bit signed integer value.

Represented natively in both protobuf and JSON.

In JavaScript and JSON, native integers may be limited to less than full range of a 64 bit integer. This is because JavaScript has a single Number type that represents both integers and floats. The safe limit for integers that can be expressed without a risk of rounding in JavaScript is Number.MAX_SAFE_INTEGER.

mapValue: MapValue | None

A map of string keys to Values.

Maps may be uniform (holding all the same value type) or non-uniform (holding mixed value types) depending on the type descriptor of this Value.

See also

BasicType.MAP, TypeDescriptor

stringValue: str | None

A string value.

Protobuf encodes strings as UTF-8 on the wire. String values in JSON requests are also be encoded as UTF-8 on the wire, as per RFC 8259. When reading or writing string values in application code, they will be presented in the normal encoding scheme of application’s coding language.

type: TypeDescriptor

Type descriptor for the current value.

A type descriptor is always required for values that are the root of a composite type, otherwise it is optional.