Value Types

Values are the basic building blocks of the system’s information. They are immutable pieces of information defined by their contents and a set of equivalence rules that depend on their type. Values can be stored in the system and compared to other values of the same type.

The value type system is inspired by JSON Schema. While this document describes a sophisticated set of types, the actual implementation at any point in time is necessarily simpler, making appropriate trade-offs between capability and time to market.

Primitive Types

Primitive types are the basic building blocks of system information. All primitive types support equality comparison. Types labeled Ordered also support ordering and range comparisons.

Type	Ordered	Description
Boolean	Y	A binary state: true or false. May be presented as yes/no, on/off, 1/0.
Number	Y	A dimensionless number. Can be refined with minimum, maximum, allowed intervals, or specific values.
Integer	Y	A whole number. Always signed.
Decimal	Y	An approximation to a real number. Always signed. Precision can be defined as a type constraint.
String	Y	A sequence of UTF-8 characters. Can be refined with minlength, maxlength, or a regex pattern.
UUID	Y (by string convention)	A Universally Unique Identifier. Compared as a string for ordering.
Timezone	Y (alphabetical by IANA TZ identifier)	A timezone from the IANA Timezone Database.
DateTime	Y	A date with time in the Gregorian calendar in a particular Timezone, with millisecond precision.
Timestamp	Y	A DateTime expressed as milliseconds since Unix epoch (Jan 1, 1970 00:00:00.000 UTC).
Date	Y	A date in the Gregorian calendar in a particular Timezone.
Duration	Y	A length of time independent of the DateTime on which it may be applied. An integer number of milliseconds.
Interval	Y	A pair of DateTime values representing the start and end of a time period. Variants: open/closed boundaries.
Physical Measurement	Y (with restrictions)	A measurement of a physical quantity (length, weight, volume, etc.) with a physical magnitude and unit. Supports conversion between units of the same magnitude.
URI	Y (by string convention)	A Uniform Resource Identifier.
Email	N	An email address.
Phone	N	A phone number. Can be refined by country.
Postal Code	N	A postal code. Can be refined by country.
Quantity	Y (with restrictions)	A specific amount of an item, always with a Number value and a Unit of Measure defined in the context of the item it measures. Always has a representation in a standard UoM for the item.
Reference	N	A reference to an entity or a specific version of an entity. Specializations: EntityId (floating), RecordId (pinned). See Entity References.
TimeCoordinates	Y (with restrictions)	A pair of effective and recorded times. See Journaled Entities for semantics.

Notes on Primitive Types

• TimeCoordinates: Effective time is when the change becomes effective for business logic; recorded time is when the change is recorded by the system.
• Quantity: A Quantity always refers to a specific item. Quantities for different items cannot be directly added.
• Physical Measurement: The range of supported physical magnitudes will grow as requirements evolve. Unit conversion is supported for values of the same magnitude.
• Additional time-related types (standard periods, recurring events) will be added in the future.

Composite Types

Individual values can be combined to create more complex information structures. Composite values are immutable — operations on them produce new values.

Combination	Description
Array	An ordered collection of values of the same type. Values are equal only if the order and values of their elements are the same.
Set	An unordered collection of values of the same type. Values are equal if they contain the same elements in any order.
Dictionary	An unordered collection of key-value pairs where keys are unique Strings and values can be of any type. Values are equal if all key-value pairs are equal.
Map	A Dictionary where all values are the same type.
Tuple	An ordered collection of values of different types. A Pair is a Tuple with two elements. Values are equal if all elements are equal in order.
Variant	A value that can be one of a defined set of types, with clear attribution rules. May include an explicit discriminator (Integer or String) to identify the active type.

Composite types are generally not considered Ordered.

Note on JSON Schema Compatibility

JSON Schema supports oneOf (equivalent to Variant), as well as anyOf and allOf. The Arda type system does not include anyOf and allOf because their attribution rules are not well-defined enough for reliable implementation. Their future inclusion is TBD.

Value Equality

For all types, equality is defined as follows:

Type(s)	Equality
Boolean, Integer, String	Standard equality of the underlying type
Decimal	Equal if their difference is below a defined tolerance (default: 1e-18)
UUID, Timezone, URI, Email, Phone, Postal Code	Equal if string representations are equal
DateTime, Timestamp, Duration	Equal if millisecond representations are equal
Date	Equal if millisecond representation at 00:00:00.000 in respective timezone is equal
Interval	Equal if start and end DateTime values are equal
Physical Measurement	Equal if value expressed in standard unit is equal
Quantity	Equal if they refer to the same item and their value in standard unit is equal
Array, Tuple	Equal if same number of elements and each element is equal in order
Set	Equal if there is a bijection pairing all elements as equal
Dictionary, Map	Equal if key sets are equal (as sets) and each key maps to an equal value
Variant	Equal if the resolved type is equal and the discriminator value (if any) is equal